Media3 SDK Integration Document
This guide provides detailed instructions on integrating the Android MediaMelon 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 Ended State
Step 6: Report Session Level Details
Step 7: Report Errors and Warnings
Step 8: Report Stream Level Information
Step 9: Report Additional Metadata
Step 1: Prerequisites
MediaMelon Media3 SDK, Maven dependencies, or the provided AAR file are necessary.
Step 2: 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.
Using Maven:
Add MediaMelon Media3 Maven dependency to
main/build.gradle
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-media3:1.2.1'
}Using AAR:
Copy
mmsmartstreaming.aarprovided in the release package for the Media3 project. Example$MEDIA3PROJECT/demos/main/mmsmartstreaming.aar.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.MMSmartStreamingMedia3;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.
protected boolean initializePlayer() {
if (player == null) {
Intent intent = getIntent();
...
// after the player is initialized and the player instance is not null
initializeMediaMelon();
...
}
void initializeMediaMelon(){
MMSmartStreamingMedia3.enableLogTrace(false);
if (MMSmartStreamingMedia3.getRegistrationStatus() == false)
{
MMSmartStreamingMedia3.setContext(getApplicationContext()); //Please make sure to provide the application's context here, and not the activity's context
boolean hashSubscriberId = false;
MMSmartStreamingMedia3.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", hashSubscriberId);
MMSmartStreamingMedia3.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
MMSmartStreamingMedia3.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
MMSmartStreamingMedia3.reportAppInfo("APP_NAME","APP_VERSION");
MMSmartStreamingMedia3.reportDeviceId("DEVICE-ID");
}
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;
MMSmartStreamingMedia3.initializeSession(, "STREAM_URL", contentMetadata, isLive);
MMSmartStreamingMedia3.reportUserInitiatedPlayback();
}Step 5: 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 6: Report Session Level Details
Step 6.1: Report Experiment Name
MMSmartStreamingMedia3.reportExperimentName("EXPERIMENT_NAME");Step 6.2: Report View Session ID
MMSmartStreamingMedia3.reportViewSessionId("VIEW_SESSION_ID");Step 6.3: Report Sub Property ID
MMSmartStreamingMedia3.reportSubPropertyId("SUB_PROPERTY_ID");Step 7: 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.
🚫 Disabling Auto Error Capture:
If you prefer to handle error reporting manually, you can disable this automatic behavior by calling:
MMSmartStreamingMedia3.disableAutoErrorCapture(true);🛠️ 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 8: Report Stream Level Information
Step 8.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 8.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 8.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 9: Report Additional Metadata
Step 9.1: Report Custom Metadata
Use this method to report any additional metadata that doesn’t fall under predefined fields. This allows flexibility to send custom business-specific or platform-specific information to the SDK.
MMSmartStreamingMedia3.reportCustomMetadata("custom_1","VALUE1");Step 9.2: 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);Last updated