MediaMelon Android Media3 SDK Integration Document

This guide provides detailed instructions on integrating the Android MediaMelon 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 Ended State

Step 5: Report Errors and Warnings

Step 6: Report Stream Level Information

Step 7: Update Asset Information

Release Notes

Step 1: Set up the build environment

$MEDIA3PROJECT = {Media3 - v1.x.x}

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 main/build.gradle

1.7.1

dependencies {
   ...
  implementation 'com.github.MediamelonSDK:mm-android-sdk-media3:v1.7.1-2.4.0'
}

1.4.1

1.3.1

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: Add 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.MMSmartStreamingMedia3;

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.

MMSmartStreamingMedia3.enableLogTrace(true);

Step 2.1: Set Context

Set the application context

MMSmartStreamingMedia3.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 [email protected].

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

Step 2.3: Report Player Information

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

Step 2.4: Report Base Player Information

MMSmartStreamingMedia3.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");

Step 2.5: Report Application Information

MMSmartStreamingMedia3.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";
    
MMSmartStreamingMedia3.initializeSession(player, "STREAM_URL", contentMetadata, isLive);
MMSmartStreamingMedia3.reportUserInitiatedPlayback();

Step 2.8: Report Experiment Name

MMSmartStreamingMedia3.reportExperimentName("EXPERIMENT_NAME");

Step 2.9: Report View Session Id

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

MMSmartStreamingMedia3.reportViewSessionId("VIEW_SESSION_ID");

Step 2.10: Report Sub Property Id

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

MMSmartStreamingMedia3.reportSubPropertyId("SUB_PROPERTY_ID");

Step 2.12: Report App Session ID

Report Application Session ID

MMSmartStreamingMedia3.setAppSessionID("APP_SESSION_ID");

Step 2.13: Report Player Resolution

Report the width and height of the player (in pixels). This is useful to understand playback size and user experience across different screen sizes or platforms.

MMSmartStreamingMedia3.reportPlayerResolution(playerWidth, playerHeight);

Step 3: Report Custom Metadata

Check the custom tags configuration in your dashboard and report accordingly. If the custom tags are not configured, please configure and use them accordingly.

MMSmartStreamingMedia3.reportCustomMetadata("custom_1","VALUE_1");

Step 4: Report Ended State

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

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

Step 5: Report Errors and Warnings

The SDK provides two ways to report errors: automatic error capture and manual error reporting via API.

⚙️ Default Behavior (Auto Error Capture):

By default, the SDK automatically listens to and captures player errors that occur during a playback session.

⚠️ Note: Errors that occur before are not captured automatically by the SDK, as they fall outside the player’s event lifecycle. Use the error and warning APIs below to manually report such issues.

🚫 Disabling Auto Error Capture:

If you prefer to handle error reporting manually, you can disable this automatic behavior by calling:

MMSmartStreamingMedia3.disableAutoErrorCapture(true);

⚠️ When disabled, the SDK will not listen for any player-generated errors. You will be responsible for reporting all errors & warnings manually using the APIs described below.

🛠️ Manual Error Reporting APIs:

Use these APIs to custom report errors and warnings to the SDK—especially for errors that occur before, or when auto-capture is disabled.

🔴 Report Fatal Error:

All errors reported via reportError are treated as fatal.

MMSmartStreamingMedia3.reportError((int) errorCode, "ERROR_MESSAGE", "ERROR_DESCRIPTION");

🟠 Report Warning (Non-Fatal):

All warnings reported via reportWarning are treated as non-fatal and will be tracked accordingly.

MMSmartStreamingMedia3.reportWarning((int) errorCode, "ERROR_MESSAGE", "ERROR_DESCRIPTION");

Step 6: Report Stream Level Information

Step 6.1: Report Stream Info

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

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

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

MMSmartStreamingMedia3.reportFallbackEvent("FALLBACK_URL", "DESCRIPTION");

Step 7: Update Asset Information

If Asset Information needs to be updated dynamically during the live session without re-initializing the player, then the updateAssetInfo API can be used to update the new AssetInfo.

Note

• This API must be called for updating asset info for the live streams only

• This API must be called after the Player has started the playback of the live stream

MMSmartStreamingMedia3.updateAssetInfo(contentMetaData);

Release Notes

Current Release

v2.4.0

• Seek duration support

• Internal updates

---

Previous Release