Getting Started

Step 1: Add the SDK to your Project

You have several options for integrating the Player SDK into your project:

Using Swift Package Manager (recommended)

Swift Package Manager is a tool for managing the distribution of Swift frameworks. It integrates with the Swift build system to automate the process of downloading, compiling, and linking dependencies.

Using Xcode

To integrate using Xcode 14.1 open your Project file and specify it in Project > Package Dependencies using the following URL:

https://github.com/bitmovin/player-ios.git

Using Package.swift

To integrate using Apple's Swift package manager, add the following as a dependency to your Package.swift file and replace the Version Number with the desired version of the SDK.

.package(url: "https://github.com/bitmovin/player-ios.git", exact: "Version Number")

Then specify BitmovinPlayer as a dependency of the desired target. Here is an example of a Package.swift file:

let package = Package(
  ...
  dependencies: [
    .package(url: "https://github.com/bitmovin/player-ios.git", exact: "Version Number")
  ],
  targets: [
    .target(name: "<NAME_OF_YOUR_PACKAGE>", dependencies: [.product(name: "BitmovinPlayer", package: "player-ios")])
  ]
  ...
)

⚠️ Note: Executing swift build from the command line is currently not supported. Open the Package in Xcode if you are developing another Package depending on BitmovinPlayer.

Using CocoaPods

Add the following lines to the Podfile of your project and replace the Version Number with the desired version of the SDK. All available versions from 3.77.0 on are listed in the Cocoapods trunk repository (earlier versions are listed in our CocoaPods repository instead).

Execute pod install to install the new BitmovinPlayer dependency.

pod 'BitmovinPlayer', 'Version Number'

Adding the SDK to your project directly

As an alternative to CocoaPods and SPM, you can download our XCFrameworks from our CDN and include them manually. Replace the VERSION_NUMBER with your desired version of our SDKs.

https://cdn.bitmovin.com/player/ios_tvos/VERSION_NUMBER/BitmovinPlayer.zip
https://cdn.bitmovin.com/player/ios_tvos/VERSION_NUMBER/BitmovinPlayerAnalytics.zip
https://cdn.bitmovin.com/player/ios_tvos/VERSION_NUMBER/BitmovinPlayerCore.zip
https://cdn.bitmovin.com/analytics/ios_tvos/VERSION_NUMBER/BitmovinAnalyticsCollector.zip

Using Xcode, just drag and drop the desired XCFrameworks into your project and ensure they are embedded in your Application. Depending on your use case, you need to add the following XCFramework files in your application.

Player with pre-integrated analytics

We suggest to leverage our pre-integrated Player and Analytics bundle, where you will need the following frameworks:

• BitmovinPlayerCore
• BitmovinPlayer
• BitmovinPlayerAnalytics
• CoreCollector
• BitmovinCollector

Player only

If you are only interested in the Player without analytics, you only need to include the BitmovinPlayerCore framework.

Player with a manual analytics integration

If you prefer to manually set up the analytics integration with the Player, you can omit the Player and Analytics bundle and only need the following frameworks:

• BitmovinPlayerCore
• CoreCollector
• BitmovinCollector

Step 2: Set up the Player

Configure the player license key

Add your player license key to the <dict> in the Info.plist:

<key>BitmovinPlayerLicenseKey</key>
<string>PLAYER_LICENSE_KEY</string>

Alternatively, you can also add the license key programmatically to the PlayerConfig via PlayerConfig.key.

Create the Player

You can create a Player instance with analytics tracking either with the default configuration,

// Enable Analytics by creating an AnalyticsConfig with your license key
let analyticsConfig = AnalyticsConfig(licenseKey: "<ANALYTICS_LICENSE_KEY>")

// Player using a default config
let player = PlayerFactory.createPlayer(
  analytics: .enabled(analyticsConfig: analyticsConfig)
)

or using a custom config:

// Or with a explicit PlayerConfig
let playerConfig = PlayerConfig()
playerConfig.key = "<PLAYER_LICENSE_KEY>" // Only needed if the license key was not added to the Info.plist file

let player = PlayerFactory.createPlayer(
    playerConfig: playerConfig,
    analytics: .enabled(analyticsConfig: analyticsConfig)
)

Configure the Source

Creating a SourceConfig based on a given Stream URL:

// Create the HLS stream URL
guard let streamUrl = URL(string: "https://cdn.bitmovin.com/content/art-of-motion/m3u8s/playlist.m3u8") else {
    return
}

// Create a SourceConfig
let sourceConfig = SourceConfig(url: streamUrl, type: .hls)

// Optionally set additional properties
sourceConfig.title = "Art of motion"

Load the Source

Load the created Source into the Player:

// Create a Source from the SourceConfig
let source = SourceFactory.createSource(from: sourceConfig)

player.load(source: source)

Note: When there is no need to access the Source instance before loading it, it is also possible to directly load a SourceConfig into the Player:

player.load(sourceConfig: sourceConfig)

Create a PlayerView using SwiftUI or UIKit

Create a view that is provided by the SDK with either SwiftUI or UIKit. This view will be used for rendering the video:

// Create the VideoPlayerView where the video will be rendered
VideoPlayerView(player: player)

// Create a PlayerView
let playerView = PlayerView(player: player, frame: view.bounds)

// Depending on your App layout you might want to set the autoresizingMask (recommended)
playerView.autoresizingMask = [.flexibleHeight, .flexibleWidth]

// Adding the view to the a container View
playerContainerView.addSubview(playerView)
playerContainerView.bringSubview(toFront: playerView)

See our examples for more details. There, you can find simple SwiftUI sample applications, including BasicPlayback for iOS, BasicPlaybackTV for tvOS and BasicPlaybackVisionOS for visionOS. For UIKit support, have a look at our BasicUIKit sample for iOS and BasicUIKitTV sample for tvOS.

See listening to events for details on how to get notified about certain events from the Player.

Step 3: Configure your Player and Analytics License

Allowlist your Bundle Identifiers

In order to use the player with analytics in your app, you have to allowlist the bundle identifier of your app into which you are integrating the SDK. This is a security mechanism and protects your license from being used elsewhere.

Allowlisting can be done in the Dashboard under Player > Licenses and Analytics > Licenses.

Summary

In this tutorial, you've learned how to add the Bitmovin Player SDK to your project, set up the player and analytics license, and how to configure and use the Player.

Next, you can

• browse our API reference.
• download fully working examples and explore more features in our GitHub repository.
• choose additional platforms to deploy on in our Getting Started Hub and try our no-code wizards.
• get real-time insights into your Player via our Analytics Dashboard.
• see if some of the questions you might have are answered in our Community and ask your own!