MediaMelon Android Custom SDK Integration Document

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

Step 1: Set up the build environment

Step 1.1: Add Gradle Dependency:

Add MediaMelon SDK gradle dependency to app/build.gradle

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

Step 1.2 Provide Permissions

Add network permissions to 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

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 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);

Step 2.1: Set Context

Set the application context

MMSmartStreamingMedia3.setContext(applicationContext)

Step 2.2: Register SDK

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

MMSmartStreamingMedia3.registerMMSmartStreaming("PLAYER_NAME", "CUSTOMER_ID", "SUBSCRIBER_ID", "DOMAIN_NAME", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG", true);

Step 2.3: Report Player Information

MMSmartStreamingMedia3.reportPlayerInfo("PLAYER_BRAND", "PLAYER_MODEL", "PLAYER_VERSION");

Step 2.4: Report Base Player Information

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

Step 2.5: Report Application Information

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

Step 2.6: Report Device Information

MMSmartStreamingMedia3.reportDeviceInfo(deviceInfo);

Device Info Object Description

Parameter

Data Type

Description

brand

String

Company or Brand to which the device belongs. Ex: Samsung

deviceModel

String

Model Identifier of the device. Ex: SM-1921

deviceType

String

The type of device. Ex: Smart TV

String

Operatin system name. Ex: Android, iOS, etc

osVersion

String

Operating system verion. Ex: 14, 18.2.0

telecomOperator

String

Telecom operator currently used.

screenWidth

String

Screen width of the device

screenHeight

String

Screen height of the device

Step 2.7: Initialize session with Content Metadata

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";
    
    MMSmartStreamingMedia3.initializeSession(cm);
    MMSmartStreamingMedia3.reportUserInitiatedPlayback();

Content Metadata Object Description

Parameter

Data Type

Description

assetId

String

Unique identifier for the video asset.

assetName

String

Human-readable name or title of the video asset.

videoId

String

Unique identifier for the video content. It can be the same as Asset ID or a different logical ID used in your system.

seriesTitle

String

Title of the series to which the episode belongs.

season

String

Name or number of the season (e.g., "Season 1", "S2").

genre

String

Genre of the content, such as "Drama", "Comedy", "Documentary", etc.

episodeNumber

String

Episode number within a season. Useful for TV series or episodic content.

contentType

String

The category or type of content, e.g., "Movie", "Episode", "Clip", "LiveStream".

drmProtection

String

DRM technology used (e.g., “Widevine”, “FairPlay”, “PlayReady”). Use “Unknown” if the content is protected, but the DRM type is unknown. Leave blank for clear (non-DRM) content.

Step 2.8: Report Experiment Name

MMSmartStreamingMedia3.reportExperimentName("EXPERIMENT_NAME");

Step 2.9: Report View Session Id

Report the View Session Id attribute after initializeSession and before reportUserInitiatedPlayback.

MMSmartStreamingMedia3.reportViewSessionId("VIEW_SESSION_ID");

Step 2.10: Report Sub Property Id

Report the Sub Property ID attribute after initializeSession and before reportUserInitiatedPlayback.

MMSmartStreamingMedia3.reportSubPropertyId("SUB_PROPERTY_ID");

Step 2.11: Report Preload

Report the preload attribute after initializeSession and before reportUserInitiatedPlayback. The preload value is reset inside initializeSession, so reporting it before this method will be ignored. If you report it after reportUserInitiatedPlayback, the first event will not contain the preload field.

MMSmartStreamingMedia3.reportPreload(preload);// preload -> boolean

Step 2.12: Report App Session ID

Report Application Session ID

MMSmartStreamingMedia3.reportAppSessionId("APP_SESSION_ID");

Step 2.13: Report Device ID

MMSmartStreamingMedia3.reportDeviceId("DEVICE_ID");

Step 2.14 Report Device Marketing Name

MMSmartStreamingMedia3.reportDeviceMarketingName("DEVICE_MARKETING_NAME");

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.

MMSmartStreamingMedia3.reportCustomMetadata("custom_1","VALUE_1");
MMSmartStreamingMedia3.reportCustomMetadata("custom_2","VALUE_2");

Step 4: Report Playback Events

Step 4.1: Report Player State

Report the player state using the following function.

MMSmartStreamingMedia3.reportPlayerState(MMPlayerState.PLAYING);

MMPlayerState

Description

PLAYING

Report when video starts playing froma paused state or on first frame rendered

PAUSED

Report when video paused

STOPPED

Report when user exits the video playback

Step 4.2: Report Buffering Events

//buffering start
MMSmartStreamingMedia3.reportBufferingStarted();

//buffering complete
MMSmartStreamingMedia3.reportBufferingCompleted();

Step 4.3: Report Seek Events

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

Step 4.4: Report Errors

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

Step 4.5: Report Warnings

MMSmartStreamingMedia3.reportWarning(WARNING_INT, "WARNING_MESSAGE", "WARNING_DETAILS");

Step 4.6: Report Playback Position

MMSmartStreamingMedia3.reportPlaybackPosition(playbackPositionInMs)

Step 5.1: Report Stream URL

Report stream url that is currently being used.

MMSmartStreamingMedia3.setStreamURL("STREAM_URL");

Step 5.2: Report Video Duration

MMSmartStreamingMedia3.reportVideoDuration(inMilliSeconds);

Step 5.3: Report Stream Information

Report Information related to the stream

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

Step 5.4: Report Network Information

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

Use the reportNetworkInfo API to report the CDN along with other network information. If additional network information is not available, use reportCDN instead.

Step 5.5: Report CDN

MMSmartStreamingMedia3.reportCDN("CDN");

Step 5.6: Report Track Information

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

Step 5.7: Report Rendition

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

MMSmartStreamingMedia3.reportRendition(renditionObject);

Rendition Object

Parameter

Data Type

Description

bitrate

int

Current bitrate at which the video is playing

width

int

current width of the video

height

int

current height of the video

frameRate

double

current frame rate of the video

aCodec

String

current Audio Codec of video

vCodec

String

current Video Codec of video

Step 5.7: Update DRM Type

MMSmartStreamingMedia3.updateDRMType("DRM_TYPE");

Step 5.8: Report Player Download Rate

Report Player download rate in bps

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

Step 5.9: Report Frame Loss

MMSmartStreamingMedia3.reportFrameloss(frameloss) // frameloss -> Int

Step 6: Report Request Status and Fallback Events

Step 6.1: Report Request Status

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

RequestStatus (Enum)

Request Status

Description

FAILED

Report on a failed request

CANCELLED

Report on a cancelled request

Step 6.2: Report Fallback event

Report fallback events in case a fallback strategy is applied.

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

Step 6.3: Update Content Metadata

MMSmartStreamingMedia3.updateContentMetadata(cm);

Step 6.4: Update Subscriber Info

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

Step 7: Report Ad Events

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

AdInfo Object

Parameter

Data Type

Description

adClient

String

The SDK or client library responsible for requesting and playing the ad. Example: Google IMA, Freewheel, SpotX.

adId

String

A unique identifier for the ad creative, often defined by the ad server or DSP.

adDuration

Double

The total duration of the ad, in milliseconds. Example: 30000 = 30 seconds.

adPosition

String

The timing of the ad in relation to the main content: "pre" (before), "mid" (during), or "post" (after).

adCreativeType

String

The format or type of the ad creative. For example, video/mp4, image/jpeg, etc., or linear, non-linear.

adServer

String

The ad server or source that delivered the ad. Example: Google Ad Manager, Freewheel, etc.

adResolution

String

The resolution of the ad video (e.g., 1920x1080), useful for reporting and quality monitoring.

adPodIndex

int

The index of the ad pod within the stream. Ad pods are groups of ads played together (like a commercial break).

adPositionInPod

int

The position of the ad within its pod (e.g., 1st ad, 2nd ad in the group).

isBumper

Boolean

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

adCreativeId

String

The creative ID associated with the specific ad asset (video, image, etc.). Helps in tracking and reporting creative-level performance.

adUrl

String

The URL from which the ad video is fetched. Typically a media file or stream URL.

adTitle

String

The title or name of the ad, usually provided in the VAST metadata or by the ad server.

adBitRate

int

Bitrate at which the ad is playing

adTimeStamp

Long

Timestamp of ad as received

Release Notes

Current Release

v1.2.9

Added an additional API to report CDN alone.
Added CDN_CHANGE event.
Added Internal functionality to report seek duration.

Previous Releases

v1.2.8

Added Api to report frame loss
Added Api to report Device ID
Added Api to report Device Marketing Name
Internal Improvements for Device Info and Network Info
Improved bitrate reporting for weighted average bitrate calculation
Updated internal SDK version format

v1.2.7

Preload field addition
App Session Id field addition
Fix to consider Exit in Buffering
New metrics to enable upscale and downscale %s for bitrate and resolution
Improved failed and offline payloads queueing

v1.2.6

CPU optimisation
fix: ENDED event in case of EBVS

PreviousAndroid SDK NextMediaMelon Android Media3 SDK Integration Document

Last updated 8 minutes ago

hashtagStep 1: Set up the build environment

hashtagStep 1.1: Add Gradle Dependency:

hashtagStep 1.2 Provide Permissions

hashtagStep 1.3: Import Packages

hashtagStep 2: Register and Initialise SDK

hashtagStep 2.1: Set Context

hashtagStep 2.2: Register SDK

hashtagStep 2.3: Report Player Information

hashtagStep 2.4: Report Base Player Information

hashtagStep 2.5: Report Application Information

hashtagStep 2.6: Report Device Information

hashtagStep 2.7: Initialize session with Content Metadata

hashtagStep 2.8: Report Experiment Name

hashtagStep 2.9: Report View Session Id

hashtagStep 2.10: Report Sub Property Id

hashtagStep 2.11: Report Preload

hashtagStep 2.12: Report App Session ID

hashtagStep 2.13: Report Device ID

hashtagStep 2.14 Report Device Marketing Name

hashtagStep 3: Report Custom Metadata

hashtagStep 4: Report Playback Events

hashtagStep 4.1: Report Player State

hashtagStep 4.2: Report Buffering Events

hashtagStep 4.3: Report Seek Events

hashtagStep 4.4: Report Errors

hashtagStep 4.5: Report Warnings

hashtagStep 4.6: Report Playback Position

hashtagStep 5: Report Stream and Network Related Information

hashtagStep 5.1: Report Stream URL

hashtagStep 5.2: Report Video Duration

hashtagStep 5.3: Report Stream Information

hashtagStep 5.4: Report Network Information

hashtagStep 5.5: Report CDN

hashtagStep 5.6: Report Track Information

hashtagStep 5.7: Report Rendition

hashtagStep 5.7: Update DRM Type

hashtagStep 5.8: Report Player Download Rate

hashtagStep 5.9: Report Frame Loss

hashtagStep 6: Report Request Status and Fallback Events

hashtagStep 6.1: Report Request Status

hashtagStep 6.2: Report Fallback event

hashtagStep 6.3: Update Content Metadata

hashtagStep 6.4: Update Subscriber Info

hashtagStep 7: Report Ad Events

hashtagRelease Notes

hashtagv1.2.9

hashtagv1.2.8

hashtagv1.2.7

hashtagv1.2.6

Step 1: Set up the build environment

Step 1.1: Add Gradle Dependency:

Step 1.2 Provide Permissions

Step 1.3: Import Packages

Step 2: Register and Initialise SDK

Step 2.1: Set Context

Step 2.2: Register SDK

Step 2.3: Report Player Information

Step 2.4: Report Base Player Information

Step 2.5: Report Application Information

Step 2.6: Report Device Information

Step 2.7: Initialize session with Content Metadata

Step 2.8: Report Experiment Name

Step 2.9: Report View Session Id

Step 2.10: Report Sub Property Id

Step 2.11: Report Preload

Step 2.12: Report App Session ID

Step 2.13: Report Device ID

Step 2.14 Report Device Marketing Name

Step 3: Report Custom Metadata

Step 4: Report Playback Events

Step 4.1: Report Player State

Step 4.2: Report Buffering Events

Step 4.3: Report Seek Events

Step 4.4: Report Errors

Step 4.5: Report Warnings

Step 4.6: Report Playback Position

Step 5: Report Stream and Network Related Information

Step 5.1: Report Stream URL

Step 5.2: Report Video Duration

Step 5.3: Report Stream Information

Step 5.4: Report Network Information

Step 5.5: Report CDN

Step 5.6: Report Track Information

Step 5.7: Report Rendition

Step 5.7: Update DRM Type

Step 5.8: Report Player Download Rate

Step 5.9: Report Frame Loss

Step 6: Report Request Status and Fallback Events

Step 6.1: Report Request Status

Step 6.2: Report Fallback event

Step 6.3: Update Content Metadata

Step 6.4: Update Subscriber Info

Step 7: Report Ad Events

Release Notes

v1.2.9

v1.2.8

v1.2.7

v1.2.6