MediaMelon Android Custom SDK Integration Document

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

Step 1: Set Up Build Environment

Step 2: Register and Initialize the SDK

Step 3: Report Custom Metadata

Step 4: Report Playback Events

Step 5: Report Stream and Network Related Information

Step 6: Report Request Status and Fallback Events

Step 7: Report Ad Events

Step 8: Report Custom Events

Release Notes

Step 1: Set up the build environment

Step 1.1: Add Gradle Dependency:

1. Add MediaMelon SDK gradle dependency to app/build.gradle

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

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 [e-mail].

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
os	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

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: Report Stream and Network Related Information

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 5.10: Report Encoding Service

MMSmartStreamingMedia3.reportEncodingService("ENCODING_SERVICE");

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

Step 7.1: Report Ad Start and End

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

Step 7.2: Report Ad Buffering:

Use Ad Buffering APIs to report any buffering that occurs during ad playback. For any buffering event, either content buffering or ad buffering should be reported, but not both.

MMSmartStreamingMedia3.reportAdBufferingStarted();
MMSmartStreamingMedia3.reportAdBufferingCompleted();

Step 8: Report Custom Events

The Custom Events API can be used to report events that are not covered by the default MediaMelon-supported events. Custom events must be reported within the SDK activity lifecycle. Events reported before SDK initialization or after session end will be ignored. Please refer to the guidelines and constraints below.

MMSmartStreamingMedia3.reportCustomEvent("EVENT_NAME", "EVENT_VALUE");

Guidelines & Constraints

• Event Name

  • Maximum length: 35 characters

  • Allowed characters: Alphanumeric and underscore (_) only

  • Special characters are not supported

  • Recommended format: UPPERCASE with underscores (e.g., DRM_CHANGE)

• Event Limits

  • A maximum of 35 custom events per session is allowed.

Custom events that violate these constraints (invalid event name or exceeding the per-session limit) will be dropped. Event values exceeding 1000 characters will be truncated to 1000 characters.

Release Notes

Current Release

v1.2.11 ^{_{Mar 27, 2026}}

• Added support for reporting a new field encoding service via reportEncodingService.

• Introduced custom event reporting through reportCustomEvent.

• Added support for ad buffering events:

  • reportAdBufferingStarted

  • reportAdBufferingCompleted

• Improved event handling to restrict event reporting after playback has ended.

---

Previous Releases

v1.2.10

• Skip Release

v1.2.9 ^{_{Feb 6, 2026}}

• Added an additional API to report CDN alone.

• Added CDN_CHANGE event.

• Added Internal functionality to report seek duration.

v1.2.8 ^{_{Dec 20, 2025}}

• 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 ^{_{Dec 3, 2025}}

• 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 ^{_{Oct 31, 2025}}

• CPU optimisation

• fix: ENDED event in case of EBVS