MediaMelon Android IMA Media3 SDK Integration Document

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

Step 1: Set up the build environment

Step 2: Register and Initialise SDK

Step 3: Report Custom Metadata

Step 4: Report Custom Errors

Step 5: Report Ended State

Step 6: Report Stream Info

Step 7: Enable IMA/DAI Ad tracking

Release Notes

Step 1: Set up the build environment

$MEDIA3PROJECT = {Media3 - v1.4.0}

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

Step 1.1: Add Gradle Dependency:

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.5'
}

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')
}

Step 1.2 Provide Permissions

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 1.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 2: 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.

Step 2.1: Set Context

Set the application context

MMSmartStreamingExo2.getInstance().setContext(applicationContext)

Step 2.2: Register SDK

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at [e-mail].

MMSmartStreamingExo2.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", true);

Step 2.3: Report Player Information

MMSmartStreamingExo2.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");

Step 2.4: Report Base Player Information

MMSmartStreamingExo2.getInstance().reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");

Step 2.5: Report Application Information

MMSmartStreamingExo2.reportAppInfo("APP_NAME","APP_VERSION");

Step 2.6: Initialize session with Content Metadata

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";
    
MMSmartStreamingExo2.getInstance().initializeSession(player, streamURL, contentMetadata, isLive);
MMSmartStreamingExo2.getInstance().reportUserInitiatedPlayback();

Step 2.7: Report Experiment Name

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

Step 2.8: Report View Session Id

Report the View Session Id attribute after initializeSession and before reportUserInitiatedPlayback.

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

Step 2.9: Report Sub Property Id

Report the Sub Property ID attribute after initializeSession and before reportUserInitiatedPlayback.

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

Step 2.10: Report App Session ID

Report Application Session ID

MMSmartStreamingExo2.getInstance().reportAppSessionId("APP_SESSION_ID");

Step 2.11: Report Player Resolution

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

Step 3: Report Custom Metadata

MMSmartStreamingExo2.getInstance().reportCustomMetadata("CUSTOM_KEY_1","VALUE1");

Step 4: 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 5: 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 6: Report Stream Information

Step 6.1: Report Stream Info

Report key stream attributes that describe the encoding and delivery method.

MMSmartStreamingExo2.getInstance().reportStreamInfo("STREAM_FORMAT", "MEDIA_TYPE", "SOURCE_TYPE", isLive)

Step 6.2: Report CDN

Report the name or identifier of the Content Delivery Network (CDN) used for streaming. This helps track performance and quality across different CDNs.

MMSmartStreamingExo2.getInstance().reportCDN("CDN");

Step 6.3: Report Stream Fallback Event

Report fallback event in case the primary manifest URL fails and falls back on the secondary manifest.

MMSmartStreamingExo2.getInstance().reportFallbackEvent("FALLBACK_URL", "DESCRIPTION");

Step 7: Enable IMA/DAI Ad tracking

Add the following steps to enable IMA/DAI Ad tracking

7.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();

7.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();
    }
}

Releases Notes

Current Release

v2.2.5 ^{_{Mar 11, 2026}}

• Added API to report App Session ID.

• Added API to report CDN.

• Added events for AD-BUFFERING.

• Added API to Report Stream Information

• Added API to Report Fallback Event.

• Added support for Seek Duration

---

Previous Releases