MediaMelon Android Custom Multi Player SDK Integration Document

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

Step 1: Prerequisites and Setup

Step 2: Register and Initialize SDK

Step 3: Report Session Level Details

Step 4: Report Player Events

Step 5: Report Stream and Track Related Events

Step 6: Report Network Related Information

Step 7: Report Errors and Fallbacks

Step 8: Report Ad Events

Step 1: Prerequisites and Setup

• MediaMelon Media3 SDK Maven dependencies or the provided AAR file is necessary.

Step 1.1: Set up the build environment

$MEDIA3PROJECT = {Media3 - v1.x.x}

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

1. Add MediaMelon Media3 Maven dependency to $MEDIA3PROJECT/demos/main/build.gradle

2. Copy mmsmartstreaming.aar provided in the release package for the Media3 project. Example $MEDIA3PROJECT/demos/main/mmsmartstreaming.aar .

Maven

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

AAR file

Step 1.2: Provide Manifest Permissions

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 1.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.wrapper.smartstreaming.MMIntegrationWrapper;
import com.mediamelon.wrapper.smartstreaming.MMPlayerState;
import com.mediamelon.wrapper.smartstreaming.custom_sdk.MMSmartStreamingMedia3;

Step 2: 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].

Step 2.1: Get SDK instance

For every new player instance create a new sdk instance.

protected boolean initializePlayer() { 
    if (player == null) { 
    Intent intent = getIntent(); ...
    //get the instance of SDK 
    MMIntegrationWrapper sdkInstance = new MMSmartStreamingMedia3(); 
    
    initializeMediaMelon(sdkInstance); 
    ... 
}

Step 2.2: Initialize session with SDK instance

void initializeMediaMelon(MMIntegrationWrapper sdkInstance){
    sdkInstance.setContext(applicationContext)
    sdkInstance.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", false);
    sdkInstance.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");
    sdkInstance.reportBasePlayerInfo("BASE_PLAYER_NAME", "BASE_PLAYER_VERSION");
    sdkInstance.reportAppInfo("APP_NAME","APP_VERSION");
    sdkInstance.reportDeviceInfo(deviceInfo);
    sdkInstance.reportDeviceID("DEVICE_ID");
    
    ContentMetadata cm  = new ContentMetadata();
    cm.assetName="ASSET_NAME";
    cm.assetId="ASSET_ID";
    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.drmLevel = "DRM_LEVEL"
    
    sdkInstance.initializeSession(cm, "PLAYER_INSTANCE_ID");
    sdkInstance.reportUserInitiatedPlayback();
}

Device Info

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

Step 3: Report Session level details

Step 3.1 Report Experiment Name

Report the experiment names as a list of String.

sdkInstance.reportExperimentNames(List<String>);

Step 3.2: Report View Session Id

sdkInstance.reportViewSessionId("VIEW_SESSION_ID");

Step 3.3: Report Sub Property Id

sdkInstance.reportSubPropertyId("SUB_PROPERTY_ID");

Step 3.4: Report Time Shift Enabled / DVR enabled

sdkInstance.reportTimeShiftEnabled(isTimeShiftEnabled); // isTimeShiftEnabled -> boolean

Step 3.5: Report Page Type

sdkInstance.reportPageType("PAGE_TYPE");

Step 3.6: Report PiP Mode

Report the PiP status of the player. If the player goes into PiP mode throughout the session report true.

sdkInstance.reportPipEnabled(isPipEnabled); // isPipEnabled -> boolean

Step 3.7: Report Device Orientation

Report current orientation of device as string.

sdkInstance.reportDeviceOrientation("ORIENTATION");

Step 3.8: Report Custom Metadata

Report additional custom metadata

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

Step 4: Report Player Events

Step 4.1: Report Player State

Make sure to report MMPlayerState.STOPPED at the end of playback completion to mark session as ended.

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

MMPlayerState
PLAYING
PAUSED
STOPPED

Step 4.2: Report Buffering Events

//buffering start
sdkInstance.reportBufferingStarted();

//buffering complete
sdkInstance.reportBufferingCompleted();

Step 4.3 Report Seek Events

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

Step 4.4: Report Playback Position

Report Playback position in ms.

sdkInstance.reportPlaybackPosition(playbackpos);

Step 5: Report Stream and Track Related Information

Step 5.1: Report Stream URL

Report stream url that is currently being used.

sdkInstance.setStreamURL("STREAM_URL");

Step 5.2: Report Stream Information

Report Information related to stream

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

Step 5.3: Report Video Duration

sdkInstance.reportVideoDuration(inMilliSeconds);

Step 5.4: Report Track Related Information

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

Step 5.5: Report Rendition Changes

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

sdkInstance.reportRendition(renditionObject);

Rendition Object

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

Step 6: Report Network Related Information

Step 6.1 Report Network Info

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

Step 6.2: Report Request Status

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

RequestStatus
FAILED
CANCELLED

Step 6.3: Report Player Download rate

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

Step 7: Report Errors & Fallbacks

Step 7.1: Report Fatal Errors

//Custom Errors 
sdkInstance.reportError(ERROR_CODE_INT, "ERROR_MESSAGE", "ERROR_DETAILS");

Step 7.2: Report Warnings

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

Step 7.3: Report Stream Fallback event

Report fallback events in case a fallback strategy is applied.

sdkInstance.reportFallbackEvent("FALLBACK_STREAM_URL", "DESCRIPTION");

Step 7.4: Update DRM Type

sdkInstance.updateDRMType("DRM_TYPE", "DRM_LEVEL");

Step 7.5: Update Content Metadata

sdkInstance.updateContentMetadata(cm);

Step 8: Report Ad Events

Step 8.1: Report Ad Breaks

sdkInstance.reportAdBreakStarted();
sdkInstance.reportAdBreakEnded();

Step 8.2: Report Ad Start and End

sdkInstance.reportAdStarted(adInfoObject);
sdkInstance.reportAdEnd();

Step 8.3 Report Ad Quartile Events

sdkInstance.reportAdFirstQuartile();
sdkInstance.reportAdMidpoint();
sdkInstance.reportAdThirdQuartile();

Step 8.4 Report Ad Request/Response (Optional)

sdkInstance.reportAdRequest(map) // map -> Map<String, String>
sdkInstance.reportAdResponse(map)

AdInfo Object

adInfo.adTitle	The title or name of the ad, usually provided in the VAST metadata or by the ad server.
adInfo.adId	A unique identifier for the ad creative, often defined by the ad server or DSP.
adInfo.adCreativeId	The creative ID associated with the specific ad asset (video, image, etc.). Helps in tracking and reporting creative-level performance.
adInfo.adCreativeType	The format or type of the ad creative. For example, video/mp4, image/jpeg, etc., or linear, non-linear.
adInfo.adClient	The SDK or client library responsible for requesting and playing the ad. Example: Google IMA, Freewheel, SpotX.
adInfo.adPosition	The timing of the ad in relation to the main content: "pre" (before), "mid" (during), or "post" (after).
adInfo.adServer	The ad server or source that delivered the ad. Example: Google Ad Manager, Freewheel, etc.
adInfo.adResolution	The resolution of the ad video (e.g., 1920x1080), useful for reporting and quality monitoring.
adInfo.adUrl	The URL from which the ad video is fetched. Typically a media file or stream URL.
adInfo.adDuration	The total duration of the ad, in milliseconds. Example: 30000 = 30 seconds.
adInfo.adPodIndex	The index of the ad pod within the stream. Ad pods are groups of ads played together (like a commercial break).
adInfo.adPositionInPod	The position of the ad within its pod (e.g., 1st ad, 2nd ad in the group).
adInfo.adPodLendth	The total number of ads in the current pod. Useful for showing “Ad 2 of 5” type of UI.
adInfo.isBumper	A boolean (true/false) indicating whether the ad is a bumper ad (short ad, usually <6s, played at the start or end of ad breaks).
adInfo.adUniversalId	A String value to report Ad Universal ID.