API Docs Reference: https://cdn.bitmovin.com/analytics/ios/3.0.0/docs/index.html

How to set up the iOS/tvOS/visionOS Collector

Bitmovin Analytics enables you to get useful insights into the video experience in your apps. The Bitmovin Player for iOS, tvOS and visionOS includes Analytics pre-integrated. Players like AVPlayer and the Amazon IVS player can be tracked through our player-specific collectors.

In order to complete this guide, you need at least a basic setup of your chosen player. If you haven't set up your Player yet, go to the corresponding Player documentation page first: Bitmovin Player getting started guide, AVPlayer documentation, Amazon IVS Player documentation.

You also need to set up your analytics license and allowlist your domain. If you haven't done this yet, go to our How to Set Up page and follow the steps there.

Platform Support

SPM is supported since 2.8.0.

Bitmovin Player

Step 1: Configure Analytics

Starting with version 3.42.0 of the player, Analytics comes pre-integrated in the player. You just need to enable Analytics during creation of the Player.

Enable Analytics for the Player

For a minimal setup, only the license key needs to be specified. For more analytics configuration see here.
This minimal setup is enough to enable basic tracking.

let analyticsConfig = AnalyticsConfig(licenseKey: "<ANALYTICS_LICENSE_KEY>")
let player = PlayerFactory.createPlayer(
    playerConfig: playerConfig,
    analytics: .enabled(analyticsConfig: analyticsConfig)
)

Enrich analytics data with Metadata

In order to enrich analytics with more data, DefaultMetadata and SourceMetadata can be set.

DefaultMetadata can be set during player creation, and this contains source independent data.

For example:

let defaultMetadata = DefaultMetadata(
    customUserId: "userId",
    customData: CustomData(
     	  customData2: "ExampleGenre"
    )
)
let player = PlayerFactory.createPlayer(
    playerConfig: playerConfig,
    analytics: .enabled(
        analyticsConfig: analyticsConfig,
        defaultMetadata: defaultMetadata
    )
)

SourceMetadata can be set for each source to add more source-specific metadata.

let sourceMetadata = SourceMetadata(
    videoId: "exampleId",
    title: "stream title",
    customData: CustomData(customData2: "ExampleGenre")
)

let source = Source.createSource(from: sourceConfig, sourceMetadata: sourceMetadata)
player.load(source: source)

Step 2: Check Statistics in Dashboard

After the setup is done there's nothing more to do. Events are recorded automatically and you can head over to the Analytics Dashboard to see your metrics.

3rd Party Players

Step 1: Add the SDK to your project

SwiftPM

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.

We support Swift Package Manager since 2.8.0

We provide the following products:

• AVFoundationCollector including AVPlayer Collector
• AmazonIVSCollector including the Amazon IVS Player Collector

Using Xcode

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

https://github.com/bitmovin/bitmovin-analytics-collector-ios

Using Package.swfit

You can also add us manually. For that you need to add the following package as a dependency to your Package.swift and replace the Version Number with the desired version of the SDK.

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

And then specify the BitmovinAnalytics package 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/bitmovin-analytics-collector-ios", exact: "Version Number")
  ],
  targets: [
    .target(
      name: "<NAME_OF_YOUR_PACKAGE>",
      dependencies: [
        .product(name: "AVFoundationCollector", package: "bitmovin-analytics-collector-ios")
        // OR
        .product(name: "AmazonIVSCollector", package: "bitmovin-analytics-collector-ios")
      ]),
  ]
  ...
)

Limitations

Executing swift build from the command line is currently not supported. Open the Package in Xcode if you are developing another Package depending on BitmovinAnalytics.

How to import the collector

We have split the BitmovinAnalytics package into 4 targets

• CoreCollector - including shared code for all collectors
• AVFoundationCollector
• AmazonIVSCollector

if you are working with our Collectors you need to add at least import CoreCollector because many Classes are relocated to that package. Going further you need to import the corresponding Collector package for your player.

import CoreCollector
import AVFoundationCollector

import CoreCollector
import AmazonIVSCollector

CocoaPods

BitmovinAnalyticsCollector is available through CocoaPods. We depend on cocoapods version >= 1.4.

Add the following lines to the Podfile of your project while replacing VERSION_NUMBER with the desired version of the SDK. All available versions are listed in the cocoapod repository.

Run pod repo update to add the newly added source and run pod install to install it.

source 'https://github.com/bitmovin/cocoapod-specs.git'

pod 'BitmovinAnalyticsCollector/Core', 'VERSION_NUMBER'
pod 'BitmovinAnalyticsCollector/AVPlayer', 'VERSION_NUMBER'

source 'https://github.com/bitmovin/cocoapod-specs.git'

pod 'BitmovinAnalyticsCollector/Core', 'VERSION_NUMBER'
pod 'BitmovinAnalyticsCollector/AmazonIVSPlayer', 'VERSION_NUMBER'

Step 2: Setup the Collector

Configuration

First you need to create a config and metadata which will configure the collector and provide some information used during the lifetime of this collector instance. For more information checkout our Configuration Guide.

Please replace ANALYTICS_LICENSE_KEY with a license key from your account. Please checkout How to set up to learn more about how to get to your analytics license.

let config = AnalyticsConfig(licenseKey: "<ANALYTICS_LICENSE_KEY>")
let metadata = DefaultMetadata(customUserId:"custom-user-id")

Collector

Next you need to create our collector and pass it the config and metadata

let analyticsCollector = AVPlayerCollectorFactory.create(config: config, defaultMetadata: metadata)

let analyticsCollector = AmazonIVSPlayerCollectorFactory.create(config: config, defaultMetadata: metadata)

Attach the collector

As soon as the player is created you have to attach the collector to the player.

analyticsCollector.attach(to: player)

Amazon IVS Collector

In order to get notified by the player events we will set an internal class to be the delegate of the player. If you also want to get notified by the player event we ask you to set your Delegate before you attach the collector to the player. We will keep a weak reference to your delegate and call it once our code is finished. Once you call detach() on the collector we reassign your delegate to the player

class CustomDelegate: IVSPlayer.Delegate {.....}

let delegate = CustomDelegate()
player.delegate = delegate
analyticsCollector.attach(to: player)

Step 3: Check Statistics in Dashboard

After the setup is done there is nothing more to do. Events are recorded automatically and you can head over to the analytics dashboard to see statistics.

Examples

You can find fully functional code examples in our Github Repository.