MediaMelon Roku SDK Integration Document

This document describes the Roku MediaMelon Player SDK Integration with the Roku media player.

Step 1: Include MediaMelon SmartStreaming SDK

Step 2: Set up a new MediaMelon Task

Step 3: MediaMelon Code Integration

Step 4: Request Information

Step 5: Error Handling

Step 6: Ad Data & Ad Events

Step 7: Custom Events

Release Notes

Step 1: Include MediaMelon SmartStreaming SDK

To integrate, unzip the MediaMelon Roku library and place the MMSmartStream folder in the components directory.

SDK: MediaMelon Roku SDK

Step 2: Set up a new MediaMelon Task

Create a new XML file MMTask.xml inside your components folder. This is used to link MediaMelon’s brsfiles into your application.

The MMTask.xmlfile should contain the following:

<component name="MMTask" extends="Task">
  <interface>
    <field id="video" type="node" alwaysNotify="true" />
    <field id="config" type="assocarray" alwaysNotify="true" />
    <field id="customConfig" type="assocarray" alwaysNotify="true" />    
    <field id="contentMetadata" type="assocarray" alwaysNotify="true" />
    <field id="customTags" type="assocarray" alwaysNotify="true" />
    <field id="error" type="assocarray" alwaysNotify="true"/>
    <field id="adError" type="assocarray" alwaysNotify="true"/>
    <field id="view" type="String" alwaysNotify="true" />
    <field id="exit" type="Boolean" alwaysNotify="true" />
    <field id="mmRafEvent" type="assocarray" alwaysNotify="true"/>
    <field id="sdk_version" type="String" alwaysNotify="true" />
    <field id="seekThreshold" type="Integer" alwaysNotify="true"/>
    <field id="codecs" type="assocarray" alwaysNotify="true" />
    <field id="isVideoLive" type="Boolean" alwaysNotify="true" />
    <field id="requestInfo" type="assocarray" alwaysNotify="true" />
    <field id="customEvent" type="assocarray" alwaysNotify="true" />
    <field id="deviceInfo" type="assocarray" alwaysNotify="true" />
  </interface>
  <script type="text/brightscript" uri="pkg:/components/MMSmartStream/MMNetworkHandler.brs" />
  <script type="text/brightscript" uri="pkg:/components/MMSmartStream/MMSmartStreamWrapper.brs" />
  <script type="text/brightscript" uri="pkg:/components/MMSmartStream/MMSmartStreamEngine.brs" />
  <script type="text/brightscript" uri="pkg:/components//MMSmartStream/MMSmartStreamRokuPlugin.brs" />
  <script type="text/brightscript" uri="pkg:/components/MMSmartStream/Utilities.brs" />
</component>

Step 3: MediaMelon Code Integration

3.1. Create MM Task Node:

In the main application, after the video instance has been created, create a MediaMelon Task node, and pass the Video node to it.

CUSTOMER_ID is your MediaMelon assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at customer-support@mediamelon.com.

m.MM = createObject("roSGNode", "MMTask")
m.MM.setField("video", m.video)

3.2. Set Configuration Details:

MMConfig = {
  customerID: "CUSTOMER_ID"
  subscriberId: "SUBSCRIBER_ID"
  subscriberType: "SUBSCRIBER_TYPE"
  subscriberTag: "SUBSCRIBER_TAG"
  playerName: "PLAYER_NAME"
  playerId: "PLAYER_ID"
  playerVersion: "PLAYER_VERSION"
  basePlayerName: "BASE_PLAYER_NAME"
  basePlayerVersion: "BASE_PLAYER_VERSION"
  disableManifestFetch: true
  domainName: "DOMAIN_NAME"
  appName: "APP_NAME"
  appSdkVersion: "APP_VERSION"
  viewSessionId: "VIEW_SESSION_ID"
  appSessionId: "APP_SESSION_ID"
  hashSubscriberId: false 'Important
  enableCustomErrorReporting: true 'Important
}
m.MM.setField("config", MMConfig)

disableManifestFetch: If your workflow restricts the manifest to be accessible from both the player and SDK simultaneously, you can disable manifest fetch. This is an optional step.
hashSubscriberId: Set true to hash the subscriberId and to false to process the subscriberId without hashing.
enableCustomErrorReporting: If set to true SDK will consider only client-reported errors, else if set to false SDK will consider errors from the video node. (Refer Here)

3.3. Set Content Metadata:

contentMetadata = {
  "assetName": "ASSET_NAME",
  "assetId": "ASSET_ID",
  "videoId": "VIDEO_ID",
  "genre": "GENRE",
  "drmProtection": "DRM_PROTECTION",
  "drmLevel": "DRM_LEVEL",
  "episodeNumber": "EPISODE_NUMBER",
  "season": "SEASON",
  "seriesTitle": "SERIES_TITLE",
  "contentType": "CONTENT_TYPE"
}
m.MM.setField("contentMetadata", contentMetadata)

3.4. Set Custom Configuration Details:

customConfig = {
  cdn: "CDN"
  experimentName: "EXPERIMENT_NAME"
  subPropertyId: "SUB_PROPERTY_ID"
  streamFormat: "STREAM_FORMAT"
  mediaType: "MEDIA_TYPE"
  drmProtection: "DRM_PROTECTION"
  drmLevel: "DRM_LEVEL"
  preload: <boolean>
  encodingService: "ENCODING_SERVICE"
}
m.MM.setField("customConfig", customConfig)

3.5. Set Codecs:

codecs = {
  video: "VIDEO_CODEC"
  audio: "AUDIO_CODEC"
}
m.MM.setField("codecs", codecs)

3.6. Set Custom Metadata:

customMetadata = {
  "CUSTOM_KEY_1": "VALUE_1",
  "CUSTOM_KEY_2": "VALUE_2"
}
m.MM.setField("customTags", customMetadata)

For Custom Metadata, first, provide the mapping in the SmartSight dashboard under the settings section, and send the values to the SDK accordingly.

3.7. Set Seek Threshold:

By default seek threshold is set to 1.25 seconds in the SDK.

m.MM.setField("seekThreshold", 2)

3.8. Set is Video Live:

Set isVideoLive to true for live video stream and to false for the VOD stream

m.MM.setField("isVideoLive", true)

3.9. Set View:

It's important to set the view field start for every new view start, and to end when the view ends.

Start View:

m.MM.setField("exit", false)
m.MM.setField("view", "start")

End View:

m.MM.setField("view", "end")
m.MM.setField("exit", true)

3.10. Run the SDK:

m.MM.control = "RUN"
m.player.setFocus(true)

3.11. Device Info:

deviceInfo = {
  deviceCapabilities: "DEVICE_CAPABILITIES"
}
m.MM.setField("deviceInfo", deviceInfo)

Step 4: Request Information

Report failed or cancelled requests for the following request types:

PIR
MANIFEST
AUDIO_CHUNK
VIDEO_CHUNK
DRM
SUBTITLE

requestInfo = { 
    requestStatus: <request_status>,    'string (This should be "failed" or "cancelled")
    requestType: <request_type>,        'string (This can be pir, manifest, audio_chunk, video_chunk, drm, subtitle)
    id: "ID",
    error: "ERROR",
    text: "TEXT",
    hostname: "HOSTNAME",
    url: "URL"
}

m.MM.setField("requestInfo", requestInfo)

Step 5: Error Handling

By default, the SDK listens to the video node for errors. To report custom errors, set enableCustomErrorReporting flag to true in MMConfig and report the errors in the following way;

Upon setting enableCustomErrorReporting flag to true, SDK will stop listening to the video node errors. Only custom errors will be reported.

5.1. Video Error Reporting:

m.MM.error = { 
    errorCode: "ERROR_CODE",
    errorMessage: "ERROR_MESSAGE",
    errorDetails: "ERROR_DETAILS",
    errorSeverity: <error_severity>   'string (This should be "warning" or "fatal")
}

error_severity: Set this to "warning" for warnings and set to "fatal" for fatal errors.

5.2. Ad Error Reporting:

m.MM.adError = { 
    errorCode: "ERROR_CODE",
    errorMessage: "ERROR_MESSAGE",
    errorDetails: "ERROR_DETAILS",
    errorSeverity: <error_severity>   'string (This should be "warning" or "fatal")
}

Step 6: Ad Data & Ad Events:

m.mmTask.setField("mmRafEvent", rafEventData)

Sample: rafEventData = { obj: rafData, eventType: "Start", ctx: ctx }

Ad Event Type and Mapping

Event Type

MediaMelon Dashboard Event

adRequest

AD_REQUEST

adResponse

AD_RESPONSE

PodStart

AD_BREAK_STARTED

PodComplete

AD_BREAK_ENDED

Start

AD_IMPRESSION & AD_PLAY

Pause

AD_PAUSED

Resume

AD_RESUMED

Complete

AD_COMPLETE

Close

AD_ENDED

FirstQuartile

AD_PLAYED_FIRST_QUARTILE

Midpoint

AD_PLAYED_MID_QUARTILE

ThirdQuartile

AD_PLAYED_THIRD_QUARTILE

Skip

AD_SKIPPED

Click

AD_CLICK

Ad Information (ctx)

adTitle

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

adId

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

adCreativeId

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

adClient

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

adPosition

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

adSystem

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

adUrl

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

adPodIndex

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

adPodPosition

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

adPodLendth

The total number of ads in the current pod. Useful for showing “Ad 2 of 5” type of UI.

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

m.MM.customEvent = {
    eventName: "EVENT_NAME",
    eventValue: "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 30 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

v2.11.0 `^{_{Jun 29, 2026}}`

Enhanced internal SDK data reporting
- Separated all data reporting logic into a dedicated MMNetworkHandler module.
- 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 support for reporting new ad events, including quartiles, request/response, errors, warnings, skip, and click events.
Added internal intermediate buffering duration reporting for long buffering sessions to improve real-time buffering monitoring.
Replaced hardcoded logs with the SDK logging function.
Added support for reporting device capabilities through deviceInfo interface.

Previous Releases

v2.10.0 `^{_{May 06, 2026}}`

Added new metadata fields player ID and DRM Level.
Fixed play duration offset calculation issue.

v2.9.0 `^{_{Mar 30, 2026}}`

Added support for reporting a new field encoding service via customConfig.
Introduced custom event reporting through customEvent interface.
Added FPS reporting in the Rendition event.
Fixed the NA Asset Name issue.

v2.8.0 `^{_{Feb 06, 2026}}`

Added CDN_CHANGE event functionality.
Added Seek Duration calculation internally.
Added Audio and Video Codecs in Rendition Event.

v2.7.2 `^{_{Jan 23, 2026}}`

Cleaned up the content change handler

v2.7.1 `^{_{Jan 06, 2026}}`

Fixed a bug in HTTP port handling in the case of upnext.

v2.7.0 `^{_{Dec 22, 2025}}`

Updated network call handling to avoid waiting after the HTTP call.
Updated Device Resolution string.

v2.6.5 `^{_{Dec 12, 2025}}`

Device & Network Information fixes
Fixed Player Resolution
Preload field addition
App Session Id field addition
Fix to consider Exit in Buffering

PreviousRoku SDK

NextMediaMelon Roku SDK Integration with IMA

Last updated 1 hour ago

Step 1: Include MediaMelon SmartStreaming SDK

Step 2: Set up a new MediaMelon Task

Step 3: MediaMelon Code Integration

3.1. Create MM Task Node:

3.2. Set Configuration Details:

3.3. Set Content Metadata:

3.4. Set Custom Configuration Details:

3.5. Set Codecs:

3.6. Set Custom Metadata:

3.7. Set Seek Threshold:

3.8. Set is Video Live:

3.9. Set View:

3.10. Run the SDK:

3.11. Device Info:

Step 4: Request Information

Step 5: Error Handling

5.1. Video Error Reporting:

5.2. Ad Error Reporting:

Step 6: Ad Data & Ad Events:

Step 7: Custom Events:

Release Notes

v2.11.0 Jun 29, 2026

v2.10.0 May 06, 2026

v2.9.0 Mar 30, 2026

v2.8.0 Feb 06, 2026

v2.7.2 Jan 23, 2026

v2.7.1 Jan 06, 2026

v2.7.0 Dec 22, 2025

v2.6.5 Dec 12, 2025

v2.11.0 `^{_{Jun 29, 2026}}`

v2.10.0 `^{_{May 06, 2026}}`

v2.9.0 `^{_{Mar 30, 2026}}`

v2.8.0 `^{_{Feb 06, 2026}}`

v2.7.2 `^{_{Jan 23, 2026}}`

v2.7.1 `^{_{Jan 06, 2026}}`

v2.7.0 `^{_{Dec 22, 2025}}`

v2.6.5 `^{_{Dec 12, 2025}}`