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:

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:

Copy mmsmartstreaming.aar provided in the release package for the Media3 project. Example $MEDIA3PROJECT/demos/main/mmsmartstreaming.aar .
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

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

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

PreviousAndroid SDK NextMedia3 SDK Integration Document

Last updated 9 days ago

Step 1: Prerequisites

Step 2: Set up the build environment

Using Maven:

Using AAR:

Step 3: Import Packages

Step 4: Register and Initialise SDK

Device Info

Content Metadata

Step 5: Report Experiment Name

Step 6: Report View Session Id

Step 7: Report Sub Property Id

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

Rendition Object

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

AdInfo Object

Step 24: Report Chunk Request Status

Step 25: Update Subscriber Info

Step 26: Report Request Status

Step 27: Report Warnings

Step 28: Report Player Download Rate