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

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" />
  </interface>
  <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. Add MMTask Child Component:

Add the MediaMelon MMTask as a child component of the main video scene custom-playback-channel-master/components/MainScene.xml

<component name="MainScene" extends="Scene" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://devtools.web.roku.com/schema/RokuSceneGraph.xsd">
<!-- importing main handler -->
<script type="text/brightscript" uri="pkg:/components/MainScene.brs" />
<children>
    <MMTask id="MM"/>
</children>

3.2. 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 [email protected].

m.MM = m.top.FindNode("MM")
m.MM.setField("video", m.video)

3.3. Set Configuration Details:

MMConfig = {
  customerID: "CUSTOMER_ID"
  subscriberId: "SUBSCRIBER_ID"
  subscriberType: "SUBSCRIBER_TYPE"
  subscriberTag: "SUBSCRIBER_TAG"
  playerName: "PLAYER_NAME"
  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.4. Set Content Metadata:

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

3.5. Set Custom Configuration Details:

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

3.6. Set Codecs:

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

3.7. 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.8. Set Seek Threshold:

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

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

3.9. 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.10. 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.11. Run the SDK:

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

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"
}

Release Notes

Current Release

v2.8.0

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

Previous Releases

v2.7.2

Cleaned up the content change handler

v2.7.1

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

v2.7.0

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

v2.6.5

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

PreviousMediaMelon iOS AVPlayer IMA SDK Integration Document NextRoku Player IMA SDK

Last updated 1 month ago

hashtagStep 1: Include MediaMelon SmartStreaming SDK

hashtagStep 2: Set up a new MediaMelon Task

hashtagStep 3: MediaMelon Code Integration

hashtag3.1. Add MMTask Child Component:

hashtag3.2. Create MM Task Node:

hashtag3.3. Set Configuration Details:

hashtag3.4. Set Content Metadata:

hashtag3.5. Set Custom Configuration Details:

hashtag3.6. Set Codecs:

hashtag3.7. Set Custom Metadata:

hashtag3.8. Set Seek Threshold:

hashtag3.9. Set is Video Live:

hashtag3.10. Set View:

hashtag3.11. Run the SDK:

hashtagStep 4: Request Information

hashtagStep 5: Error Handling

hashtag5.1. Video Error Reporting:

hashtag5.2. Ad Error Reporting:

hashtagRelease Notes

hashtagv2.8.0

hashtagv2.7.2

hashtagv2.7.1

hashtagv2.7.0

hashtagv2.6.5

Step 1: Include MediaMelon SmartStreaming SDK

Step 2: Set up a new MediaMelon Task

Step 3: MediaMelon Code Integration

3.1. Add MMTask Child Component:

3.2. Create MM Task Node:

3.3. Set Configuration Details:

3.4. Set Content Metadata:

3.5. Set Custom Configuration Details:

3.6. Set Codecs:

3.7. Set Custom Metadata:

3.8. Set Seek Threshold:

3.9. Set is Video Live:

3.10. Set View:

3.11. Run the SDK:

Step 4: Request Information

Step 5: Error Handling

5.1. Video Error Reporting:

5.2. Ad Error Reporting:

Release Notes

v2.8.0

v2.7.2

v2.7.1

v2.7.0

v2.6.5