# MediaMelon Android Multiplayer Custom SDK Integration Document

**Step 1:** [Prerequisites and Setup](#step-1-prerequisites-and-setup)

**Step 2:** [Instantiate and Register SDK](#step-3-initialize-session-and-report-user-intent-to-playback)

**Step 3:** [Initialize Playback Session](#step-3-initialize-playback-session)

**Step 4:** [Report Custom Metadata](#step-4-report-custom-metadata)

**Step 5:** [Report Playback Events](#step-3-initialize-session-and-report-user-intent-to-playback-3)

**Step 6:** [Report Stream and Track Related Events](#step-3-initialize-session-and-report-user-intent-to-playback-4)

**Step 7:** [Report Request Status and Fallback Events](#step-3-initialize-session-and-report-user-intent-to-playback-8)

**Step 8:** [Report Ad Events](#step-8-report-a-d-events)

**Step 9:** [Report Custom Events](#step-9-report-custom-events)

[Release Notes](#release-notes)

### Step 1: Prerequisites and Setup

#### **Step 1.1: Add Gradle Dependency:**

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

{% tabs %}
{% tab title="Maven" %}

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

{% endtab %}
{% endtabs %}

#### Step 1.2: Provide Manifest Permissions

Add network permissions.

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

```java
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 <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

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.

{% hint style="info" %}
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);`
{% endhint %}

{% hint style="info" %}
CUSTOMER\_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at <customer-support@mediamelon.com>.
{% endhint %}

#### Step 2.1: Create SDK instance&#x20;

For every Player Instance create a new SDK Instance.

```java
MMIntegrationWrapper sdkInstance = MMSmartStreamingMedia3.getInstance(); 
```

#### Step 2.2:  Set Context

Set the application context

```java
sdkInstance.setContext(applicationContext)
```

#### Step 2.3: Register SDK

{% hint style="info" %}
CUSTOMER\_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID contact MediaMelon at <customer-support@mediamelon.com>.
{% endhint %}

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

#### Step 2.4: Report Player ID

```java
sdkInstance.reportPlayerId("PLAYER_ID");
```

#### Step 2.5: Report Player Information

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

#### Step 2.6: Report Base Player Information

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

#### Step 2.7: Report Application Information

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

#### Step 2.8: Report Device Information

```java
sdkInstance.reportDeviceInfo(deviceInfo);
```

<details>

<summary>Device Info Object Description</summary>

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

</details>

#### Step 2.9: Report Sub Property Id <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

```java
sdkInstance.reportSubPropertyId("SUB_PROPERTY_ID");
```

#### Step 2.10: Report App Session Id

Report Application Session ID

```java
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.

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

<details>

<summary>Content Metadata Object Description</summary>

<table><thead><tr><th width="148.34765625">Parameter</th><th width="117.17578125">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>assetId</td><td>String</td><td>Unique identifier for the video asset.</td></tr><tr><td>assetName</td><td>String</td><td>Human-readable name or title of the video asset.</td></tr><tr><td>videoId</td><td>String</td><td>Unique identifier for the video content. It can be the same as <strong>Asset ID</strong> or a different logical ID used in your system.</td></tr><tr><td>seriesTitle</td><td>String</td><td>Title of the series to which the episode belongs.</td></tr><tr><td>season</td><td>String</td><td>Name or number of the season (e.g., "Season 1", "S2").</td></tr><tr><td>genre</td><td>String</td><td>Genre of the content, such as "Drama", "Comedy", "Documentary", etc.</td></tr><tr><td>episodeNumber</td><td>String</td><td>Episode number within a season. Useful for TV series or episodic content.</td></tr><tr><td>contentType</td><td>String</td><td>The category or type of content, e.g., "Movie", "Episode", "Clip", "LiveStream".</td></tr><tr><td>drmProtection</td><td>String</td><td>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.</td></tr></tbody></table>

</details>

#### Step 3.2: Report Experiment Name

Report the experiment name as a String.

```java
sdkInstance.reportExperimentName("Experiment Name");
```

#### Step 3.3: Report View Session Id <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

{% hint style="info" %}
Report the View Session Id attribute after `initializeSession` and before `reportUserInitiatedPlayback`.&#x20;
{% endhint %}

```java
sdkInstance.reportViewSessionId("VIEW_SESSION_ID");
```

#### Step 3.4: Report Preload

{% hint style="info" %}
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.
{% endhint %}

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

#### Step 3.5: Report Player Resolution

```java
sdkInstance.reportPlayerResolution(playerWidth, playerHeight);
```

#### Step 3.6 Report User Initiated Playback

{% hint style="info" %}
This function indicates the intent for playback and must be reported after `initializeSession` .
{% endhint %}

```java
sdkInstance.reportUserInitiatedPlayback();
```

### Step 4: Report Custom Metadata

Check the custom tags configuration in your [dashboard](https://smartsight3.mediamelon.com/settings) and report accordingly. If the custom tags are not configured, please configure and use them accordingly.

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

### Step 5: Report Playback Events <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

#### Step 5.1: Report Player State

{% hint style="info" %}
Make sure to report ***MMPlayerState.STOPPED*** at the end of playback completion to mark session as ended.
{% endhint %}

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

<details>

<summary>MMPlayerState</summary>

| MMPlayerState |
| ------------- |
| PLAYING       |
| PAUSED        |
| STOPPED       |

</details>

#### Step 5.2: Report Buffering Events

```java
//buffering start
sdkInstance.reportBufferingStarted();

//buffering complete
sdkInstance.reportBufferingCompleted();
```

#### Step 5.3 Report Seek Events

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

#### Step 5.4: Report Errors

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

#### Step 5.5: Report Warnings

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

#### Step 5.6: Report Playback Position

Report Playback position in ms.

```java
sdkInstance.reportPlaybackPosition(playbackpos);
```

### Step 6: Report Stream and Track Related Information <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

#### &#x20;Step 6.1: Report Stream URL <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

Report stream url that is currently being used.

```java
sdkInstance.setStreamURL("STREAM_URL");
```

#### Step 6.2: Report Stream  Information

Report Information related to stream

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

#### Step 6.3: Report Video Duration <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

```java
sdkInstance.reportVideoDuration(inMilliSeconds);
```

#### Step 6.4 Report Network Info

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

{% hint style="info" %}
Use the **`reportNetworkInfo`** API to report the CDN along with other network information.\
If additional network information is not available, use **`reportCDN`** instead.
{% endhint %}

#### Step 6.5: Report CDN

```java
MMSmartStreamingMedia3.reportCDN("CDN");
```

#### Step 6.6:  Report Track Related Information <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

```java
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.

```java
sdkInstance.reportRendition(renditionObject);
```

<details>

<summary>Rendition Object</summary>

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

</details>

#### Step 6.8: Update DRM Type

{% hint style="warning" %}
This API has been deprecated. Please refer [Step 7.3](#step-7.3-update-drm) for updated API.
{% endhint %}

```java
sdkInstance.updateDRMType("DRM_TYPE");
```

#### Step 6.9: Report Player Download Rate

Report Player download rate in bps

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

#### Step 6.10: Report Frame Loss

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

#### Step 6.11: Report Encoding Service

```java
sdkInstance.reportEncodingService("ENCODING_SERVICE");
```

### Step 7:  Report Request Status and Fallback Events <a href="#step-3-initialize-session-and-report-user-intent-to-playback" id="step-3-initialize-session-and-report-user-intent-to-playback"></a>

#### Step 7.1: Report Request Status

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

<details>

<summary>Request Status (Enum)</summary>

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

</details>

#### Step 7.2: Report Stream Fallback event

Report fallback events in case a fallback strategy is applied.&#x20;

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

#### Step 7.3: Update DRM

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

#### Step 7.4: Update Content Metadata

```java
sdkInstance.updateContentMetadata(cm);
```

#### Step 7.5: Update Subscriber Information

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

### Step 8: Report Ad Events

#### Step 8.1: Report Ad Start and End

```java
sdkInstance.reportAdBreakStarted();
sdkInstance.reportAdBreakEnded();
sdkInstance.reportAdStarted(adInfoObject);
sdkInstance.reportAdEnd();
```

<details>

<summary>AdInfo Object</summary>

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

</details>

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

```java
sdkInstance.reportAdBufferingStarted();
sdkInstance.reportAdBufferingCompleted();
```

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

```javascript
sdkInstance.reportCustomEvent("EVENT_NAME", "EVENT_VALUE");
```

{% hint style="info" %}
**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.
{% endhint %}

#### Release Notes

<details>

<summary>Current Release</summary>

#### v2.1.3[^1]  <sup><sub>`Apr 30, 2026`<sub></sup>

* Added missing methods in the wrapper `updateSubscriberInfo` and `updateContentMetadata` .

</details>

***

<details>

<summary>Previous Releases</summary>

#### v2.1.2[^1]  <sup><sub>`Apr 14, 2026`<sub></sup>

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

</details>

[^1]: **Performance Report:** [here](https://docs.mediamelon.com/mediamelon/sdk-performance-metrics/android/android-multiplayer-custom-sdk-performance-metrics)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/android/mediamelon-android-multiplayer-custom-sdk-integration-document.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.