iOS - Media Player framework

Datazoom is a high-availability real-time data collection solution. This document summarizes how to integrate the iOS 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:
   

Initial setup 

Using XCFramework

• Download DZ_Collector_iOS.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.

Using Swift Package Manager

• In your code project select File > Add Packages and in Search or Enter URL field enter:

https://gitlab.com/datazoom/apple-ios-mobile/dzcollectorios-spm

• If you plan to collect ad-related events using Google Interactive Media Ads (IMA) framework, please use this URL instead:

https://gitlab.com/datazoom/apple-ios-mobile/dz_collector_av_ima.git

Note: To use GoogleIMA enabled framework you must have GoogleIMA framework installed already in your project, otherwise the build process will fail.

• Set dependency rule to Branch main and specify name of your project.

• On the next screen, Choose package products, make sure that DZ_Collector_iOS is selected and click on Add package.
  

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 DZNativeGold pod in the Podfile
  

  pod 'DZNativeGold','2.0.0',:source=>'https://gitlab.com/datazoom/pod-specs.git'

• 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.

Steps for Swift Language based Applications

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

• Import the framework using the following command:

  import DZ_Collector_iOS

• Initialize the framework by passing along the 'Configuration ID', and URL given by Datazoom. Completion handler will return two values, success and error if happened.

  let collector = DZ_Collector(configID: <configuration id from Datazoom>, url: <url provided by Datazoom>)
  collector.start(completion: @escaping (Bool, Error?) -> ())

• You can start recording events for your AVPlayer instance using this API call. 

  collector.startRecordingEvents(for: <AVPlayer object>)

• You can also stop recording events of your AVPlayer instance using similar API call. 

  collector.stopRecordingEvents(for: <AVPlayer object>)

• To stop recording event for ALL active AVPlayer instances use:

  collector.stopRecordingEvents()

• Run the app and observe the events captured in a Collector, data corresponding to MOBILE/iPhone in Platform, refers to the events tracked from iPhone.

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_iOS;

• Initialize the swift class in the .h file.

  DZ_Collector *collector;

• In the .m file, allocate using:

  collector = [[DZ_Collector alloc]initWithConfigId: <configuration id from Datazoom>, url: <url provided by Datazoom>]; 
  [collector startWithCompletion: ^(BOOL result, NSError *error) {
      ...
  }];

• You can start recording events for your AVPlayer instance using this API call.

  [collector startRecordingEventsFor: <AVPlayer* object>];
  

• You can also stop recording events of your AVPlayer instance using similar API call. 

  [collector stopRecordingEventsFor: <AVPlayer* object>];

• Run the app and observe the events captured in a Collector, data corresponding to MOBILE/iPhone in Platform, refers to the events tracked from iPhone.

Support for Google Interactive Media Ads

Datazoom allows customers to collect ad-related events when using Google Interactive Media Ads library.
To use Google IMA support, you will first need to install the Google IMA framework. Please refer to Google’s documentation on using this framework.

After that make sure that the proper version of Datazoom Collector framework is installed. Please refer to the Using Swift Package Manager section of this document.

To request an add you will need to specify adUrl (refer to Google documentation), reference to a view that has AVPlayer embedded and the viewController that holds the view:

collector.requestAds(for: adTagUrl, in: view, viewController: viewController)

You can also track already existing ad session with:

collector.setContentPlayhead(for: player)

Custom Events & Metadata

Datazoom allows customers to collect custom events and metadata that aren't emitted from the video player.

Custom events and metadata can be sent in global contexts (applying to the session) or in player context (applying to a specific player).

Custom Metadata

• Create a Dictionary object with necessary metadata

  let metaData = ["customMetadata":"MetadataValue"]

• Add the metadata to collector.
  

  collector.addCustom(metadata: metadata)

• To add the metadata to a specific player context:

collector.add(customMetadata:metadata playerContext: contextId)

Example:

func sendCustomMetadata(){
    let metadata = ["customPlayerName": "iOS Native Player"]
	collector.addCustom(metadata: metadata)
}

• In Objective-C:

  NSDictionary *metadata = @{@"customMetadata": @"MetadataValue"};
  [collector addCustomMetadata:metadata];

Custom Events

To send a custom Event you can use this methods:

• In Swift:

  collector.customEvents(event: "custom_event_name", metadata: metadata)

metadata is a dictionary of [String: Any]. It is an optional parameter and can be nil.

• In Objective-C

  [collector customEvents: @"custom_event_name" metadata: metadata];

  metadata is a NSDictionary. It is ann optional parameter and can be nil.

• To send a custom event in a specific context in Swift:

  collector.customEvents("eventName", playerContext: contextId)

Example:

• Swift

  @objc func buttonPushTouched() {       
    let metadata = ["customPlayerName":"NativeiOSPlayer",
                    "customDomainName":"datazoom.io"]
    collector.customEvents("buttonClick", metadata:metadata)        
  }

• Objective-C:

  NSDictionary *metadata = @{@"customPlayerName": @"NativeiOSPlayer",
                             @"customDomainName", @"datazoom.io"
                            };
  [collector customEvents:@"CustomEventName" metadata: metadata];