# MediaMelon Android ExoPlayer SDK Integration Document
**Step 1:** [Set up the build environment](#step-2-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
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 ExoPlayer Maven dependency to `/build.gradle`
{% tabs %}
{% tab title="2.19.1" %}
```gradle
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-exoplayer:v2.19.1-2.3.5'
}
```
{% endtab %}
{% tab title="2.18.6" %}
```
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-exoplayer:v2.18.6:2.3.0'
}
```
{% endtab %}
{% tab title="2.17.1" %}
```gradle
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-exoplayer-2.17.1:2.3.0'
}
```
{% endtab %}
{% endtabs %}
**Using AAR:**
1. Copy `mmsmartstreaming.aar` provided in the release package. Example `$project/main/mmsmartstreaming.aar` .
{% tabs %}
{% tab title="2.19.1" %}
[`mmsmartstreaming.aar`](https://mediamelon-builds.s3.us-east-1.amazonaws.com/MM-RELEASE-BUILDS/SDK_RELEASES/Android/2025-11-4/mmsmartstreaming.aar)
{% endtab %}
{% tab title="2.18.6" %}
[`mmsmartstreaming.aar`](https://mediamelon-builds.s3.us-east-1.amazonaws.com/MM-RELEASE-BUILDS/SDK_RELEASES/Android/2025-05-06/mmsmartstreaming.aar)
{% endtab %}
{% tab title="2.17.1" %}
[`mmsmartstreaming.aar`](https://mediamelon-builds.s3.us-east-1.amazonaws.com/MM-RELEASE-BUILDS/SDK_RELEASES/Android/2025-04-24/mmsmartstreaming.aar)
{% endtab %}
{% endtabs %}
2. Add the following library to `build.gradle` :-
```gradle
dependencies {
...
api files ('mmsmartstreaming.aar')
}
```
#### Step 1.2 Provide Permissions
Add network permissions to `AndroidManifest.xml`
```xml
```
#### Step 1.3: Import Packages
Import dependencies in `PlayerActivity.java`
```java
import com.mediamelon.qubit.ep.ContentMetadata
import com.mediamelon.smartstreaming.exoplayer.MMSmartStreamingAdapter
import com.mediamelon.smartstreaming.exoplayer.MMSmartStreamingFactory
```
### 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.
#### Step 2.1 Get Adapter Instance
```java
MMSmartStreamingAdapter mmSmartStreamingAdapter = MMSmartStreamingFactory.getInstance();
```
#### Step 2.2: Set Context
Set the application context
```java
mmSmartStreamingAdapter.setContext(applicationContext)
```
#### Step 2.3: 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
mmSmartStreamingAdapter.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", true);
```
#### Step 2.4: Report Player Information
```java
mmSmartStreamingAdapter.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
```
#### Step 2.5: Report Base Player Information
```java
mmSmartStreamingAdapter.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
```
#### Step 2.6: Report Application Information
```java
mmSmartStreamingAdapter.reportAppInfo("APP_NAME","APP_VERSION");
```
#### Step 2.7: Initialize Session
```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";
mmSmartStreamingAdapter.initializeSession(Companion.getPlayer(), "STREAM_URL",contentMetaData, isLive);
mmSmartStreamingAdapter.reportUserInitiatedPlayback();
```
{% 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
mmSmartStreamingAdapter.enableLogTrace(true)
```
{% endhint %}
#### Step 2.8: Report Experiment Name
```java
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.reportSubPropertyId("SUB_PROPERTY_ID");
```
#### Step 2.11: 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
mmSmartStreamingAdapter.reportPlayerResolution(playerWidth, playerHeight);
```
#### Step 2.12: Report App Session ID
```java
mmSmartStreamingAdapter.reportAppSessionId("APP_SESSION_ID);
```
### 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
mmSmartStreamingAdapter.reportCustomMetadata("custom_1","VALUE1");
```
### Step 4: Report Ended State
Report ENDED state in `PlayerActivity` when playback ends.
{% hint style="info" %}
If not reported at the end of the playback, it may reflect a longer playtime.
{% endhint %}
```java
private void releasePlayer() {
if (player != null) {
player.release();
player = null;
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.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
mmSmartStreamingAdapter.updateAssetInfo(contentMetaData);
```
#### Release Notes
Current Release
#### v2.3.5[^1]
* Added API to report App Session ID.
* Added API to report CDN.
* Added events for AD-BUFFERING.
* Added support for Seek Duration
***
Previous Releases
[^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-exoplayer-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.