# IMA Media3 v1.2.1 SDK Integration Document

**Step 1:** [Prerequisites](#step-1-prerequisites)

**Step 2:** [Set up the build environment](#step-2-set-up-the-build-environment)

**Step 3:** [Import Packages](#step-3-import-packages)

**Step 4:** [Register and Initialise SDK](#step-3-initialize-session-and-report-user-intent-to-playback)

**Step 5:** [Report Experiment Name](#step-5-report-experiment-name)

**Step 6:** [Report Sub-Property Id](#step-6-report-sub-property-id)

**Step 7:** [Report View Session](#step-7-report-view-session-id)

**Step 8:** [Report Player Resolution](#step-8-report-player-resolution)

**Step 9:** [Report Custom Errors](#step-9-report-custom-errors-optional)

**Step 10:** [Report Ended State](#step-5-report-ended-state-when-the-player-instance-is-released)

**Step 11:** [Enable IMA/DAI Ad tracking](#step-6-enable-ima-dai-a-d-tracking)

### Step 1: Prerequisites

* Media3 - v1.2.1 sample application.
* MediaMelon Media3 SDK Maven dependencies or the provided AAR file is necessary.

### Step 2: Set up the build environment 

> `$MEDIA3PROJECT = {Media3 - v1.2.1}`

The SDK files should be added to the build environment and the required network permissions should be enabled.

#### **Using Maven:**

1. Add MediaMelon Media3 Maven dependency to `$MEDIA3PROJECT/demos/main/build.gradle`

```gradle
dependencies {
   ...
  implementation 'com.github.MediamelonSDK:mm-android-sdk-media3-ima:2.2.1'
}
```

#### **Using AAR:** 

1. Copy [`mmsmartstreaming.aar`](https://mediamelon-builds.s3.us-east-1.amazonaws.com/MM-RELEASE-BUILDS/SDK_RELEASES/Android/2025-02-07/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')
}
```

Add network permissions to `$MEDIA3PROJECT/demos/main/src/main/AndroidManifest.xml`

```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`

```java
import com.mediamelon.qubit.ep.ContentMetadata;
import com.mediamelon.smartstreaming.MMQBRMode;
import com.mediamelon.smartstreaming.media3_ima.MMAnalyticsBridge;
import com.mediamelon.smartstreaming.media3_ima.MMSmartStreamingExo2;
```

### Step 4: Register and Initialise SDK <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

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 %}

{% hint style="info" %}
CUSTOMER\_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at <customer-support@mediamelon.com>.
{% endhint %}

```java
protected boolean initializePlayer() {
   
   // after the player is initialized and the player instance is not null
   initializeMediaMelon();
   ...
 }

void initializeMediaMelon(){
     MMSmartStreamingExo2.enableLogTrace(false);
    if (MMSmartStreamingExo2.getRegistrationStatus() == false)
    {
      MMSmartStreamingExo2.getInstance().setContext(getApplicationContext()); //Please make sure to provide the application's context here, and not the activity's context
      boolean hashSubscriberId = true;
      MMSmartStreamingExo2.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", hashSubscriberId);
      MMSmartStreamingExo2.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
      MMSmartStreamingExo2.getInstance().reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
      
      MMSmartStreamingExo2.reportAppInfo("APP_NAME","APP_VERSION");
      MMSmartStreamingExo2.getInstance().setDeviceInfo("DEVICE_MARKETING_NAME");
      
      //call this function to enable custom error reporting 
      MMSmartStreamingExo2.getInstance().enableCustomErrorReporting(true);
    }
    

    ContentMetadata cm  = new ContentMetadata();
    cm.assetName="ASSET_NAME";
    cm.assetId="ASSET_ID";
    cm.videoId="VIDEO_ID";
    cm.seriesTitle="SERIES_TITLE";
    cm.season="SEASON";
    cm.genre="GENRE";
    cm.episodeNumber="EPISODE_NUMBER";
    cm.drmProtection="DRM_PROTECTION";
    cm.contentType="CONTENT_TYPE";
    JSONObject contentMetadata = cm.getJSONObject();
    
    boolean isLive = false;
    MMSmartStreamingExo2.getInstance().initializeSession(player, MMQBRMode.QBRModeDisabled, streamURL, contentMetadata, isLive);
    MMSmartStreamingExo2.getInstance().reportUserInitiatedPlayback();
    MMSmartStreamingExo2.getInstance().reportCustomMetadata("CUSTOM_KEY_1","VALUE1");
 }
```

### Step 5: Report Experiment Name

```java
MMSmartStreamingExo2.getInstance().reportExperimentName("EXPERIMENT_NAME");
```

### Step 6: Report Sub-Property Id

```java
MMSmartStreamingExo2.getInstance().reportSubPropertyId("SUB_PROPERTY_ID");
```

### Step 7: Report View Session Id

```java
MMSmartStreamingExo2.getInstance().reportViewSessionId("VIEW_SESSION_ID");
```

### Step 8: Report Player Resolution

```java
MMSmartStreamingExo2.getInstance().reportPlayerResolution(playerWidth, playerHeight);
```

### Step 9: Report Custom Errors

{% hint style="info" %}
Make sure that `enableCustomErrorReporting` is set to `true` for this to be able to report errors&#x20;
{% endhint %}

```java
MMSmartStreamingExo2.getInstance().reportError("ERROR_CODE", "ERROR_MESSAGE", "ERROR_DESCRIPTION");
```

### Step 10: Report Ended State <a href="#step-5-report-ended-state-when-the-player-instance-is-released" id="step-5-report-ended-state-when-the-player-instance-is-released"></a>

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 11: Enable IMA/DAI Ad tracking

Add the following steps to enable IMA/DAI Ad tracking

#### 11.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();
```

#### 11.b: DAI Ad Tracking

The function `onAdsManagerLoaded` is part of `AdsLoader.AdsLoadedListener`&#x20;

```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();
    }
}
```


---

# 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/ima-media3-v1.2.1-sdk-integration-document.md?ask=<question>
```

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.