# IMA Media3 v1.3.0 SDK Integration Document

### Prerequisites: <a href="#prerequisites" id="prerequisites"></a>

1. Google IMA DAI [Sample app](https://github.com/googleads/googleads-ima-android-dai) and [Documentation](https://developers.google.com/interactive-media-ads/docs/sdks/android/dai).
2. MediaMelon SmartSight SDK  maven dependencies or `smartstreaming-release.aar`.
3. MediaMelon-assigned Customer ID.

{% hint style="info" %}
**Note:** If you do not know your Customer ID contact MediaMelon at [support@mediamelon.com](mailto:support%40mediamelon.com)
{% endhint %}

### **Step 1: Set up the build environment** <a href="#step-1-set-up-the-build-environment" id="step-1-set-up-the-build-environment"></a>

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

**Using Maven:**

1. Add the following library to `BasicExample/app/build.gradle` :-

```gradle
dependencies {
    .
    .
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.24.0'
    implementation 'androidx.media3:media3-exoplayer:1.3.0'
    implementation 'com.github.MediamelonSDK:mm-sdk-media3-ima-android:1.0.3'
    .
    .
}
```

**Using ARR:**

1. Copy `smartstreaming-release.aar` provided with the release package to `BasicExample/app/`
2. Add the following library to `BasicExample/app/build.gradle` :-

```gradle
dependencies {
    .
    .
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.24.0'
    implementation 'androidx.media3:media3-exoplayer:1.3.0'
    api files ('smartstreaming-release.aar')
    .
    .
}
```

### Step 2: Import the required  MediaMelon SDK Classes: <a href="#step-2-add-mediamelon-library-to-sample-app" id="step-2-add-mediamelon-library-to-sample-app"></a>

#### **Step 2.1:** Add the below imports to:

`BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/MyActivity.java`

```java
import com.mediamelon.smartstreaming.MMAVAssetInformation;
import com.mediamelon.smartstreaming.MMQBRMode;
import com.mediamelon.smartstreaming.MMRegistrationInformation;
import com.mediamelon.smartstreaming.MMSmartStreaming;
import com.mediamelon.smartstreaming.MMSmartStreamingExo2;
```

#### **Step 2.2:** Add the below imports to:&#x20;

`BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/samplevideoplayer/SampleVideoPlayer.java`

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

#### **Step 2.3:** Add the below imports to:&#x20;

`BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/SampleAdsWrapper.java`

```java
import com.mediamelon.smartstreaming.MMAnalyticsBridge;
import com.mediamelon.smartstreaming.MMSmartStreamingExo2;
```

### Step 3: Integrate MediaMelon SDK  <a href="#step-3-integrate-mediamelon-code-to-the-sample-app" id="step-3-integrate-mediamelon-code-to-the-sample-app"></a>

The below steps describe the procedure to integrate the MediaMelon SDK into the application.&#x20;

{% hint style="info" %}
**Note -** Only the code written inside the *\<MediaMelon Integration>* tag is to be added for MediaMelon-specific integration, the rest of the code above and below the *\<MediaMelon Integration>* tag is shown just to give a context, as shown below:-
{% endhint %}

#### **Step 3.1:** Add the following code to:&#x20;

`BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/samplevideoplayer/SampleVideoPlayer.java`

```java
private void initPlayer() { // this is the function that creates/initialises the EXO player
  release();
  simpleExoPlayer = new SimpleExoPlayer.Builder(context).build();
  playerView.setPlayer(simpleExoPlayer);
  .
  .
  //<MediaMelon Integration>
  ContentMetadata cm  = new ContentMetadata();
  cm.videoId="VIDEO_ID";
  cm.seriesTitle="TITLE";
  cm.season="SEASON";
  cm.genre="GENRE";
  cm.episodeNumber="EPISODE_NUMBER";
  cm.drmProtection="DRM_PROTECTION";
  cm.contentType="CONTENT_TYPE";
  cm.assetName="ASSET_NAME";
  cm.assetId="ASSET_ID";
  cm.videoType = "VIDEO_TYPE";
  JSONObject ContentMetadataAsJSON = cm.getJSONObject();
  boolean isLive = false; //Set this to true for a live stream or to false for a VoD stream

  MMSmartStreamingExo2.getInstance().initializeSession(simpleExoPlayer, MMQBRMode.QBRModeDisabled, streamUrl, ContentMetadataAsJSON, isLive); //isLive is an optional field here
  MMSmartStreamingExo2.getInstance().reportCustomMetadata("key","value");   //(optional) add custom tags
  MMSmartStreamingExo2.getInstance().reportUserInitiatedPlayback();
  //<MediaMelon Integration>
};
```

```java
private void release() {
  if (simpleExoPlayer != null) {
    simpleExoPlayer.release();
    simpleExoPlayer = null;
    streamRequested = false;
    
    //<MediaMelon Integration>
    MMSmartStreamingExo2.getInstance().reportPlayerState(false, Player.STATE_ENDED);
    //<MediaMelon Integration>
  }
}
```

#### **Step 3.2:** Add the following code to:&#x20;

`BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/MyActivity.java`

```java
@Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);
    .
    .
    //<MediaMelon Integration>
    Log.d("SmartStreamingIntgr", MMSmartStreamingExo2.getVersion());
    MMSmartStreamingExo2.enableLogTrace(true); //set to "false" before releasing player to production
    if (MMSmartStreamingExo2.getRegistrationStatus() == false){ //Check if it is the first time Registration process is done
      MMSmartStreamingExo2.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG");
      MMSmartStreamingExo2.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
      MMSmartStreamingExo2.getInstance().setContext(getApplicationContext()); //Please make sure to provide the application's context here, and not the activity's context
    }
    //<MediaMelon Integration>
    .
    .
  }
```

<table><thead><tr><th width="274">Variable</th><th>Description</th></tr></thead><tbody><tr><td>PLAYER_NAME</td><td>String containing the player version (e.g. “Bitmovin_Android_Player_2.28.0”).</td></tr><tr><td>CUSTOMER_ID</td><td>String containing your MediaMelon-assigned Customer ID.</td></tr><tr><td>SUBSCRIBER_ID</td><td>String containing your subscriber’s ID. If you do not use subscriber IDs, enter null</td></tr><tr><td>DOMAIN_NAME</td><td>String containing your section of your subscriber or assets. (Optional)</td></tr><tr><td>SUBSCRIBER_TYPE</td><td>String containing the subscriber type (e.g. “Free”, “Paid”). If you do not use subscriber types, enter null</td></tr><tr><td>SUBSCRIBER_TAG</td><td>String containing an additional subscriber-specific information. This is sent in clear (not hashed) to SmartSight and it is advised to not send sensitive information in this field.</td></tr><tr><td>ASSET_ID</td><td>String containing Asset Id.</td></tr><tr><td>ASSET_NAME</td><td>String containing Asset Name.</td></tr><tr><td>VIDEO_ID</td><td>String containing your video’s ID. If you do not use videos IDs, enter null.</td></tr><tr><td>PLAYER_BRAND</td><td>String containing the player brand (e.g. “bitmovin”).</td></tr><tr><td>PLAYER_MODEL</td><td>String containing the player model. For example - This could be a variant of player. Say name of third party player used by organisation. Or any human readable name of the player.</td></tr><tr><td>PLAYER_VERSION</td><td>String containing the player version.</td></tr></tbody></table>

#### **Step 3.3:** Add the following code to:&#x20;

`BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/SampleAdsWrapper.java`

```java
private final ImaSdkFactory sdkFactory;
private AdsLoader adsLoader;
private StreamDisplayContainer displayContainer;
private StreamManager streamManager;
private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;
.
.
//<MediaMelon Integration>
MMAnalyticsBridge analyticsBridgeObject; // Declaration of Analytics Bridge object, wherever the IMA AdsLoader and IMA StreamManager are declared in your application
//<MediaMelon Integration>
```

```java
private void createAdsLoader() { // this functions creates the Google IMA DAI ads loader (which is preferably a singleton - only one ads loader for the entire lifecyle)
  ImaSdkSettings settings = sdkFactory.createImaSdkSettings();
  //<MediaMelon Integration>
  analyticsBridgeObject = MMSmartStreamingExo2.getInstance().getAnalyticsBridge(); // get the Analytics Bridge Object ,this should be done wherever in your application the Google IMA adsLoader is created
  //<MediaMelon Integration>
  .
  .
  adsLoader = sdkFactory.createAdsLoader(context, settings, displayContainer);
}
```

```java
public void requestAndPlayAds() {  
  .
  .
  //<MediaMelon Integration>
  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
  //<MediaMelon Integration>
  .
  .
  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this); 
  adsLoader.requestStream(buildStreamRequest());
  .
  . 
}
```

```java
 @Override
  public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
    .
    .
    //<MediaMelon Integration>
    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
    //<MediaMelon Integration>
    .
    .
    streamManager.addAdErrorListener(this);
    streamManager.addAdEventListener(this);
    streamManager.init();
    .
    .
  }
```

#### **Step 4**: AD Event callbacks from the SDK.&#x20;

A list of all Google IMA DAI AD events can be found [here](https://developers.google.com/interactive-media-ads/docs/sdks/android/dai/api/reference/com/google/ads/interactivemedia/v3/api/AdEvent.AdEventType).

```
  @Override
  public void onAdEvent(AdEvent event) { // this is a callback which gets called whenever a AD event occurs
    switch (event.getType()) {
     // Access all ad events here , this method will be automatically called whenever an ad event occurs
      case AD_PROGRESS:
      // write your own logic inside each case
        break;
      case FIRST_QUARTILE:
        // write your own logic inside each case
        break;
      case MIDPOINT:
        // write your own logic inside each case
        break;
      case THIRD_QUARTILE:
        // write your own logic inside each case
        break;
      case COMPLETED:
        // write your own logic inside each case
        break;
      default:
        log(String.format("Event: %s\n", event.getType()));
        break;
    }
  }
```


---

# 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.3.0-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.