Articles in this section

See more

AVPlayer Media Player ##Extension v2 of the iOS / tvOS Collector

Avatar
Tony Gentile
  • Updated
Follow

##dz-db-collector-details

Prerequisites

  • iOS / tvOS version 12.1+

  • XCode 14.1+ ( Swift 5.7.1+ )

Installation

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

Using Swift Package Manager

  • Open/Create a project in XCode

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

  • Paste the repository URL: https://gitlab.com/datazoom/apple/libraries-release/apple_avplayer

  • For Rules, select Branch (with branch set to main) and click Add Package.

  • On the confirmation dialog click Add Package, again.

  • Check if the library is added to the project

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 a Podfile configuration file if not present.

    pod init

  • Run the command:

    open Podfile

  • Add the DZCollector pod in the Podfile

    source 'https://gitlab.com/datazoom/pod-specs.git'
pod 'DZNativeUnified'

  • Pull and update the latest Cocoapods pod specs

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

Using XCFramework (manually)

  • Download latest version of DZ_Collector.xcframework.zip file from here, and unpack.

  • 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 the 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 in the same section. Also, make sure that Embed option is set to Embed & Sign.

Usage for Swift Language-based Applications

Import and initialization of framework

Importing the framework using the following command:

import DZ_Collector

Initialize the framework by passing along ConfigurationId (provided by Datazoom)

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

Example:

let collector = DZCollector()

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

Custom Events & Metadata

Datazoom allows customers to collect custom events and custom metadata that don't originate from a video player. Once the framework is successfully initialized you should be able to send custom events and set custom metadata. Note that custom metadata can be attached to Datazoom generated events or your own custom events.

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

Example: (using your own custom event)

let collector = DZCollector()
let name = "SOME CUSTOM EVENT"
let data = "SOME CUSTOM METADATA"     
collector.sendCustomEvent(name: name, metadata: data{ success, error in
      if success == true {
          // Custom event sent
      }
      else {
          if let error = error {
              // custom event error
          }
      }

})

If we want to attach custom metadata or event to a specific player context we can use the following method:

let collector = DZCollector()
let name = "SOME CUSTOM EVENT"
let data = "SOME CUSTOM METADATA"
let playerContext = "SOME PLAYER CONTEXT UUID"                 
collector.sendCustomEvent(playerContext: playerContext, name: name, metadata: data{ success, error in
      if success == true {
          // Custom event sent
      }
      else {
          if let error = error {
              // custom event error
          }
      }

})

Separately we can also set, read, and clear app session related custom metadata by using the following methods:

    func setSessionCustomMetadata(_ metadata:[String:Any]?)
    func getSessionCustomMetadata() -> [String:Any]?
    func clearSessionCustomMetadata()

We can also set, read, and clear player instance related custom metadata by using the following methods:

    func setPlayerCustomMetadata(playerContext: String, _ metadata:[String:Any]?)
    func getPlayerCustomMetadata(playerContext: String) -> [String:Any]?
    func clearPlayerCustomMetadata(playerContext: String)

Initialization of player

There are several methods to initialize a player, depending on customer needs.

Please note: In order to successfully collect player dimensions playerView MUST be included in initialization process.

  • Create and Initialize AVPlayer with url:

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

    Example:

    collector.initPlayer(url: url, { playerId, player, error in
      if let playerId = playerId, let player = player {
      // initialization done
      // playerId - playerContext - using latter referring to player
      // player - AVPlayer instance
      }
      else {
      // error - error during initialization
      }
  })

  • Create and Initialize AVPlayer with url and send player custom metadata:

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

    Example:

    let playerMetadata: [String: Any]? = ["custom_player_metadata": "metadata"]

collector.initPlayer(url: videoUrl, metadata: playerMetadata, { playerId, player, error in
      if let playerId = playerId, let player = player {
      // initialization done
      // playerId - playerContext - using latter referring to player
      // player - AVPlayer instance
      }
      else {
      // error - error during initialization
      }
  })

    • Initialize with already created AVPlayer:

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

      Example:

      collector.initPlayer(player: player, { playerId, error in
      if let playerId = playerId {
      // initialization done
      // playerId - playerContext - using latter referring to player
      }
      else {
      // error - error during initialization
      }
  })

    • Initialize with already created AVPlayer and send player custom metadata:

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

      Example:

      let playerMetadata: [String: Any]? = ["custom_player_metadata": "metadata"]

collector.initPlayer(player: player, metadata: playerMetadata, { playerId, error in
      if let playerId = playerId {
      // initialization done
      // playerId - playerContext - using latter referring to player
      // player - AVPlayer instance
      }
      else {
      // error - error during initialization
      }
  })

De-initialization of player

In cases where a playlist reaches it’s natural end, it’s required that you call this method to ensure the final stop event fires.

func deinitPlayer(playerContext: String,_ completion: ((Bool, Error?) -> Void)?)

Example:

collector.deinitialize(playerContext: playerContext, { success, error in
      if success == true {
          // player deinit done
      }
      else {
          if let error = error {
              // player deinit error
          }
      }
  })

Usage of Google IMA Ads

func initAds(adUrl: String, controller: AVPlayerController, playerContext: String, contentDuration: Float = 0, _ completion: ((Bool, Error?) -> Void)?) {
    let ad: DZAdDataIMA = DZAdDataIMA(playerContext: playerContext)
    ad.delegate = self
    ad.requestAds(url: adUrl, controller: controller, contentDuration: contentDuration)
        completion?(true, nil)
  }


Related articles

Comments

0 comments

Please sign in to leave a comment.