tvOS - Native Player

Datazoom is a high-availability real-time data collection solution. This document summarizes how to integrate the tvOS Media Player with the Datazoom platform.

1. Login to Datazoom here:  https://app.datazoom.io
   
2. Add a Collector as indicated here:  How to add a Collector
   
   
3. Copy the config key that was created at the end of the process
   Click the icon indicated below to copy the Configuration Key
   
   You will see this message:
   

     4. Replace the <configuration id from Datazoom> in Datazoom's  DZNativeCollector.framework file with the Key you copied above.

     5. Replace the <url given by Datazoom> with <https://platform.datazoom.io/beacon/v1/>

     6. Replace the <AVPlayer Object> with your playerInstance identifier

Prerequisites

• tvOS version 12.1+

• XCode version 13.1+ ( Swift 5.5.1+ )

Installation

The preferred way of installing DZCollectorTvOSNative is via the Swift Package Manager.

Using Swift Package Manager

• Open/Create project in XCode

• Add Swift Package Dependecy - navigate to File → Swift Packages → Add Package Dependency...
  

  

• Paste the repository URL (datazoom/apple-tvos/dz-tvos-multi-native-framework ) and click Next.
  

  

• For Rules, select Branch (with branch set to main).
  

  

• Click Finish.

• Open the Project settings, add DZCollectorTvOSNative.framework to the Linked Frameworks and Libraries, set Status to Optional.

Optional usage of Google IMA Ads

• Download from https://developers.google.com/interactive-media-ads/docs/sdks/tvos/client-side/download

• Import the framework using the following command:
  

  import GoogleInteractiveMediaAds

Using CocoaPods

• Open the terminal and check if Cocoapods is installed in your machine.

  pod --version

• If the above command returns no version number, then you'll need to install CocoaPods. 

  sudo gem install cocoapods

• After installation, navigate to the Xcode project directory and create aPodfile configuration file if not present.

  pod init

• Run the command:

  open Podfile

• Add the DZNativetvOS pod in the Podfile

  source 'https://gitlab.com/datazoom/pod-specs.git'
  pod 'DZNativetvOS','2.0.2'

• Pull and update the latest Cocoapods pod specs

  pod repo update

• Install the pods

  pod install

• Be sure to close any current Xcode sessions and use `your_project_name.xcworkspace` for this project from now on.

Using XCFramework

• Download DZ_Collector_tvOS.xcframework file from here .

• Drag and drop the downloaded frameworks into your Xcode project. Drag the file to the files inspector on the left side of Xcode. Make sure you check the box "Copy items" in the popup menu that displays while drag and drop the file.

• In selected Xcode target, go to the General tab and scroll down to Frameworks, Libraries and Embedded Content (Embedded Binaries in older Xcode versions). Make sure that the framework added in the above step is present. If not present, add the framework by clicking the "+" button available at the same section. Also, make sure that Embed option is set to Embed & Sign.

Steps for ObjectiveC Language based Applications

• After including the framework file, Create a bridging header file, to allow interoperability of languages.

• open the ViewController/View file, where the AVPlayer(native player) is included.

• Import the following:

  #import <AVKit/AVKit.h> 
  #import <AVFoundation/AVFoundation.h> 
  #import "DZ_Collector_tvOS/DZ_Collector_tvOS-Swift.h"

• Sample of collector initialization:

  DZNativeCollector *collector = [DZNativeCollector alloc];
      
  [collector initializeWithConfigID:@"<configuration id from Datazoom>"  url:@"<url provided by Datazoom>" onCompletion:^(BOOL, NSError * _Nullable) {
      printf("Initialization done") ;
  }];

Usage - Steps for Swift Language based Applications:

Import and initialization of framework and player

• Import the framework using the following command:

  import DZ_Collector_tvOS

• Initialize the framework by passing along the 'Configuration ID' and url:

  func initialize(configurationId: String, url:String, _ completion: @escaping (Bool,Error?) -> Void)

  Example:

  let collector = DZNativeCollector()
  
  collector.initialize(configurationId: libConfig.configurationId, url: libConfig.apiEndpoint, { success, error in
        if success == true {
            // init done
        }
        else {
            if let error = error {
                // init error
            }
        }
    })

• Create and Initialize native player with videoUrl:

  func initPlayer(url: String, _ completion: ((String?, AVPlayer?, Error?) -> Void)?) 

  Example:

  collector.initPlayer(url: videoUrl, { playerId, player, error in
        if let playerId = playerId, let player = player {
            // store playerId for future referencing the player
  ...
            let playerViewController = AVPlayerViewController()
            playerViewController.player = player
  ...
        }
    })

• Create and Initialize native player with videoUrl and sending player custom metadata:

  func initPlayer(url: String, metadata: [String:Any]?, _ completion: ((String?, AVPlayer?, Error?) 

  Example:

  collector.initPlayer(url: videoUrl, metadata: ["CustomPlayerMetadata", "MetadataValue"], { playerId, player, error in
        if let playerId = playerId, let player = player {
            // store playerId for future referencing the player
  ...
            let playerViewController = AVPlayerViewController()
            playerViewController.player = player
  ...
        }
    })

• Init player after creation:

  func initPlayer(player: AVPlayer, _ completion: ((String?, Error?) -> Void)?)

• Example:

  var controller = AVPlayerViewController()
  let contentUrl = URL(string: videoUrl)
  var player = AVPlayer(url: contentUrl!)
          
  collector.initPlayer(player: player, { playerId, error in
      if let playerId = playerId {
          // store playerId for future referencing the player
  ...
      }
  })

• Init player after creation and sending player custom metadata:

  func func initPlayer(player: AVPlayer, metadata: [String:Any]?, _ completion: ((String?, Error?) -> Void)?)

• Example:

  var controller = AVPlayerViewController()
  let contentUrl = URL(string: videoUrl)
  var player = AVPlayer(url: contentUrl!)
          
  collector.initPlayer(player: player, metadata: ["CustomPlayerMetadata", "MetadataValue"], { playerId, error in
      if let playerId = playerId {
          // store playerId for future referencing the player
  ...
      }
  })

• Starting and stoping collecting data for specific player:

  // start collecting data
  func startCollectingData(playerContext: String)
  
  // stop collecting data
  func stopCollectingData(playerContext: String)

• Example:

  // stop collecting data
  collector.stopCollectingData(playerContext: playerId) // playerId is previously stored after initPlayer
  
  // start collecting data
  collector.startCollectingData(playerContext: playerId)

Using custom metadata

• All metadata are in dictionary format and all are optional

  var metadata: [String:Any]?

• Get, set and clear specific type of metadata with methods:

  // Custom session metadata
  func getSessionCustomMetadata() -> [String:Any]?
  func setSessionCustomMetadata(_ metadata:[String:Any]?) 
  func clearSessionCustomMetadata()
  
  // Custom player metadata
  func getPlayerCustomMetadata(playerContext: String) -> [String : Any]?
  func setPlayerCustomMetadata(playerContext: String, _ metadata: [String : Any]?)
  func clearPlayerCustomMetadata(playerContext: String)

  Example:

  // Custom session metadata
  collectorgetSessionCustomMetadata()
  collector.setSessionCustomMetadata(["Session Custom Name","My Session Data"])
  collector.clearSessionCustomMetadata()
  
  // Custom player metadata
  collector.getPlayerCustomMetadata(playerContext: playerId) // playerId is previously stored after initPlayer
  collector.setPlayerCustomMetadata(playerContext: playerId, ["Session Custom Metadata","Lorem ipsum"])
  collector.clearPlayerCustomMetadata(playerContext: playerId)

Using custom events

• Custom event metadata are in dictionary format and all are optional

  var metadata: [String:Any]?

• Sending custom event with CustomEventName and CustomEventMetadata with method:

  func sendCustomEvent(name: String, metadata: [String : Any]?)

  Example:

  func buttonPushTouched() {      
    collector.sendCustomEvent(eventName: "CustomEventExample", metadata: ["customPlayerName":"NativePlayer","customDomainName":"datazoom.io"])
  }