AV Player with Nowtilus SSAI

Integration document for AV Player with Nowtilus SSAI

Step 0: Creating AV Player based media player application

Create a directory for integration by doing the following. Open the terminal, change directory to the home directory, and create a folder sampleintegration

cd ~/
mkdir sampleintegration
cd sampleintegration/

Pull the Sample Application from https://sdk.mediamelon.com/$CustomerID/iOS/AVPlayer_SampleApplication.zip and unzip it

wget https://sdk.mediamelon.com/202290422/04022022/iOS/AVPlayer_SampleApplication.zip

Step 1: Get the MMGenericFramework Static Framework Library

Download the MMGenericFramework static faremwork

Copy the MMGenericFramework static framework to the AVPlayerWithNowtilusSSAi directory

If you are building for the simulator use the MMGenericFramework.framework in the iphonesimulator-x86 and which building for the device use the MMGenericFramework.framework in the iphoneos-arm64 directory

Step 2: Integrating the MMGeneric Framework with the AV Player Sample Application

There are a few steps involved for integrating the MediaMelon Player SDK using the MediaMelonSmartStreaming Framework:

  1. Add the appropriate MMGenericFramework to the AV Player Sample Application

  2. Add the AVPlayerIntegrationWrapper.swift file from the Wrapper directory

  3. Provide asset information for the content before starting the player and after creating its instance

  4. Cleaning up the SDK Session

  5. Disable manifest fetching by the SDK

  6. Add the MMSSAIAdManagerDelegate callbacks

  7. Initializing SSAIAd Manager

  8. Stop the Ad Manager

All AV Player related code of the sample application can be found in the Swift classViewController.swift

1. Import Frameworks

import MMGenericFramework

2. Ad the AVPlayerIntegrationWrapper.swift file

This is the integration layer between the Media Melon Framework and AV Player. This needs to be added to the project. Unless absolutely necessary , this file should not be modified.

3. Provide Asset information

After the instance of the player is create, we should set the asset information and send it to before starting its playback. In ViewController.swift, call function self.configureMMSDKwithURL(mediaURL: String, vastURL: String, player: AVPlayer)

private func configureMMSDKWithURL(urlStr: String, vastURLStr: String, player: AVPlayer) {
        print("Integrating with \(String(describing: AVPlayerIntegrationWrapper.getVersion()))")
        let assetInfo = MMAssetInformation(assetURL: urlStr, assetID: String(arc4random()), assetName: "assetNameRandom", videoId: "VIDEO_ID")
        assetInfo.addCustomKVP("CustomKVP1Key", "CustomKVP1Value")
            assetInfo.addCustomKVP("CustomKVP2Key", "CustomKVP2Value")
            assetInfo.setQBRMode(.QBRModeDisabled, withMetaURL: nil)
        let registrationInfo = MMRegistrationInformation(customerID: "202290422", playerName: "AVPLayer")
        registrationInfo.setPlayerInformation(brand: "Apple", model: "iPhone 11", version: "14.1")
        registrationInfo.setSubscriberInformation(subscriberID: "<subscriber_id>", subscriberType: "<subscriber_type>", subscriberTag: "TAGIT")
        AVPlayerIntegrationWrapper.shared.mmssaiManagerDelegate = self
        AVPlayerIntegrationWrapper.disableManifestsFetch(disable: true)
        AVPlayerIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: registrationInfo, player: player)
        //Initialize SSAI
        AVPlayerIntegrationWrapper.shared.initialiseSSAIAdManager(mediaUrl: self.mediaURL, vastUrl: self.vastURL, isLive: self.isLive)
 }

4. Cleaning up the SDK Session

We need to clean up the SDK session once the playback completes. The SDK internally manages the cleanup for most of the cases. For example - when playback finishes, or some error is notified.

However, in some error cases, like network reachability issues, the error notification is delayed. And before this error notification is available, the user may trigger another session. Therefore, it is advised to clean up the session once the playback finishes.

We recommend cleanup at the following two places.

  • When the view controller hosting the post roll ad terminates

  • When the player is restarted

AVPlayerIntegrationWrapper.shared.stopSSAIAdManager()
AVPlayerIntegrationWrapper.cleanUp()

5. Disable manifest fetching by the SDK

If your workflow restricts the manifest to be accessible from both player and the MediaMelon Player SDK simultaneously, then, you can disable the fetch of manifest via disableManifestsFetch() in method _configureMMSDKwithURL()

private func configureMMSDKWithURL(mediaURL: String, vastURL: String) {
    .
    .
    .
    AVPlayerIntegrationWrapper.cleanUp()
    AVPlayerIntegrationIntegrationWrapper.disableManifestsFetch(disable: true)
    AVPlayerIntegrationIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: registrationInfo, player: player)
}

Note: Disable Manifest Fetch is Optional

6. Add the MMSSAIManagerDelegate

Add the MMSSAIManagerDelegate the ViewController class in ViewController.swift. This delegate will be used for receiving Ad related events and data. At every Ad event the Delegate will fire the notifyMMSSAIAdEventsWith function. This can be used to display Ad related data, enable or disable Ad skipping etc. 

class ViewController: UIViewController, MMSSAIManagerDelegate 
.....
     func notifyMMSSAIAdEventsWith(eventName: MMSSAIAdSate, adInfo: MMSSAIAdDetails) {
        
        if (eventName == MMSSAIAdSate.adPlaying)
        {
            
            print ("Ad progress ", ((AVPlayerIntegrationWrapper.getAdPlaybackTime(adInfo: adInfo)*100)/AVPlayerIntegrationWrapper.getAdDuration(adInfo: adInfo)))
            
        }
        else
        {
            print("---------------------------------------------------")
            print(" Ad Id :",AVPlayerIntegrationWrapper.getAdId(adInfo: adInfo))
            print(" Ad Title :",AVPlayerIntegrationWrapper.getAdTitle(adInfo: adInfo) )
            print(" Ad Index :",AVPlayerIntegrationWrapper.getAdIndex(adInfo: adInfo)," of ", AVPlayerIntegrationWrapper.getAdTotalAdsInPod(adInfo: adInfo) )
            print(" Ad Server :",AVPlayerIntegrationWrapper.getAdServer(adInfo: adInfo))
            print(" Ad Duration :",AVPlayerIntegrationWrapper.getAdDuration(adInfo: adInfo) )
            print(" Ad Position :",AVPlayerIntegrationWrapper.getAdPosition(adInfo: adInfo) )
            print(" Ad Event :",eventName )
            
            if ( eventName == MMSSAIAdSate.adImpression)
            {
                
                let clickURL = AVPlayerIntegrationWrapper.getClickThroughURL(adInfo: adInfo)
                let clickTrackingURL = AVPlayerIntegrationWrapper.getClickTrackingURL(adInfo: adInfo)
                print("Video Click URL:", clickURL)
                print("Video Click Tracking  URL:", clickTrackingURL)
            }
        
            print("---------------------------------------------------")
        }
        
    }

Ad Events Supported

adCueTimelineStart

Fired at the start of an Ad break

adImpression

Fired on Ad Impression

adStarted

Fired on start of Ad Play

adPlaying

Fired every 1s during Ad Playback

adFirstQuartile

Fired when Ad playback reached the 25% mark

adMidPoint

Fired when the Ad playback reaches the 50% mark

adThirdQuartile

Fired when Ad Playback reaches the 75% mark

adCompleted

Fired when Ad Playback reaches 100% mark

adCueTimelineEnd

Fired at the end of an Ad break

adSkipped

Fired when an Ad break is skipped

Sample output 

---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adCueTimelineStart
---------------------------------------------------
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adImpression
Video Click URL: XXXXXXXXXXXXXXX
Video Click Tracking  URL: XXXXXXXXXXXXXXXXXXX
---------------------------------------------------
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adStarted
---------------------------------------------------
Ad progress  4
Ad progress  8
Ad progress  12
Ad progress  16
Ad progress  20
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adFirstQuartile
---------------------------------------------------
Ad progress  24
Ad progress  28
Ad progress  32
Ad progress  36
Ad progress  40
Ad progress  44
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adMidpoint
---------------------------------------------------
Ad progress  48
Ad progress  52
Ad progress  56
Ad progress  60
Ad progress  64
Ad progress  68
Ad progress  72
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adThirdQuartile
---------------------------------------------------
Ad progress  76
Ad progress  80
Ad progress  84
Ad progress  88
Ad progress  92
Ad progress  96
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adCompleted
---------------------------------------------------
---------------------------------------------------
 Ad Id : 502180
 Ad Title : Video_4
 Ad Index : 1  of  1
 Ad Server : VMAX
 Ad Duration : 25
 Ad Position : MID
 Ad Event : adCueTimelineEnd
---------------------------------------------------

7. Initialize the SSAI Ad Manager

Initialize the SSAI Ad Manager to track the Ads and report Ad related metric. For live stream the last parameter isLive is set to true. There are different ways in which the Ad manager can be initialized

Mode 1: Poll for Vast and Manifest Mode ( Default mode )

private func configureMMSDKWithURL(mediaURL: String, vastURL: String) {
    .
    .
    .
     
        AVPlayerIntegrationWrapper.shared.initialiseSSAIAdManager(mediaUrl: mediaURL, vastUrl: vastURL, isLive: true)
}

Mode 2: Read the Manifest data from player API and retreive the Vast file from X-AD-VAST tag in the #EXT-X-DATERANGE metadata in the manifest file

To enable this mode there are a a few steps required

STEP 1: Enable Meta Data Collector

    private func initialisePlayer() {
        self.player = AVPlayer()
        self.metadataCollector = AVPlayerItemMetadataCollector()
        self.playerItem = AVPlayerItem(url: URL(string: self.mediaURL)!)
        
        AVPlayerIntegrationWrapper.setMetaDataCollector( player: self.player,
                                                         collector: self.metadataCollector,
                                                         playerItem: self.playerItem)
      .....

STEP 2: Sync player time with Manifest based time

        override func viewDidLoad() {
        super.viewDidLoad()
        self.getURLDetails()
        self.initialisePlayer()
        
        NotificationCenter.default.addObserver(self,
               selector: #selector(playerItemDidReadyToPlay(notification:)),
               name: .AVPlayerItemNewAccessLogEntry,
                                               object: self.player?.currentItem)
    }
    
    
    .......
    
    
    // Sync player time
    @objc func playerItemDidReadyToPlay(notification: Notification) {
            if let _ = notification.object as? AVPlayerItem {
                
                
                AVPlayerIntegrationWrapper.shared.syncEpochTime(epochTime: Int64(self.playerItem.currentDate()!.timeIntervalSince1970 * 1000))
                
                NotificationCenter.default.removeObserver(self,
                            name: .AVPlayerItemNewAccessLogEntry,
                               object: player?.currentItem)
            }
    }

STEP 3 Initialise the AD Manager

AVPlayerIntegrationWrapper.shared.initialiseSSAIAdManager(mediaUrl: self.mediaURL, isLive: self.isLive, pollForVast: false)  // Poll for vast set to false used the metadatacollector for accesing manifest data

8. Stop the SSAI Ad Manager

To stop the SSAI Ad Manager call the following API


AVPlayerIntegrationWrapper.shared.stopSSAIAdManager()

Step 3: Adding multiple static frameworks including the MMGeneric (Static) Framework 

libtool -static -o MyToplevelSDK.framework MMGeneric.framework/MMGenericFramework AnotherSDK.framework/AnotherSDK

List of AvPlayerIntegrationWrapper methods for SSAI

Method
Functionality

initialiseSSAIAdManager

Initializes the Nowtilus SSAI Ad Manager

setMetaDataCollector

Configiures the Meta Data collector and then returns meta data valuessyn

syncEpochTime

Syncs the player time with the time provided in the Manifest URL

stopSSAIManager

Stops the running instance of the SSAI Ad Manager

getAdPlaybackTime

Gets the playback time of the current ad playing ( Called during an Ad Break)

getAdDuration

Gets duration of the current Ad ( Called during an Ad Break)

getAdId

Gets the Ad Id value( Called during an Ad Break)

getAdTitle

Gets the Ad Title ( Called during an Ad Break)

getAdIndex

Returns in Index of the current ad playing in an Ad break. ( Called during an Ad Break)

getAdTotalAdsInPod

Gets the toal number of Ads inside an Ad Pod( Called during an Ad Break)

getAdServer

Gets the Ad Server Name ( Called during an Ad Break)

getAdDuration

Gets the duration of the events( Called during an Ad Break)

getAdPosition

Gets the position of the Ads . For live Ads this will return "MID"

PreviousVO Player iOS Integration Guide with SSAINextC++ Based Player SDK(Nowtilus SSAI)

Last updated