MediaMelon Android Multiplayer Custom SDK Integration Document

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

Step 1: Prerequisites and Setup

Step 2: Instantiate and Register SDK

Step 3: Initialize Playback Session

Step 4: Report Custom Metadata

Step 5: Report Playback Events

Step 6: Report Stream and Track Related Events

Step 7: Report Request Status and Fallback Events

Step 8: Report Ad Events

Step 9: Report Custom Events

Step 10: Destroy SDK

Release Notes

Step 1: Prerequisites and Setup

Step 1.1: Add Gradle Dependency:

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

Maven

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

Step 1.2: Provide Manifest Permissions

Add network permissions.

<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.DeviceInfo;
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: Instantiate and Register SDK

The player application must register the SDK and provide Player Information once the player is initialized. Please note that the values configured during this integration step persist across all subsequent video sessions for that SDK instance.

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

Step 2.1: Create SDK instance

For every Player Instance create a new SDK Instance.

MMIntegrationWrapper sdkInstance = MMSmartStreamingMedia3.getInstance(); 

Step 2.2: Set Context

Set the application context

sdkInstance.setContext(applicationContext)

Step 2.3: Register SDK

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at [e-mail].

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

Step 2.4: Report Player ID

sdkInstance.reportPlayerId("PLAYER_ID");

Step 2.5: Report Player Information

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

Step 2.6: Report Base Player Information

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

Step 2.7: Report Application Information

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

Step 2.8: Report Device Information

sdkInstance.reportDeviceInfo(deviceInfo);

Device Info Object Description

Parameter	Data Type
deviceMarketingName	String
brand	String
deviceModel	String
deviceId	String
os	String
osVersion	String
telecomOperator	String
screenWidth	String
screenHeight	String
deviceCapabilities	String

Step 2.9: Report Sub Property Id

sdkInstance.reportSubPropertyId("SUB_PROPERTY_ID");

Step 2.10: Report App Session Id

Report Application Session ID

sdkInstance.reportAppSessionId("APP_SESSION_ID");

Step 3: Initialize Playback Session

The SDK must be initialized at the start of each video session. Initialization includes reporting Content Metadata and indicating the intent for playback with the SDK.

Step 3.1: Initialize Session with Content Metadata

Initialize the 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.drmLevel = "DRM_LEVEL"
contentMetadata.contentType="CONTENT_TYPE";
    
sdkInstance.initializeSession(contentMetadata);

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 3.2: Report Experiment Name

Report the experiment name as a String.

sdkInstance.reportExperimentName("Experiment Name");

Step 3.3: Report View Session Id

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

sdkInstance.reportViewSessionId("VIEW_SESSION_ID");

Step 3.4: 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.

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

Step 3.5: Report Player Resolution

sdkInstance.reportPlayerResolution(playerWidth, playerHeight);

Step 3.6 Report User Initiated Playback

This function indicates the intent for playback and must be reported after initializeSession .

sdkInstance.reportUserInitiatedPlayback();

Step 4: 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.

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

Step 5: Report Playback Events

Step 5.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

MMPlayerState
PLAYING
PAUSED
STOPPED

Step 5.2: Report Buffering Events

//buffering start
sdkInstance.reportBufferingStarted();

//buffering complete
sdkInstance.reportBufferingCompleted();

Step 5.3 Report Seek Events

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

Step 5.4: Report Errors

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

Step 5.5: Report Warnings

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

Step 5.6: Report Playback Position

Report Playback position in ms.

sdkInstance.reportPlaybackPosition(playbackpos);

Step 6: Report Stream and Track Related Information

Step 6.1: Report Stream URL

Report stream url that is currently being used.

sdkInstance.setStreamURL("STREAM_URL");

Step 6.2: Report Stream Information

Report Information related to stream

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

Step 6.3: Report Video Duration

sdkInstance.reportVideoDuration(inMilliSeconds);

Step 6.4 Report Network Info

sdkInstance.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 6.5: Report CDN

MMSmartStreamingMedia3.reportCDN("CDN");

Step 6.6: Report Track Related Information

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

Step 6.7: 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.8: Update DRM Type

This API has been deprecated. Please refer Step 7.3 for updated API.

sdkInstance.updateDRMType("DRM_TYPE");

Step 6.9: Report Player Download Rate

Report Player download rate in bps

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

Step 6.10: Report Frame Loss

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

Step 6.11: Report Encoding Service

sdkInstance.reportEncodingService("ENCODING_SERVICE");

Step 7: Report Request Status and Fallback Events

Step 7.1: Report Request Status

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

Request Status (Enum)

Request Status	Description
FAILED	Report on a failed request
CANCELLED	Report on a cancelled request

Step 7.2: Report Stream Fallback event

Report fallback events in case a fallback strategy is applied.

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

Step 7.3: Update DRM

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

Step 7.4: Update Content Metadata

sdkInstance.updateContentMetadata(cm);

Step 7.5: Update Subscriber Information

sdkInstance.updateSubscriberInfo("SUBSCRIBER_ID", "SUBSCRIBER_TYPE", "SUBSCRIBER_TAG");

Step 8: Report Ad Events

Step 8.1: Report Ad Start and End

reportAdBreakStarted and reportAdBreakEnded APIs now can be reported with an optional Map<String, Object> as param.

sdkInstance.reportAdBreakStarted(map);
sdkInstance.reportAdBreakEnded();
sdkInstance.reportAdStarted(adInfoObject);
sdkInstance.reportAdEnd();

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.

Step 8.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.

sdkInstance.reportAdBufferingStarted();
sdkInstance.reportAdBufferingCompleted();

Step 8.3: Report Ad Events:

Use the reportAdEvent function to report all Ad events.

reportAdStarted and reportAdEnd are kept as it is for backward compatibility, but going forward, all the new Integrations should use the reportAdEvent API for all ad states.

sdkInstance.reportAdEvent(MMAdEvent, adInfoObject);

MMAdEvent (Enum)

Ad Event	Description
AD_START	Report on ad start.
AD_FIRST_QUARTILE	Report on ad reached first quartile.
AD_MID_POINT	Report on ad reached midpoint.
AD_THIRD_QUARTILE	Report on ad reached third quartile.
AD_SKIP	Report on ad skipped.
AD_END	Report on ad ended.
AD_COMPLETE	Report on ad ended and ad play time greater than 95%.
AD_CLICK	Report on ad clicked.

Step 8.4: Report Ad Request and Response

Report Ad Request and Ad Response using the following API:

Both of these APIs requires Map<String, Object> as parameter to report ad data.

sdkInstance.reportAdRequest(requestMap); 
sdkInstance.reportAdResponse(responseMap);

Step 8.5: Report Ad Errors and Warnings

Report Ad Error :

sdkInstance.reportAdError(AD_ERROR_CODE_INT, "AD_ERROR_MESSAGE", "AD_ERROR_DESCRIPTION");

Report Ad Warnings :

sdkInstance.reportAdWarning(AD_WARNING_CODE_INT, "AD_WARNING_MESSAGE", "AD_WARNING_DESCRIPTION");

Step 9: 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.

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

Step 10: Destroy SDK

Release the SDK resource by destroying the SDK Instance using the following method:

Use this only when the player object is destroyed.

sdkInstance.destroy()

Release Notes

Current Release

v2.2.5 ^{_{Jul 28, 2026}}

• Crash fix added for NPE in case of unstable network on sim carrier

---

Previous Releases

v2.2.4 ^{_{Jul 20, 2026}}

• Added destroy() method to release the sdk resources.

v2.2.3 ^{_{Jul 13, 2026}}

• Added queue size limit for event queue and dead letter queue.

• Added additional exception handling for corner cases.

v2.2.2 ^{_{Jul 7, 2026}}

• Internal optimisation for event queueing.

v2.2.1 ^{_{Jul 1, 2026}}

• Added retry handling for socket timeout exceptions.

v2.2.0 ^{_{Jun 29, 2026}}

• Enhanced Internal SDK data reporting

  • Added batch-based data reporting with configurable reporting intervals.

  • Improved reliability with exponential backoff retries, jitter, request timeouts, and Dead Letter Queue (DLQ) support.

  • Enabled remote configuration for batch size, reporting interval, retry settings, and the batching feature flag.

• Added new APIs for reporting ad events, including quartiles, request/response, errors, warnings, skip, and click events.

• Added support for reporting device capabilities through DeviceInfo.

v2.1.4 ^{_{Jun 19, 2026}}

• Updated proguard rules as fix for build pipeline failure.

v2.1.3 ^{_{Apr 30, 2026}}

• Added missing methods in the wrapper updateSubscriberInfo and updateContentMetadata .

v2.1.2 ^{_{Apr 14, 2026}}

• Initial release with Multi-Player support.

• New Field playerID addition and API to report it via reportPlayerId .

• New Field drmLevel addition in contentMetadata.

• Deprecated updateDrmType API. Added new API called updateDRM to update DRM Protection and DRM Level.

• New Field adUniversalId addition in AdInfo Object.

• Added deviceMarketingName and deviceId in the DeviceInfo object.

• Buffering events exceeding the stats interval are now included in the stats payload.