MediaMelon Android Bitmovin SDK Integration Document

This page describes the integration of the MediaMelon Player SDK with Bitmovin Player on the Android platform

Step 1: Set up the build environment

Step 2: Register and Initialise SDK

Step 3: Report Custom Metadata

Step 4: Report Stream Level Info

Step 5: Report Ended State

Step 6: Setup SSAI Ad Manager for Ad Callbacks

Step 7: Initialize Harmonic SSAI Ad Manager

Step 8: Update Asset Info dynamically

Release Notes

Step 1: Set up the build environment

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

1. Copy bitmovin-lib-release.aar provided with the release notes.

Step 1.1: Add Gradle Dependency:

Using AAR:

1. dependencies {
     ...
     api files ('bitmovin-lib-release.aar')
   }

Using Maven:

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

   dependencies {
       ...
       implementation("com.github.MediamelonSDK:mediamelon_bitmovin_sdk:1.3.5")
       ...
   }

Step 1.2 Provide Permissions

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

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Step 1.3: Import Packages

import com.mediamelon.qubit.ep.ContentMetadata;
import com.mediamelon.smartstreaming.MMAVAssetInformation;
import com.mediamelon.smartstreaming.MMPlayerState;
import com.mediamelon.smartstreaming.MMRegistrationInformation;
import com.mediamelon.smartstreaming.MMSmartStreaming;
import com.mediamelon.smartstreaming.ssai.harmonic.MMHarmonicSSAIAdInfo;
import com.mediamelon.smartstreaming.ssai.harmonic.MMHarmonicSSAIEventListeners;
import com.mediamelon.smartstreaming.bitmovin_harmonic_ssai.MMSmartStreamingBitmovinAdaptor;

Step 2: Register and Initialise SDK

The player application must register the MediaMelon Player SDK and provide player information once when the application launches. Please note that values provided in this integration step persist across video sessions. This is typically done when the player itself is initialised.

Step 2.1: Set Asset Information

MMAVAssetInformation assetInformation = new MMAVAssetInformation("ASSET_ID", "ASSET_NAME", "VIDEO_ID");
String jsonAssetInfo = assetInformation.toJSON();
MMSmartStreamingBitmovinAdaptor.JsonFromClient = jsonAssetInfo;

Step 2.2: Create Adaptor Instance

MMSmartStreamingBitmovinAdaptor mmSmartStreamingBitmovinAdaptor  = new MMSmartStreamingBitmovinAdaptor(getApplicationContext()) ;

Step 2.3: Set Registration and Player Information

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at [email protected].

Please provide the hashSubscriberId value in setSubscriberInformation(), hashSubscriberId boolean variable indicates whether the SUBSCRIBER_ID to be hashed or not.

MMRegistrationInformation registrationInformation = new MMRegistrationInformation("CUSTOMER_ID", "PLAYER_NAME");
registrationInformation.setPlayerInformation("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
registrationInformation.setDomain("DOMAIN_NAME");
boolean hashSubscriberId = true; 
registrationInformation.setSubscriberInformation("SUBSCRIBER_ID", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", hashSubscriberId);
MMSmartStreamingBitmovinAdaptor.setPlayerRegistrationInformation(registrationInformation, player, getApplicationContext());

Step 2.4: Set Stream URL

mmSmartStreamingBitmovinAdaptor.setURL(url);

Step 2.5: Report Base Player Information

MMSmartStreamingBitmovinAdaptor.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");

Step 2.6: Report Application Information

mmSmartStreamingBitmovinAdaptor.reportAppInfo("APP_NAME", "APP_VERSION");

Step 2.7: Report Content Metadata

ContentMetadata cm  = new ContentMetadata();

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";
cm.assetName="ASSET_NAME";
cm.assetId="ASSET_ID";

JSONObject jsonObj = cm.getJSONObject();
MMSmartStreamingBitmovinAdaptor.contentMetadataFromUser = jsonObj;

Step 2.8: Report Experiment Name

mmSmartStreamingBitmovinAdaptor.reportExperimentName("EXPERIMENT_NAME");

Step 2.9: Report View Session Id

mmSmartStreamingBitmovinAdaptor.reportViewSessionId("VIEW_SESSION_ID");

Step 2.10: Report Sub Property Id

mmSmartStreamingBitmovinAdaptor.reportSubPropertyId("SUB_PROPERTY_ID");

Step 2.11: Report Player Resolution

mmSmartStreamingBitmovinAdaptor.reportPlayerResolution(playerWidth, playerHeight);

Step 3: Report Custom Metadata

Check the custom tags configuration in your dashboard and report accordingly. If the custom tags are not configured, please configure and use them accordingly.

mmSmartStreamingBitmovinAdaptor.reportCustomMetadata("custom_1", "VALUE_1");

Step 4: Report Stream Level Information

Step 4.1: Report Stream Info

Report key stream attributes that describe the encoding and delivery method.

mmSmartStreamingBitmovinAdaptor.reportStreamInfo("STREAM_FORMAT", "MEDIA_TYPE", "SOURCE_TYPE", isLive)

Step 4.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.

mmSmartStreamingBitmovinAdaptor.reportCDN("CDN");

Step 5: Report Ended State

@Override
protected void onDestroy() {
    playerView.onDestroy();
    super.onDestroy();
    MMSmartStreaming.getInstance().reportPlayerState(MMPlayerState.STOPPED);
}

Step 6: Setup SSAI Ad Manager for Ad Callbacks

To handle Harmonic SSAI events, create an object of MMHarmonicSSAIEventListeners in the required class and implement the methods you need. Once implemented, add the listener to mmSmartStreamingBitmovinAdaptor as shown below:

 MMHarmonicSSAIEventListeners mmHarmonicSSAIEventListeners = new MMHarmonicSSAIEventListeners() {
    @Override
    public void onAdImpression(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdStarted(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdFirstQuartile(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdMidpoint(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdThirdQuartile(MMHarmonicSSAIAdInfo ssaiAdInfo) {}
    
    @Override
    public void onAdComplete(MMHarmonicSSAIAdInfo ssaiAdInfo) { }
 };
 mmSmartStreamingBitmovinAdaptor.addSSAIListener(mmHarmonicSSAIEventListeners);

6.1 MMHarmonicSSAIEventListners callbacks:

The following callbacks are available within the MMHarmonicSSAIEventListeners interface:

• onAdImpression

• onAdStarted

• onAdFirstQuartile

• onAdMidpoint

• onAdThirdQuartile

• onAdComplete

6.2 AdInfo Accessible Methods:

The AdInfo object provides several methods to access ad-related information:

• getAdClient()

• getAdCurrentPlaybackTime()

• getAdDuration()

• getAdStartTime()

• getAdEndTime()

• getAdId()

• getAdServer()

Step 7: Initialize Harmonic SSAI Ad Manager

• DASH PMM_URL: Send the final redirected URL with the pmm ID.

• HLS PMM_URL: Send the variant URL with the pmm ID.

Note: Call initializeHarmonicSSAIAdManager only once at the stream start.

mmSmartStreamingBitmovinAdaptor.initializeHarmonicSSAIAdManager("PMM_URL");

Step 8: Update Asset Info dynamically

If Asset Information needs to be updated dynamically during the live session without re-initiating the player, then the "updateAssetInfo” API can be used to update the new AssetInfo.

Note:

1. This API must be called for updating asset info for the live streams only

2. This API must be called after the Player has started the live-stream playback.

3. The new Asset Info Object will override the previous values, hence set all the required fields every time before calling this API.

MMAVAssetInformation newAssetInformation = new MMAVAssetInformation("ASSET_ID", "ASSET_NAME", "VIDEO_ID");
MMSmartStreamingBitmovinAdaptor.updateAssetInfo(newAssetInformation, player, "SEASON","GENRE","EPISODE_NUMBER","CONTENT_TYPE","VIDEO_TYPE","DRM_PROTECTION","SERIES_TITLE");

Release Notes

Current Release

v1.3.5

• Added API to report App Session ID.

• Added API to report CDN.

• Added events for AD-BUFFERING.

• Fix for Ad playtime for session with no ads.

• Updated folder structure

---

Previous Releases

v1.3.4

• Added API to report Application Information

• Added API to report Stream Information

v1.3.3

• Number field in streaming_progress removed