Datazoom is a high-availability real-time data collection solution. This document summarizes how to integrate the Bitmovin iOS/tvOS video player with the Datazoom platform.
Login to Datazoom here: https://app.datazoom.io
Add a Collector as indicated here: How to add a Collector
Copy the
config keythat was created at the end of the process
Click the icon indicated below to copy the Configuration Key
Prerequisites
iOS / tvOS version 14.0+ (Bitmovin Player, ver. 3.40.0 )
XCode 14.1+ ( Swift 5.7.1+ )
Installation
The preferred way of installing DZCollector is via the Swift Package Manager.
Dependencies
Our framework has one dependency - Bitmovin Player SDK.
The latest version of DZCollector was built against Bitmovin Player SDK version 3.40.0
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_bitmovin
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 'DZBitmovinUnified'
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 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
}
}
})
Sending custom events and setting custom metadata
Once the framework is successfully initialized you should be able to send custom events and set custom metadata.
func sendCustomEvent(name: String, metadata: [String: Any]?)
Example:
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 connect 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.
Create and Initialize Bitmovin Player with url:
func initPlayer(url: String, playerView: UIView, license:String, _ completion: ((String?, Player?, Error?) -> Void)?)
Example:
collector.initPlayer(url: videoUrl, playerView: playerContainerView, license: key, { playerId, player, error in if let playerId = playerId, let player = player { // initialization done // playerId - playerContext - using latter referring to player // player - Bitmovin Player instance } else { // error - error during initialization } })Create and Initialize Bitmovin Player with url and send player custom metadata:
func initPlayer(url: String, playerView: UIView, license: String, metadata: [String:Any]?, _ completion: ((String?, Player?, Error?) -> Void)?)
Example:
let playerMetadata: [String: Any]? = ["custom_player_metadata": "metadata"] collector.initPlayer(url: videoUrl, playerView: playerContainerView, license: key, metadata: playerMetadata, { playerId, player, error in if let playerId = playerId, let player = player { // initialization done // playerId - playerContext - using latter referring to player // player - Bitmovin Player instance } else { // error - error during initialization } })Initialize with already created Bitmovin Player:
func initPlayer(player: Player, _ 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 Bitmovin Player and send player custom metadata:
func initPlayer(player: Player, 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 - Bitmovin Player instance } else { // error - error during initialization } })
De-initialization of player
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
}
}
})
De-initialization of framework
func deinitialize()
Example:
collector.deinitialize()
Usage of Google IMA Ads
Download Client-Side SDK from:
Add the framework
Import the frameworkbitmovin
Add advertising configuration to player configuration (Bitmovin sample - BasicAds)
Example:
let playerConfig = PlayerConfig() ... let adTagVast1 = "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=".urlWithCorrelator() let adSource1 = AdSource(tag: adTagVast1, ofType: .ima) let preRoll = AdItem(adSources: [adSource1], atPosition: "pre") let adConfig = AdvertisingConfig(schedule: [preRoll]) playerConfig.advertisingConfig = adConfig ...
Comments
0 comments
Article is closed for comments.