Bitmovin TVOS v2.66 (Nowtilus SSAI) with Content Provider Metrics

Step by step integration of the Mediamelon Player SDK with Nowtilus SSAI with Bitmovin Player 2.66.0

Integrating the MediaMelonSmartStreaming Framework

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

1. Importing the framework

2. Providing asset information for the content before starting the player and after creating its instance

3. Cleaning up the SDK integration session

4. Disable manifest fetching by the SDK

5. Initializing SSAI

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

Open the project file ~/sampleintegration/SampleBitmovinPlayer_v2.66.0_SSAI_MMSDK_<SDK Version>/BasicPlayback.xcworkspace in XCode and edit the file ViewController.swiftas mentioned below

1. Import Frameworks

import BitmovinPlayer
import MMSmartStreamingSDK // For Cocoaapods release
or
import MMGenericFramework // For Framework release

2. Provide Asset information

After the instance of the player is created, and SourceConfig is set with it, 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)

pprivate func configureMMSDK(mediaURL: String, vastURL: String) {
        let assetInfo = MMAssetInformation(assetURL: mediaURL, assetID: "RandomID", assetName: "Test Asset", videoId: "123456789")
        
        assetInfo.setContentType("Movie") //Type of content (Movie / Special / Clip / Scene)
        assetInfo.setDrmProtection("Fairplay") //Widevine, Fairplay, Playready etc. Unknown means content is protected, but protection type is unknown. For clear contents, do not set this field
        assetInfo.setEpisodeNumber("testEpisode") //Sequence Number of the Episode (string).
        assetInfo.setSeriesTitle("testSeries") //Title of the series
        assetInfo.setSeason("testSeason") //Season For example - Season1,2,3 etc
        assetInfo.setGenre("testGenre") //Genre of the content

        // Optional custom metadata
        assetInfo.addCustomKVP("CustomKVP1Key", "CustomKVP1Value")
        assetInfo.addCustomKVP("CustomKVP2Key", "CustomKVP2Value")
        assetInfo.setQBRMode(.QBRModeDisabled, withMetaURL: nil)
        
        let resgistrato = MMRegistrationInformation(customerID: "200417809", playerName: "BitmovinPlayerTesting")
        BitmovinPlayerIntegrationWrapper.setPlayerRegistrationInformation(registrationInformation: resgistrato, player: player)
        BitmovinPlayerIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: resgistrato, player: player)
     }
    

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

BitmovinPlayerIntegrationWrapper.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) {
    .
    .
    .
    BitmovinPlayerIntegrationWrapper.cleanUp()
    BitmovinPlayerIntegrationWrapper.disableManifestsFetch(disable: true)
    BitmovinPlayerIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: registrationInfo, player: player)
}

Note: Disable Manifest Fetch is Optional

5. Add the SSAIManagerDelegate

Add the SSAIManagerDelegate to the ViewController class in ViewController.swift

class ViewController: UIViewController, SSAIManagerDelegate 

You can now use the 2 delegate functions to get the event information whenever an AD event occurs

   
    func notifyMMSSAIAdEvents(eventName: MMSSAIAdSate, adInfo: MMSSAIAdDetails)
    {
        
    }
    

    func notifyMMSSAIAdEventsWithTimeline(eventName: MMSSAIAdSate, adTimeline: [MMSSAIAdDetails]) 
    {
        
    }
    

6. Initialize the SSAI Ad Manager

Initialize the SSAI Ad Manager to track the Ads and report Ad related metrics

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

7. Create a new session and update the asset information

During playback updateAssetInfo can be used to create a new session and update the asset information. The usage can be seen in the updateAsset function in the ViewController

func updateAsset() {
        let assetInfo = MMAssetInformation(assetURL: mediaURL, assetID: "RandomID", assetName: "Test Asset", videoId: "123456789")
        
        assetInfo.setContentType("Movie") //Type of content (Movie / Special / Clip / Scene)
        assetInfo.setDrmProtection("Fairplay") //Widevine, Fairplay, Playready etc. Unknown means content is protected, but protection type is unknown. For clear contents, do not set this field
        assetInfo.setEpisodeNumber("testEpisode") //Sequence Number of the Episode (string).
        assetInfo.setSeriesTitle("testSeries") //Title of the series
        assetInfo.setSeason("testSeason") //Season For example - Season1,2,3 etc
        assetInfo.setGenre("testGenre") //Genre of the content
        assetInfo.addCustomKVP("CustomKVP1Key", "CustomKVPalue")
        assetInfo.addCustomKVP("CustomKVP2Key", "CustomKVPValue")
        assetInfo.setQBRMode(.QBRModeDisabled, withMetaURL: nil)
          
         // Create a new session and update the Asset info
          BitmovinPlayerIntegrationWrapper.updateAssetInfo(assetInfo: assetInfo, player: player)
                  
  }

8. Getting the mediaURL and vastURL from the Session Resolver URL

The session resolver URL as provided by Nowtilus redirects to another resolved URL from which the mediaURL and vastURL required for initializing the Media Melon SDK is obtained. Information about the resolved URL is obtained in the onDownloadFinished event handler for Bitmovin Player. The code below shows how this is done.

    func  onDownloadFinished(_ event: DownloadFinishedEvent) {
        var redirectedMediaURL: String?
        if let redirectionLocation = event.lastRedirectLocation {
            redirectedMediaURL = redirectionLocation.absoluteString
            
                let parts = redirectedMediaURL?.components(separatedBy: "/master.m3u8")
                let result = parts?.first ?? ""
                let vastUrl = result + "/vast.xml"
            
                if !self.isMMInitialised {
                    derivedURL = redirectedMediaURL!
                    self.configureMMSDK(mediaURL: redirectedMediaURL!, vastURL: vastUrl)
                    self.isMMInitialised = true
                }
        }
        
        if redirectedMediaURL == nil {
            derivedURL = event.url.absoluteString
            redirectedMediaURL = event.url.absoluteString
            if !isMMInitialised {
                self.configureMMSDK(mediaURL: redirectedMediaURL!, vastURL: "")                
                isMMInitialised = true
           }
        }
    }

Please note that in case there is no URL redirection we need to obtain the actual URL from the event.url.absoluteString and use it in initializing the Media Melon SDK using the configureMMSDK call as shown in the sample integration

9 Enabling Content Provider Metrics

Content Provider Metric Reporting is enabled by calling the setContentProviderDetails function defined in the BitmovinPlayerIntegrationWrapper.swift. This needs to be done immediately after the call to configure the Media Melon SDK

self.configureMMSDK(mediaURL: redirectedMediaURL!, vastURL: vastUrl)
if ( contentProviderDetails == true)
{
    BitmovinPlayerIntegrationWrapper.setContentProviderDetails(url:redirectedMediaURL!)
}

The setContentProviderDetails expects the URL with the Content Provider information as shown in the table below. In case the information is correctly provided it enables content provider metrics reporting.

The above code is tested with URLs with the structure:

• https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8?tbtoken=JWTtoken&provider=tbox&cid=ContentId

Parameter	Value
provider	stzp : Starz tbox: Toolbox
tbtoken	JWT Token for Toolbox endpoint
cid	Content ID
sid	Starz session ID

For enabling Toolbox metrics please pass - provider, tbtoken and cid values as shown below

https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8?tbtoken=JWTtoken&provider=tbox&cid=ContentId

For enabling Starz content provider metrics please pass: provider, cid and sid values as shown below

https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8?provider=stzp&cid=ContentId&sid=SessionId