Media3 IMA SDK Integration Document

This guide provides detailed instructions on integrating the Android MediaMelon IMA SDK with the Media3 player.

Step 1: Prerequisites

Step 2: Set up the build environment

Step 3: Import Packages

Step 4: Register and Initialise SDK

Step 5: Report Experiment Name

Step 6: Report Sub-Property Id

Step 7: Report View Session

Step 8: Report Player Resolution

Step 9: Report Custom Errors

Step 10: Report Ended State

Step 11: Enable IMA/DAI Ad tracking

Step 1: Prerequisites

• Media3 sample application.

• MediaMelon Media3 SDK Maven dependencies or the provided AAR file is necessary.

Step 2: Set up the build environment

The SDK files should be added to the build environment and the required network permissions should be enabled.

Using Maven:

1. Add MediaMelon Media3 Maven dependency to $MEDIA3PROJECT/demos/main/build.gradle

1.4.0

dependencies {
   ...
  implementation 'com.github.MediamelonSDK:mm-android-sdk-media3-ima:2.2.2'
}

Using AAR:

1. Copy mmsmartstreaming.aar provided in the release package for the Media3 project. Example $MEDIA3PROJECT/demos/main/mmsmartstreaming.aar .

2. Add the following library to $MEDIA3PROJECT/demos/main/build.gradle :-

dependencies {
  ...
  api files ('mmsmartstreaming.aar')
}

Add network permissions to $MEDIA3PROJECT/demos/main/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Step 3: Import Packages

$MEDIA3PROJECT/demos/main/src/main/java/androidx/media3/demo/main/PlayerActivity.java

import com.mediamelon.qubit.ep.ContentMetadata;
import com.mediamelon.smartstreaming.media3_ima.MMAnalyticsBridge;
import com.mediamelon.smartstreaming.media3_ima.MMSmartStreamingExo2;

Step 4: Register and Initialise SDK

The player application must register the SDK and provide player information once the player is initialized. Please note that values provided in this integration step persist across video sessions.

The SDK must be initialized at the start of each video session. Initialization includes setting the application context, initializing the playback session, and indicating the intent for playback with the SDK.

The enableLogTrace() feature should be enabled for testing during the integration process. Set this to False before releasing the player to production.

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at [email protected].

protected boolean initializePlayer() {
   
   // after the player is initialized and the player instance is not null
   initializeMediaMelon();
   ...
 }

void initializeMediaMelon(){
     MMSmartStreamingExo2.enableLogTrace(false);
    if (MMSmartStreamingExo2.getRegistrationStatus() == false)
    {
      MMSmartStreamingExo2.getInstance().setContext(getApplicationContext()); //Please make sure to provide the application's context here, and not the activity's context
      boolean hashSubscriberId = true;
      MMSmartStreamingExo2.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", hashSubscriberId);
      MMSmartStreamingExo2.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
      MMSmartStreamingExo2.getInstance().reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
      
      MMSmartStreamingExo2.reportAppInfo("APP_NAME","APP_VERSION");
      MMSmartStreamingExo2.getInstance().setDeviceInfo("DEVICE_MARKETING_NAME");
      
      //call this function to enable custom error reporting 
      MMSmartStreamingExo2.getInstance().enableCustomErrorReporting(true);
    }
    
    ContentMetadata contentMetadata  = new ContentMetadata();
    contentMetadata.assetName="ASSET_NAME";
    contentMetadata.assetId="ASSET_ID";
    contentMetadata.videoId="VIDEO_ID";
    contentMetadata.seriesTitle="SERIES_TITLE";
    contentMetadata.season="SEASON";
    contentMetadata.genre="GENRE";
    contentMetadata.episodeNumber="EPISODE_NUMBER";
    contentMetadata.drmProtection="DRM_PROTECTION";
    contentMetadata.contentType="CONTENT_TYPE";
    
    boolean isLive = false;
    MMSmartStreamingExo2.getInstance().initializeSession(player, streamURL, contentMetadata, isLive);
    MMSmartStreamingExo2.getInstance().reportUserInitiatedPlayback();
    MMSmartStreamingExo2.getInstance().reportCustomMetadata("CUSTOM_KEY_1","VALUE1");
    MMSmartStreamingExo2.getInstance().reportCustomMetadata("CUSTOM_KEY_2","VALUE2");
 }

For Custom Metadata, first, provide the mapping in the SmartSight dashboard under the settings section and send the values to the SDK accordingly.

Step 5: Report Experiment Name

MMSmartStreamingExo2.getInstance().reportExperimentName("EXPERIMENT_NAME");

Step 6: Report Sub-Property Id

MMSmartStreamingExo2.getInstance().reportSubPropertyId("SUB_PROPERTY_ID");

Step 7: Report View Session Id

MMSmartStreamingExo2.getInstance().reportViewSessionId("VIEW_SESSION_ID");

Step 8: Report Player Resolution

MMSmartStreamingExo2.getInstance().reportPlayerResolution(playerWidth, playerHeight);

Step 9: Report Custom Errors

Make sure that enableCustomErrorReporting is set to true for this to be able to report errors

MMSmartStreamingExo2.getInstance().reportError("ERROR_CODE", "ERROR_MESSAGE", "ERROR_DESCRIPTION");

Step 10: Report Ended State

Report ENDED state in PlayerActivity when playback ends.

If not reported at the end of the playback, it may reflect a longer playtime.

private void releasePlayer() {
    if (player != null) {
      player.release();
      player = null;
      
      MMSmartStreamingExo2.getInstance().reportPlayerState(false, Player.STATE_ENDED);
    }
  }

Step 11: Enable IMA/DAI Ad tracking

Add the following steps to enable IMA/DAI Ad tracking

11.a: IMA Ad Tracking

private final ImaSdkFactory sdkFactory;
private AdsLoader adsLoader;
private StreamDisplayContainer displayContainer;

MMAnalyticsBridge analyticsBridgeObject;

//Get the Analytics Bridge Object, this should be done wherever in your application the adsLoader is created
analyticsBridgeObject = MMSmartStreamingExo2.getInstance().getAnalyticsBridge(); 

//Initialising ads loader
ImaSdkSettings settings = sdkFactory.createImaSdkSettings();
adsLoader = sdkFactory.createAdsLoader(context, settings, displayContainer);

// For IMA Ad Tracking
public void requestAndPlayAds() {  
  adsLoader.addAdErrorListener(analyticsBridgeObject); // pass the Analytics Bridge object to the ads error listeners
  adsLoader.addAdsLoadedListener(analyticsBridgeObject); // pass the Analytics Bridge object to the ads loaded listeners
}

Alternate method for IMA ad tracking

adsLoader = new ImaAdsLoader.Builder(/* context= */ this)
                .setAdEventListener(analyticsBridgeObject)
                .setAdErrorListener(analyticsBridgeObject)
                .build();

11.b: DAI Ad Tracking

The function onAdsManagerLoaded is part of AdsLoader.AdsLoadedListener

private StreamManager streamManager;
MMAnalyticsBridge analyticsBridgeObject;

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
 //Get the Analytics Bridge Object ,this should be done wherever in your application the adsManager is loaded
analyticsBridgeObject = MMSmartStreamingExo2.getInstance().getAnalyticsBridge();
  
  if(event.getStreamManager()!=null) {
      streamManager = event.getStreamManager();
      
      streamManager.addAdErrorListener(analyticsBridgeObject); // pass the Analytics Bridge object to the ad error listeners
      streamManager.addAdEventListener(analyticsBridgeObject); // pass the Analytics Bridge object to the ad event listeners
      streamManager.init();
    }
}