Bitmovin Android v3 (Nowtilus SSAI) with Content Provider Metrics

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

Prerequisites

1. Bitmovin Android Sample Player https://github.com/bitmovin/bitmovin-player-android-samples

2. MediaMelon SmartSight SDKsmartstreaming-release.aar

3. MediaMelon-assigned Customer ID

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

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 smartstreaming-release.aar provided with the release package to BasicPlayback/smartstreaming-release.aar

2. Add network permissions to

   app/src/main/AndroidManifest.xml

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   
   <!-- <MMSmartStreaming 1a> -->
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
   <!-- </MMSmartStreaming 1a> -->

3. Add the following library to BasicPlayback/build.gradle :-

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

Step 2: Integrate MediaMelon Player SDK Code to Basic Playback App

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

import com.mediamelon.smartstreaming.MMAVAssetInformation;
import com.mediamelon.smartstreaming.MMRegistrationInformation;
import com.mediamelon.smartstreaming.MMSmartStreaming;
import com.mediamelon.smartstreaming.MMSmartStreamingBitmovinAdaptor;
import com.mediamelon.smartstreaming.MMSSAIEventsListeners;
import com.mediamelon.smartstreaming.mmAd;
import com.mediamelon.smartstreaming.mmAdTimelineInfo;
import com.mediamelon.smartstreaming.MMSmartStreamingNowtilusSSAIPlugin;
import com.mediamelon.qubit.ep.ContentMetadata;

Note:

Please provide the exact correct details in all fields like CUSTOMER_ID, ASSET_ID, ASSET_TITLE, VIDEO_ID, PLAYER_BRAND, PLAYER_MODEL, PLAYER_VERSION, PLAYER_NAME, DOMAIN_NAME, SUBSCRIBER_ID, SUBSCRIBER_TYPE & SUBSCRIBER_TAG.

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

This data helps in debugging through MediaMelon SmartSight if anything goes wrong.

Added the isLive API in sample application, if isLive value needs to set externally then use the following API, else if it needs to set by the player then don’t call the API.

MMSmartStreamingBitmovinAdaptor.setIsLive(true);//for live streams pass true,else false

protected void initializePlayer() {
    //Player creation
    player = Player.create(this);
    playerView.setPlayer(player);

    // MediaMelon code
    String assetId  = "assetID"; //enter you assetId here
    String assetName = "assetNAME"; // enter your assetname here
    String videoId = "videoID"; // enter your videoId here
    MMAVAssetInformation assetInformation = new MMAVAssetInformation(assetId, assetName, videoId);
    String jsonAssetInfo = assetInformation.toJSON();
    MMSmartStreamingBitmovinAdaptor mmSmartStreamingBitmovinAdaptor  = new MMSmartStreamingBitmovinAdaptor(getApplicationContext()) ;
    MMSmartStreamingBitmovinAdaptor.JsonFromClient=jsonAssetInfo;
    MMSmartStreamingBitmovinAdaptor.enableLogTrace(false); //set this to false before releasing to production
    MMSmartStreamingBitmovinAdaptor.getVersion();
    //set the isLive value
    MMSmartStreamingBitmovinAdaptor.setIsLive(true);//For Live streams true, else false
    //register customer
    MMRegistrationInformation registrationInformation = new MMRegistrationInformation("CustomerID", "PlayerName");
    //register the player
    registrationInformation.setPlayerInformation("PlayerBrand", "PlayerModel", "PlayerVersion");
    registrationInformation.setDomain("DOMAINNAME");
    registrationInformation.setSubscriberInformation("SUBSCRIBERID", "SUBSCRIBERTYPE", "SUBSCRIBERTAG","doHash");
    MMSmartStreamingBitmovinAdaptor.setPlayerRegistrationInformation(registrationInformation, player, this);
    String url  = "Provide Session Resolver URL here";
    String[] arr = url.split("api-key=");
    String nowtilusApikey = arr[1];
    mmSmartStreamingBitmovinAdaptor.setContentProviderDetails(url);
    mmSmartStreamingBitmovinAdaptor.setURL(url);  
    MMSmartStreamingBitmovinAdaptor.apikey  = nowtilusApikey;
    //change the below sourceType according to the stream format for eg : SourceType.Dash
    SourceConfig sourceConfiguration = new SourceConfig(url, SourceType.Hls);
    Source playerSource  = Source.create(sourceConfiguration);
    MMSmartStreaming.getInstance().reportUserInitiatedPlayback();
    //load the source into the player
    this.player.load(playerSource);

    }

Variable	Description
$PLAYERNAME	String containing the player version (e.g. “Bitmovin_Android_Player_2.28.0”).
$CUSTOMERID	String containing your MediaMelon-assigned Customer ID.
$SUBSCRIBERID	String containing your subscriber’s ID. If you do not use subscriber IDs, enter null
$DOMAINNAME	String containing your section of your subscriber or assets. (Optional)
$SUBSCRIBERTYPE	String containing the subscriber type (e.g. “Free”, “Paid”). If you do not use subscriber types, enter null
$SUBSCRIBERTAG	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.
$ASSETID	String containing Asset Id.
$ASSETNAME	String containing Asset Name.
$VIDEOID	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 : (Optional) Report Content Metadata

Optionally, the user of the MediaMelon Player SDK may choose to set additional content metadata metrics as below:

To enable Content Metadata , user need to include the following package in BasicPlayback app.

import com.mediamelon.qubit.ep.ContentMetada;

 //optional content metadata
 ContentMetadata cm  = new ContentMetadata();
 String episodeNumber = "EpisodeNumber";
 String season = "Season";
 String genre = "Genre";
 String drmProtection = "drmProtection";
 String contentType = "contentType";
 String title = "Title";
 cm.videoId=videoId;
 cm.seriesTitle=title;
 cm.season=season;
 cm.genre=genre;
 cm.episodeNumber=episodeNumber;
 cm.drmProtection=drmProtection;
 cm.contentType=contentType;
 cm.assetName=assetName;
 cm.assetId=assetId;
 JSONObject j = cm.getJSONObject();
 MMSmartStreamingBitmovinAdaptor.contentMetadataFromUser=j;
 //optional content metadata

Step 4: (Optional) Disable Manifest Fetch

If your workflow restricts the manifest to be accessible from both player and SDK simultaneously, then, you can disable the fetch of manifest via API disableManifestsFetch:

 MMSmartStreamingBitmovinAdaptor.disableManifestsFetch(true);

Step 5:(Optional) Report custom metadata

mmSmartStreamingBitmovinAdaptor.reportCustomMetadata("key", "VALUE_STRING");

Step 6: Report player ended call in onDestroy() Listener in sample application

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

Step 7:(Optional) Update assetInfo 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 playback of the live stream.

3. New Asset Info Object will override the previous values, Hence set all the fields that are required every time calling this API.

    // make a new MMAVAssetInformation  object
   MMAVAssetInformation newAssetInformation = new MMAVAssetInformation("$assetId", "$assetName", "$videoId");
   // add the new updated content metadata (episodeNumber, genre, seriesTitle...) 
   MMSmartStreamingBitmovinAdaptor.updateAssetInfo(newAssetInformation,player,"$season","$genre","$episodeNumber","$contentType","$videoType","$drmProtection","$seriesTitle");
           

Step 8: To Add Listener , get the Ad events from SSAIAdManager

//exposing the ad listeners to the player application
MMSSAIEventsListeners mmssaiEventsListeners = new MMSSAIEventsListeners() {
@Override
public void onAdImpression(mmAd ssaiAdInfo) {
}

@Override
public void onAdComplete(mmAd ssaiAdInfo) {
}

@Override
public void onCueTimelineEnter(mmAd ssaiAdInfo) {
}

@Override
public void onCueTimelineExit(mmAd ssaiAdInfo) {
}

@Override
public void onCueTimelineAdded(mmAdTimelineInfo timelineInfo) {
}

};
MMSmartStreamingNowtilusSSAIPlugin obj = mmSmartStreamingBitmovinAdaptor.getSSAIAdManager();
obj.addListener(mmssaiEventsListeners);

List of AD EVENTS

onAdImpression
onAdStarted
onAdFirstQuartile
onAdMidpoint
onAdThirdQuartile
onAdProgress
onAdComplete
onCueTimelineAdded 
onCueTimelineEnter
onCueTimelineExit

mmAd Object

{
String adId;
String adCreativeId;
String adTitle;
String adServer;
long adDuration;
long adCurrentPlaybackTimeInSec;
String position;
String streamType;
boolean isLinear;
int adIndex;
long startTimeInMs;
}

mmAdTimelineInfo Object

 {
 public ArrayList<mmAd> adInfos = new ArrayList<mmAd>();
   public int totalAds;
 }

COMPLETE INTEGRATION

 protected void initializePlayer() {
  //Player creation
 player = Player.create(this);
 playerView.setPlayer(player);

  // MediaMelon code
  String assetId  = "assetID"; //enter you assetId here
  String assetName = "assetNAME"; // enter your assetname here
  String videoId = "videoID"; // enter your videoId here

  //optional content metadata
  ContentMetadata cm  = new ContentMetadata();
  String episodeNumber = "EpisodeNumber";
  String season = "Season";
  String genre = "Genre";
  String drmProtection = "drmProtection";
  String contentType = "contentType";
  String title = "Title";
  cm.videoId=videoId;
  cm.seriesTitle=title;
  cm.season=season;
  cm.genre=genre;
  cm.episodeNumber=episodeNumber;
  cm.drmProtection=drmProtection;
  cm.contentType=contentType;
  cm.assetName=assetName;
  cm.assetId=assetId;
  JSONObject j = cm.getJSONObject();
  MMSmartStreamingBitmovinAdaptor.contentMetadataFromUser=j;
  //optional content metadata

  MMAVAssetInformation assetInformation = new MMAVAssetInformation(assetId, assetName, videoId);
  String jsonAssetInfo = assetInformation.toJSON();
  Log.i("jsonAssetInfo " , jsonAssetInfo);
  MMSmartStreamingBitmovinAdaptor mmSmartStreamingBitmovinAdaptor  = new MMSmartStreamingBitmovinAdaptor(getApplicationContext()) ;
  MMSmartStreamingBitmovinAdaptor.JsonFromClient=jsonAssetInfo;
  //report custome metadata
  mmSmartStreamingBitmovinAdaptor.reportCustomMetadata("key", "VALUE_STRING");
  MMSmartStreamingBitmovinAdaptor.enableLogTrace(false); //set this to false before production
  MMSmartStreamingBitmovinAdaptor.getVersion();
  //set the isLive value
      MMSmartStreamingBitmovinAdaptor.isLive  = true; //For live streams true, else false
  //register customer
  MMRegistrationInformation registrationInformation = new MMRegistrationInformation("CustomerID", "PlayerName");
  //register player
  registrationInformation.setPlayerInformation("PlayerBrand", "PlayerModel", "PlayerVersion");
  registrationInformation.setDomain("DOMAINNAME");
  registrationInformation.setSubscriberInformation("SUBSCRIBERID", "SUBSCRIBERTYPE", "SUBSCRIBERTAG","doHash");
  MMSmartStreamingBitmovinAdaptor.setPlayerRegistrationInformation(registrationInformation, player, this);
  //disable/enable manifest fetch
  MMSmartStreamingBitmovinAdaptor.disableManifestsFetch(true);
  String url  = "Provide Session Resolver URL here";
  String[] arr = url.split("api-key=");
  String nowtilusApikey = arr[1];
  mmSmartStreamingBitmovinAdaptor.setContentProviderDetails(url);
  mmSmartStreamingBitmovinAdaptor.setURL(url);
  MMSmartStreamingBitmovinAdaptor.apikey  = nowtilusApikey;
  //exposing the ad listeners to the player application
  MMSSAIEventsListeners mmssaiEventsListeners = new MMSSAIEventsListeners() {
  @Override
  public void onAdImpression(mmAd ssaiAdInfo) {
  }

  @Override
  public void onAdComplete(mmAd ssaiAdInfo) {
  }
  @Override
  public void onCueTimelineEnter(mmAd ssaiAdInfo) {
  }

  @Override
  public void onCueTimelineExit(mmAd ssaiAdInfo) {

  }

  @Override
  public void onCueTimelineAdded(mmAdTimelineInfo timelineInfo) {

  }
};

  MMSmartStreamingNowtilusSSAIPlugin obj = mmSmartStreamingBitmovinAdaptor.getSSAIAdManager();
  obj.addListener(mmssaiEventsListeners);
  SourceConfig sourceConfiguration = new SourceConfig(url, SourceType.Hls);
  Source playerSource  = Source.create(sourceConfiguration);
  MMSmartStreaming.getInstance().reportUserInitiatedPlayback();
  //load the source into the player
  this.player.load(playerSource);

    }