IMA Media3 v1.3.0 SDK Integration Document

This procedure describes the MediaMelon SDK(with Google IMA) Integration with a Media3 Android . This is a sample integration done with the sample application from the Google IMA.

Prerequisites:

1. Google IMA DAI Sample app and Documentation.

2. MediaMelon SmartSight SDK maven dependencies or smartstreaming-release.aar.

3. MediaMelon-assigned Customer ID.

Note: If you do not know your Customer ID contact MediaMelon at [email protected]

Step 1: Set up the build environment

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

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

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:

Step 2.1: Add the below imports to:

BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/MyActivity.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:

BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/samplevideoplayer/SampleVideoPlayer.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:

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

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

Step 3: Integrate MediaMelon SDK

The below steps describe the procedure to integrate the MediaMelon SDK into the application.

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

Step 3.1: Add the following code to:

BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/samplevideoplayer/SampleVideoPlayer.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>
};

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:

BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/MyActivity.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>
    .
    .
  }

Variable	Description
PLAYER_NAME	String containing the player version (e.g. “Bitmovin_Android_Player_2.28.0”).
CUSTOMER_ID	String containing your MediaMelon-assigned Customer ID.
SUBSCRIBER_ID	String containing your subscriber’s ID. If you do not use subscriber IDs, enter null
DOMAIN_NAME	String containing your section of your subscriber or assets. (Optional)
SUBSCRIBER_TYPE	String containing the subscriber type (e.g. “Free”, “Paid”). If you do not use subscriber types, enter null
SUBSCRIBER_TAG	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.
ASSET_ID	String containing Asset Id.
ASSET_NAME	String containing Asset Name.
VIDEO_ID	String containing your video’s ID. If you do not use videos IDs, enter null.
PLAYER_BRAND	String containing the player brand (e.g. “bitmovin”).
PLAYER_MODEL	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.
PLAYER_VERSION	String containing the player version.

Step 3.3: Add the following code to:

BasicExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/videoplayerapp/SampleAdsWrapper.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>

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

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

 @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.

A list of all Google IMA DAI AD events can be found here.

  @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;
    }
  }