AVPlayer Quality Of Experience SDK

This guide provides detailed instructions on integrating the MediaMelon AVPlayer SDK into an iOS Media Player Application.

Step 1: Import Frameworks

Step 2: Setup The SDK

Step 3: Configure and Initialise MediaMelon SDK

Step 4: Cleaning up the SDK Session

Step 5: Disable manifest fetch by the SDK

Step 6: Enable or Disable SDK Log Trace

All AVPlayer related code of the sample application can be found in the Swift class ViewController.swift

Step 1: Import Frameworks

import AVFoundation
import MMAVPlayerFramework

Step 2: Setup The SDK

Using Cocoapods

target 'SwiftDemo' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'MediaMelon-AVPlayer-iOS'
  # Pods for SwiftDemo
end

Using XCFramework:

Add the "xcframework" to the appropriate target's frameworks, libraries, and embedded content sections.

Step 3: Configure and Initialise MediaMelon SDK

After the player instance has created with the required asset information, send the media URL and player object to configureMMSDKWithURL function as shown below.

Swift

private func configureMMSDKWithURL(hlsURLStr: String, player: AVPlayer) {
    print("Integrating with \(String(describing: AVPlayerIntegrationWrapper.getVersion()))")
    
    let assetInfo = MMAssetInformation(assetURL: hlsURLStr, assetID: "ASSET_ID", assetName: "ASSET_NAME", videoId: "VIDEO_ID")
    assetInfo.setContentType("CONTENT_TYPE")
    assetInfo.setDrmProtection("DRM_PROTECTION")
    assetInfo.setEpisodeNumber("EPISODE_NUMBER")
    assetInfo.setSeriesTitle("SERIES_TITLE")
    assetInfo.setSeason("SEASON")
    assetInfo.setGenre("GENRE")
    
    //Add custom {Key, Value} pairs (Optional)
    assetInfo.addCustomKVP("CUSTOM_KEY_1", "CUSTOM_VALUE_1")
    assetInfo.addCustomKVP("CUSTOM_KEY_2", "CUSTOM_VALUE_2")
    
    let registrationInfo = MMRegistrationInformation(customerID: "CUSTOMER_ID", playerName: "PLAYER_NAME")
    //Set the player and subscriber information
    registrationInfo.setPlayerInformation(brand: "PLAYER_BRAND", model: "PLAYER_MODEL", version: "PLAYER_VERSION")
    registrationInfo.setSubscriberInformation(subscriberID: "SUBSCRIBER_ID", subscriberType: "SUBSCRIBER_TYPE", subscriberTag: "SUBSCRIBER_TAG", hashSubscriberID: <Bool>)
    registrationInfo.setDomain("DOMAIN_NAME")
    
    AVPlayerIntegrationWrapper.shared.reportAppData(appName: "APP_NAME", appVersion: "APP_VERSION")
    
    // SDK Initialization
    AVPlayerIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: registrationInfo, player: player, isLive: <Bool>)
}

Objective-C

- (void)configureMMSDKWithURL:(NSString *)hlsURLStr {
    MMAssetInformation *assetInfo = [[MMAssetInformation alloc] initWithAssetURL:hlsURLStr assetID:@"ASSET_ID" assetName:@"ASSET_NAME" videoId:@"VIDEO_ID"];
    // Set the content metadata of the asset (Optional)
    [assetInfo setContentType:@"CONTENT_TYPE"];
    [assetInfo setDrmProtection:@"DRM_PROTECTION"];
    [assetInfo setEpisodeNumber:@"EPISODE_NUMBER"];
    [assetInfo setSeriesTitle:@"SERIES_TITLE"];
    [assetInfo setSeason:@"SEASON"];
    [assetInfo setGenre:@"GENRE"];
    
    // Add custom {Key, Value} pairs (Optional)
    [assetInfo addCustomKVP:@"CUSTOM_KEY_1" value:@"CUSTOM_VALUE_1"];
    [assetInfo addCustomKVP:@"CUSTOM_KEY_2" value:@"CUSTOM_VALUE_2"];
    
    // Set QBR mode as shown below
    [assetInfo setQBRMode:QBRModeDisabled withMetaURL:nil];
    
    MMRegistrationInformation *registrationInfo = [[MMRegistrationInformation alloc] initWithCustomerID:@"CUSTOMER_ID" playerName:@"PLAYER_NAME"];
    // Set the player and subscriber information
    [registrationInfo setPlayerInformationWithBrand:@"PLAYER_BRAND" model:@"PLAYER_MODEL" version:@"PLAYER_VERSION"];
    [registrationInfo setSubscriberInformationWithSubscriberID:@"SUBSCRIBER_ID" subscriberType:@"SUBSCRIBER_TYPE" subscriberTag:@"SUBSCRIBER_TAG" hashSubscriberID:YES]; // Set the boolean value accordingly
    [registrationInfo setDomain:@"DOMAIN_NAME"];
    
    [AVPlayerIntegrationWrapper.shared reportAppDataWithAppName:@"APP_NAME" appVersion:@"APP_VERSION"];
    [AVPlayerIntegrationWrapper.shared reportVideoQuality:@"VIDEO_QUALITY"];
    [AVPlayerIntegrationWrapper.shared reportDeviceID:@"DEVICE_ID"];
    
    // SDK Initialization
    [AVPlayerIntegrationWrapper initializeAssetForPlayerWithAssetInfo:assetInfo registrationInformation:registrationInfo player:self.player isLive:YES]; // Set the boolean value accordingly
}

• hashSubscriberID: To hash the subscriber ID, set it to true. To leave the subscriber ID un-hashed, set it to false.

• isLive: Set it to true for a live video and false for a VOD video. This is optional.

Step 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.cleanUp()

Step 5: Disable manifest fetch by the SDK (Optional)

If your workflow limits access to the manifest from both the player and the MediaMelon Player SDK at the same time, you have the option to prevent manifest fetching by using the disableManifestsFetch() method within the configureMMSDKwithURL method.

private func configureMMSDKWithURL(hlsURLStr: String) {
    .
    .
    .
    AVPlayerIntegrationWrapper.cleanUp()
    AVPlayerIntegrationWrapper.disableManifestsFetch(disable: true)
    AVPlayerIntegrationWrapper.initializeAssetForPlayer(assetInfo: assetInfo, registrationInformation: registrationInfo, player: player, isLive: <Bool>)
}

Note: Disable Manifest Fetch is Optional

Step 6: Enable or Disable SDK Log Trace

To enable the SDK log trace, use the following API call: enableLogTrace.

AVPlayerIntegrationWrapper.shared.enableLogTrace(logStTrace: true)

Variable	Description
PLAYER_NAME	String containing the Player Name.
CUSTOMER_ID	String containing your MediaMelon-assigned Customer ID.
SUBSCRIBER_ID	String containing your Subscriber’s ID. If you do not use subscriber IDs, enter null
DOMAIN_NAME	String containing your section of your subscriber or assets.
SUBSCRIBER_TYPE	String containing the Subscriber Type (e.g. “Free”, “Paid”). If you do not use subscriber types, enter null
SUBSCRIBER_TAG	String containing an additional subscriber-specific information. This is sent in clear (not hashed) to SmartSight and it is advised to not send sensitive information in this field.
ASSET_ID	String containing Asset Id.
ASSET_NAME	String containing Asset Name.
VIDEO_ID	String containing your video’s ID. If you do not use videos IDs, enter null.
CONTENT_TYPE	String containing type of the Content. For example - "Movie", "Special", "Clip", "Scene Epis Lifts".
GENRE	String containing Genre of the content. For example - "Comedy", "Horror".
DRM_PROTECTION	Widevine, Fairplay, Playready etc. Unknown means content is protected, but protection type is unknown. For clear contents, do not set this field
EPISODE_NUMBER	String containing sequence number of the Episode.
SEASON	String containing the Season. For example - "Season1".
SERIES_TITLE	String containing Title of the Series.
VIDEO_TYPE	String containing Video Type. For example - "LIVE", "VOD".
CUSTOM_TAGS	Extra custom metadata can be added here if required.
PLAYER_BRAND	String containing Player Brand.
PLAYER_MODEL	String containing Player Model. For example - This could be a variant of player. Say name of third party player used by organisation. Or any human readable name of the player.
PLAYER_VERSION	String containing Player Version.