# MediaMelon Android Media3 SDK Integration Document
**Step 1:** [Set up the build environment](#step-1-set-up-the-build-environment)
**Step 2:** [Register and Initialise SDK](#step-3-initialize-session-and-report-user-intent-to-playback)
**Step 3:** [Report Custom Metadata](#step-3-report-custom-metadata)
**Step 4:** [Report Ended State](#step-5-report-ended-state-when-the-player-instance-is-released)
**Step 5:** [Report Errors and Warnings](#step-5-report-errors-and-warnings)
**Step 6:** [Report Stream Level Information](#step-6-report-stream-level-information)
**Step 7:** [Update Asset Information](#step-7-update-asset-information)
[Release Notes](#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`
{% tabs %}
{% tab title="1.7.1" %}
```java
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-media3:v1.7.1-2.4.0'
}
```
{% endtab %}
{% tab title="1.4.1" %}
```java
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-media3:v1.4.1-2.4.0'
}
```
{% endtab %}
{% tab title="1.3.1" %}
```gradle
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-media3:1.2.1'
}
```
{% endtab %}
{% endtabs %}
**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` :-
```gradle
dependencies {
...
api files ('mmsmartstreaming.aar')
}
```
#### Step 1.2: Add Permissions
Add network permissions to `$MEDIA3PROJECT/demos/main/src/main/AndroidManifest.xml`
```xml
```
#### Step 1.3: Import Packages
`$MEDIA3PROJECT/demos/main/src/main/java/androidx/media3/demo/main/PlayerActivity.java`
```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.
{% hint style="info" %}
The `enableLogTrace()` feature should be enabled for testing during the integration process. Set this to False before releasing the player to production.
```java
MMSmartStreamingMedia3.enableLogTrace(true);
```
{% endhint %}
#### Step 2.1: Set Context
Set the application context
```java
MMSmartStreamingMedia3.setContext(applicationContext)
```
#### Step 2.2: Register SDK
{% hint style="info" %}
CUSTOMER\_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at .
{% endhint %}
```java
MMSmartStreamingMedia3.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", true);
```
#### Step 2.3: Report Player Information
```java
MMSmartStreamingMedia3.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
```
#### Step 2.4: Report Base Player Information
```java
MMSmartStreamingMedia3.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
```
#### Step 2.5: Report Application Information
```java
MMSmartStreamingMedia3.reportAppInfo("APP_NAME","APP_VERSION");
```
#### Step 2.6: Initialize session with Content Metadata
```java
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
```java
MMSmartStreamingMedia3.reportExperimentName("EXPERIMENT_NAME");
```
#### Step 2.9: Report View Session Id
{% hint style="info" %}
Report the View Session Id attribute after `initializeSession` and before `reportUserInitiatedPlayback`.
{% endhint %}
```java
MMSmartStreamingMedia3.reportViewSessionId("VIEW_SESSION_ID");
```
#### Step 2.10: Report Sub Property Id
{% hint style="info" %}
Report the Sub Property ID attribute after `initializeSession` and before `reportUserInitiatedPlayback`.
{% endhint %}
```java
MMSmartStreamingMedia3.reportSubPropertyId("SUB_PROPERTY_ID");
```
#### Step 2.12: Report App Session ID
Report Application Session ID
```java
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.
```java
MMSmartStreamingMedia3.reportPlayerResolution(playerWidth, playerHeight);
```
### Step 3: Report Custom Metadata
Check the custom tags configuration in your [dashboard](https://smartsight3.mediamelon.com/settings) and report accordingly. If the custom tags are not configured, please configure and use them accordingly.
```java
MMSmartStreamingMedia3.reportCustomMetadata("custom_1","VALUE_1");
```
### Step 4: Report Ended State
In `$MEDIA3PROJECT/demos/main/src/main/java/androidx/media3/demo/main/PlayerActivity.java`
```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.
{% hint style="info" %}
⚠️ 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.
{% endhint %}
🚫 **Disabling Auto Error Capture:**
If you prefer to handle error reporting manually, you can disable this automatic behavior by calling:
```java
MMSmartStreamingMedia3.disableAutoErrorCapture(true);
```
{% hint style="info" %}
⚠️ 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.
{% endhint %}
**🛠️ 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**.
```java
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.
```java
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.
```java
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.
```java
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.
```java
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.
{% hint style="info" %}
**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
{% endhint %}
```java
MMSmartStreamingMedia3.updateAssetInfo(contentMetaData);
```
### Release Notes
Current Release
#### [**v2.4.0**](#user-content-fn-1)[^1]
* Added API to report CDN.
* Added events for AD-BUFFERING.
* Added support for Seek Duration
***
Previous Release
[^1]: Release Date: 11/3/2026
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/android/mediamelon-android-media3-sdk-integration-document.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.