Akamai Adaptive Media Player iOS

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

Datazoom’s framework facilitates applications that use the Akamai iOS Player to send video playback events based on the configuration created in data pipes.

Prerequisites

• macOS Catalina version 10.15.2 or later

• Xcode 12.x with Swift 5.1 (The AMP Core supports Swift 5.1 only)

• CocoaPods (https://guides.cocoapods.org/using/getting-started.html )

Installation

• 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 DZAkamaiGold framework after use_frameworks! in the Podfile

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

• Add the AmpCore framework in the Podfile

  pod 'AmpCore'

• 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: "https://platform.datazoom.io")
  collector.start(completion: @escaping (Bool, Error?) -> ())

• If you are using Swift 5.5 or later you can also using asynchronous async/await approach:

  let collector = DZ_Collector(configID: <configuration id from Datazoom>, url: "https://platform.datazoom.io")
  do {
    try await collector.start()
  } catch (let error) {
    // handle error
  }
  

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

  collector.startRecordingEvents(for: <AmpPlayer object>)

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

  collector.stopRecordingEvents(for: <AmpPlayer object>)

• To stop recording event for ALL active AmpPlayer 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;
  @import AmpCore;

• Declare the swift class in the .h file.

  DZ_Collector *collector;

• In the .m file, allocate and initialize using:
  Completion handler will return two values, success and error if happened.

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

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

  [collector startRecordingEventsFor: <AmpPlayer* object>];
  

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

  [collector stopRecordingEventsFor: <AmpPlayer* 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.

Custom Events & Metadata

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

Custom Metadata

• Create an NSDictionary with necessary metadata

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

• Add the metadata to DZEventCollector

  collector.addCustom(metadata: metadata)Example:

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

• In Objective-C:

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

Custom Events

• Send  Events like below:

  collector.addCustomEvent(event: "custom_event_name", metadata: metadata|nil)
  

  
  Example:

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

• In Objective-C:

  [collector addCustomWithEvent:@"CustomEventName" metadata: metadata];