# MediaMelon Android IMA 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 Custom Errors](#step-4-report-custom-errors)
**Step 5:** [Report Ended State](#step-5-report-ended-state-when-the-player-instance-is-released)
Step 6: [Report Stream Info](#step-6-report-stream-information)
**Step 7:** [Enable IMA/DAI Ad tracking](#step-7-enable-ima-dai-a-d-tracking)
[Release Notes](#releases-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`
{% tabs %}
{% tab title="1.4.0" %}
```java
dependencies {
...
implementation 'com.github.MediamelonSDK:mm-android-sdk-media3-ima:2.2.5'
}
```
{% endtab %}
{% endtabs %}
**Using AAR:**
1. Copy [`mmsmartstreaming.aar`](https://sdks.mediamelon.com/android/media3/IMA/2.2.5/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 Provide 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_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.
{% 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.
{% endhint %}
#### Step 2.1: Set Context
Set the application context
```java
MMSmartStreamingExo2.getInstance().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
MMSmartStreamingExo2.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", true);
```
#### Step 2.3: Report Player Information
```java
MMSmartStreamingExo2.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
```
#### Step 2.4: Report Base Player Information
```java
MMSmartStreamingExo2.getInstance().reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
```
#### Step 2.5: Report Application Information
```java
MMSmartStreamingExo2.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";
MMSmartStreamingExo2.getInstance().initializeSession(player, streamURL, contentMetadata, isLive);
MMSmartStreamingExo2.getInstance().reportUserInitiatedPlayback();
```
#### Step 2.7: Report Experiment Name
```java
MMSmartStreamingExo2.getInstance().reportExperimentName("EXPERIMENT_NAME");
```
#### Step 2.8: Report View Session Id
{% hint style="info" %}
Report the View Session Id attribute after `initializeSession` and before `reportUserInitiatedPlayback`.
{% endhint %}
```java
MMSmartStreamingExo2.getInstance().reportViewSessionId("VIEW_SESSION_ID");
```
#### Step 2.9: Report Sub Property Id
{% hint style="info" %}
Report the Sub Property ID attribute after `initializeSession` and before `reportUserInitiatedPlayback`.
{% endhint %}
```java
MMSmartStreamingExo2.getInstance().reportSubPropertyId("SUB_PROPERTY_ID");
```
#### Step 2.10: Report App Session ID
Report Application Session ID
```java
MMSmartStreamingExo2.getInstance().reportAppSessionId("APP_SESSION_ID");
```
#### Step 2.11: Report Player Resolution
```java
MMSmartStreamingExo2.getInstance().reportPlayerResolution(playerWidth, playerHeight);
```
### Step 3: Report Custom Metadata
```java
MMSmartStreamingExo2.getInstance().reportCustomMetadata("CUSTOM_KEY_1","VALUE1");
```
### Step 4: Report Custom Errors
{% hint style="info" %}
Make sure that `enableCustomErrorReporting` is set to `true` for this to be able to report errors
{% endhint %}
```java
MMSmartStreamingExo2.getInstance().reportError("ERROR_CODE", "ERROR_MESSAGE", "ERROR_DESCRIPTION");
```
### Step 5: 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;
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.
```java
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.
```java
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.
```java
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
```java
private final ImaSdkFactory sdkFactory;
private AdsLoader adsLoader;
private StreamDisplayContainer displayContainer;
MMAnalyticsBridge analyticsBridgeObject;
```
```java
//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);
```
```java
// 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
}
```
{% hint style="info" %}
Alternate method for IMA ad tracking
{% endhint %}
```java
adsLoader = new ImaAdsLoader.Builder(/* context= */ this)
.setAdEventListener(analyticsBridgeObject)
.setAdErrorListener(analyticsBridgeObject)
.build();
```
#### 7.b: DAI Ad Tracking
The function `onAdsManagerLoaded` is part of `AdsLoader.AdsLoadedListener`
```java
private StreamManager streamManager;
MMAnalyticsBridge analyticsBridgeObject;
```
```java
@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[^1]
* 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
[^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-ima-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.