Custom SDK Integration Document

This guide provides detailed instructions on integrating the Android MediaMelon Custom SDK.

Step 1: Prerequisites

Step 2: Set up the build environment

Step 3: Import Packages

Step 4: Register and Initialise SDK

Step 5: Report Experiment Name

Step 6: Report Sub-Property Id

Step 7: Report View Session

Step 8: Report Player State

Step 9: Report Stream URL

Step 10: Report Manifest Status

Step 11: Report Stream Related Information

Step 12: Report Network Related Information

Step 13: Report Track Related Information

Step 14: Report Errors

Step 15: Report Video Duration

Step 16: Report Seek Events

Step 17: Report Buffering Events

Step 18: Report Rendition Changes

Step 19: Report Fallback Event

Step 20: Update DRM Type

Step 21: Update Content Metadata

Step 22: Report Session End

Step 23: Report Ad Events

Step 24: Report Chunk Status

Step 25: Update Subscriber Info

Step 26: Report Request Status

Step 27: Report Warnings

Step 28: Report Player Download Rate

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

dependencies {
   ...
  implementation 'com.github.MediamelonSDK:mm-java-custom-sdk:1.2.5'
}

Using AAR:

1. Copy 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 :-

dependencies {
  ...
  api files ('mmsmartstreaming.aar')
}

Add network permissions to $MEDIA3PROJECT/demos/main/src/main/AndroidManifest.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

import com.mediamelon.core.qubit.ChunkStatus;
import com.mediamelon.core.qubit.ChunkType;
import com.mediamelon.core.qubit.DeviceInfo;
import com.mediamelon.core.qubit.ManifestStatus;
import com.mediamelon.core.qubit.Rendition;
import com.mediamelon.core.qubit.ep.AdInfo;
import com.mediamelon.core.qubit.ep.ContentMetadata;
import com.mediamelon.core.qubit.RequestStatus;
import com.mediamelon.wrapper.smartstreaming.MMPlayerState;
import com.mediamelon.wrapper.smartstreaming.custom_sdk.MMSmartStreamingMedia3;

Step 4: Register and Initialise SDK

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.

The enableLogTrace() feature should be enabled for testing during the integration process. Set this to False before releasing the player to production.

MMSmartStreamingMedia3.enableLogTrace(false);

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

protected boolean initializePlayer() {
   if (player == null) {
   Intent intent = getIntent();
   ...
   // after the player is initialized and the player instance is not null
   initializeMediaMelon();
   ...
 }

void initializeMediaMelon(){

    MMSmartStreamingMedia3.setContext(applicationContext)
    MMSmartStreamingMedia3.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", true);
    MMSmartStreamingMedia3.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
    MMSmartStreamingMedia3.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
    MMSmartStreamingMedia3.reportAppInfo("APP_NAME","APP_VERSION");
    MMSmartStreamingMedia3.reportDeviceInfo(deviceInfo);
    MMSmartStreamingMedia3.reportDeviceID("DEVICE_ID");

    ContentMetadata contentMetadata  = new ContentMetadata();
    contentMetadata.assetName="ASSET_NAME";
    contentMetadata.assetId="ASSET_ID";
    contentMetadata.videoId="VIDEO_ID";
    contentMetadata.seriesTitle="SERIES_TITLE";
    contentMetadata.season="SEASON";
    contentMetadata.genre="GENRE";
    contentMetadata.episodeNumber="EPISODE_NUMBER";
    contentMetadata.drmProtection="DRM_PROTECTION";
    contentMetadata.contentType="CONTENT_TYPE";
    
    sdkInMMSmartStreamingMedia3stance.initializeSession(cm);
    MMSmartStreamingMedia3.reportUserInitiatedPlayback();
    MMSmartStreamingMedia3.reportCustomMetadata("custom_1","VALUE_1");
 }

Device Info

Parameter	Data Type
brand	String
deviceModel	String
os	String
osVersion	String
telecomOperator	String
screenWidth	String
screenHeight	String

Content Metadata

Parameter	Data Type
assetId	String
assetName	String
videoId	String
seriesTitle	String
season	String
genre	String
episodeNumber	String
contentType	String
drmProtection	String

Step 5: Report Experiment Name

MMSmartStreamingMedia3.reportExperimentName("EXPERIMENT_NAME");

Step 6: Report View Session Id

MMSmartStreamingMedia3.reportViewSessionId("VIEW_SESSION_ID");

Step 7: Report Sub Property Id

MMSmartStreamingMedia3.reportSubPropertyId("SUB_PROPERTY_ID");

Step 8: Report Player State

// Report Player State --> Playing, Paused, Stopped
MMSmartStreamingMedia3.reportPlayerState(MMPlayerState.PLAYING);

MMPlayerState
PLAYING
PAUSED
STOPPED

Step 9: Report Stream URL

Report stream url that is currently being used.

MMSmartStreamingMedia3.setStreamURL("STREAM_URL");

Step 10: Report Manifest Status

Report the status of the Manifest Request as SUCCESS, FAILED, CANCELLED

MMSmartStreamingMedia3.reportManifestRequestStatus(ManifestStatus.SUCCESS, "DESCRIPTION");

ManifestStatus
SUCCESS
FAILED
CANCELLED

Step 11: Report Stream Related Information

Report Information related to stream

MMSmartStreamingMedia3.reportStreamInfo("STREAM_FORMAT", "MEDIA_TYPE", "SOURCE_TYPE", isLive);

Step 12: Report Network Related Information

MMSmartStreamingMedia3.reportNetworkInfo("CDN", "ASN", "HOST_NAME", "NETWORK_TYPE", "NETWORK_OPERATOR"); 

Step 13: Report Track Related Information

MMSmartStreamingMedia3.reportTrackInfo("AUDIO_TRACK", "SUBTITLE_TRACK", isSubtitleActive, isVDSActive, "VIDEO_TRACK");

Step 14: Report Errors

//Custom Errors 
MMSmartStreamingMedia3.reportError(ERROR_CODE_INT, "ERROR_MESSAGE", "ERROR_DETAILS");
//Application Errors
MMSmartStreamingMedia3.reportApplicationError(ERROR_CODE_INT, "ERROR_MESSAGE", "ERROR_DETAILS");
//Business Errors
MMSmartStreamingMedia3.reportBusinessError(ERROR_CODE_INT, "ERROR_MESSAGE", "ERROR_DETAILS");

Step 15: Report Video Duration

MMSmartStreamingMedia3.reportVideoDuration(inMilliSeconds);

Step 16: Report Seek Events

//seek started
MMSmartStreamingMedia3.reportSeekStarted();
      
//seek completed
MMSmartStreamingMedia3.reportSeekCompleted();

Step 17: Report Buffering Events

//buffering start
MMSmartStreamingMedia3.reportBufferingStarted();

//buffering complete
MMSmartStreamingMedia3.reportBufferingCompleted();

Step 18: Report Rendition Changes

Report changes in the rendition of current stream wrapped in the Rendition object.

MMSmartStreamingMedia3.reportRendition(renditionObject);

Rendition Object

Parameter	Data Type
bitrate	int
width	int
height	int
frameRate	double
aCodec	String
vCodec	String

Step 19: Report Fallback event

Report fallback events in case a fallback strategy is applied.

MMSmartStreamingMedia3.reportFallbackEvent("STREAM_URL", "DESCRIPTION");

Step 20: Update DRM Type

MMSmartStreamingMedia3.updateDRMType("DRM_TYPE");

Step 21: Update Content Metadata

MMSmartStreamingMedia3.updateContentMetadata(cm);

Step 22: Report Session End

MMSmartStreamingMedia3.reportPlayerState(MMPlayerState.ENDED);

Step 23: Report Ad Events

MMSmartStreamingMedia3.reportAdBreakStarted();
MMSmartStreamingMedia3.reportAdBreakEnded();
MMSmartStreamingMedia3.reportAdStarted(adInfoObject);
MMSmartStreamingMedia3.reportAdEnd();

AdInfo Object

Parameter	Data Type
adClient	String
adId	String
adDuration	Double
adPosition	String
adType	MMAdType
adCreativeType	String
adServer	String
adResolution	String
adPodIndex	int
adPositionInPod	int
isBumper	Boolean
adScheduledTime	double
adCreativeId	String
adUrl	String
adTitle	String
adBitRate	int
adTimeStamp	Long

Step 24: Report Chunk Request Status

MMSmartStreamingMedia3.reportChunkRequestStatus(chunkStatus, chunkType, map);// map -> HashMap<String, String>

ChunkStatus
FAILED
CANCELLED

Chunk Type
AUDIO
VIDEO

Step 25: Update Subscriber Info

MMSmartStreamingMedia3.updateSubscriberInfo("SUB_ID_NEW", "SUB_TYPE_NEW", "SUB_TAG_NEW");

Step 26: Report Request Status

MMSmartStreamingMedia3.reportRequestStatus(RequestStatus, "REQUEST_TYPE", map); // map -> Map<String, String>

Request Status
FAILED
CANCELLED

Step 27: Report Warnings

Report non fatal errors as warnings

MMSmartStreamingMedia3.reportWarning(ERROR_CODE_INT, "ERROR_MESSAGE", "ERROR_DETAILS");

Step 28: Report Player Download Rate

Report Player download rate in bps

MMSmartStreamingMedia3.reportPlayerDownloadRate(bps) //  bps -> Long