Roku with RAF SDK

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

Step 1: Include MediaMelon SmartStreaming SDK

Step 2: Setup a new MediaMelon Task

Step 3: MediaMelon Code Integrate

Step 4: Error Handling

Step 5: Ad Tracking with RAF

Step 6: Variables and Description

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 IMA SDK

Step 2: Setup 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="mmAdData" type="assocarray" alwaysNotify="true" />
    <field id="mmAdPlaying" type="Boolean" 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" />
  </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 Integrate

3.1. Add MMTask Child Component:

Add the MediaMelon MMTask as a child component to 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: "Roku"
  disableManifestFetch: false
  domainName: "DOMAIN_NAME"
  appName: "APP_NAME"
  appSdkVersion: "APP_VERSION"
  viewSessionId: "VIEW_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, then you can disable manifest fetch. This is an optional step.
hashSubscriberId: Set to true to hash the subscriberId and to false to process 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.

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

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 VOD stream

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

3.10. Set View:

It's important to set the view field start for every new view starts and to end when a 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: Error Handling

By default, 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.

4.1. Video Error Reporting:

m.MM.error = { 
    errorCode: "ERROR_CODE",
    errorMessage: "ERROR_MESSAGE",
    errorDetails: "ERROR_DETAILS"
}

4.2. Ad Error Reporting:

m.MM.adError = { 
    errorCode: "ERROR_CODE",
    errorMessage: "ERROR_MESSAGE",
    errorDetails: "ERROR_DETAILS"
}

Step 5: Ad Tracking with RAF

    RAF = Roku_Ads()
    RAF.setAdUrl(vastTag)

    logObj = {
        log: function(evtType = invalid as dynamic, ctx = invalid as dynamic)
            'The below function sends the Ad data to MediaMelon SDK for ad tracking
            sendAdDataToMMSDK(ctx)
    }
    logFunc = function(obj = invalid as dynamic, evtType = invalid as dynamic, ctx = invalid as dynamic)
        obj.log(evtType, ctx)
    end function
    RAF.setTrackingCallback(logFunc, logObj)
    
    adPods = RAF.getAds()

function sendAdDataToMMSDK(ctx as object)
    if m.global <> invalid and m.global.MMAnalytics <> invalid
        m.global.MMAnalytics.setField("mmAdData", ctx)
    end if
end function

Set the field named mmAdPlaying to true when an ad break started as shown below:

'preroll ads
if adPods <> invalid and adPods.count() > 0
        video.control = "stop"
        m.top.playingAd = true
        print "Preroll adPods > " adPods
        m.global.MMAnalytics.setField("mmAdPlaying", true) 'This line is part of MM SDK Integration
        keepPlaying = RAF.showAds(adPods, invalid, view)
 end if

'midroll ads
 if adPods <> invalid and adPods.count() > 0
        'ask the video to stop - the rest is handled in the state=stopped event below
        print "Midroll adPods > " adPods
        m.global.MMAnalytics.setField("mmAdPlaying", true) 'This line is part of MM SDK Integration
        video.control = "stop"
 end if

Step 6: Variables and Description

Variable

Description

Optional/Mandatory

PLAYER_NAME

String containing the Player Name.

Mandatory

CUSTOMER_ID

String containing your MediaMelon-assigned Customer ID.

Mandatory

SUBSCRIBER_ID

String containing your Subscriber’s ID.

Mandatory

DOMAIN_NAME

String containing your section of your subscriber or assets.

Mandatory

SUBSCRIBER_TYPE

String containing the Subscriber Type (e.g. “Free”, “Paid”).

Mandatory

SUBSCRIBER_TAG

String containing additional subscriber-specific information. This is sent in clear (not hashed) to SmartSight and it is advised not to send sensitive information in this field.

Optional

ASSET_ID

String containing Asset Id.

Mandatory

ASSET_NAME

String containing Asset Name.

Mandatory

VIDEO_ID

String containing your video’s ID.

Mandatory

CONTENT_TYPE

String containing the type of the Content. For example - "Movie", "Special", "Clip", "Scene" or "Episode".

Mandatory

GENRE

String containing the Genre of the content. For example - "Comedy", "Horror".

Mandatory

DRM_PROTECTION

Widevine, Fairplay, Playready, etc. Unknown means content is protected, but the protection type is unknown. For clear contents, do not set this field

Mandatory

EPISODE_NUMBER

String containing sequence number of the Episode.

Mandatory

SEASON

String containing the Season. For example - "Season 1".

Mandatory

SERIES_TITLE

String containing Title of the Series.

Mandatory

VIDEO_TYPE

String containing Video Type. For example - "LIVE", and "VOD".

Optional

PLAYER_BRAND

String containing Player Brand (e.g. “Exo Player”).

Mandatory

PLAYER_MODEL

String containing Player Model. For example - This could be a variant of a player. Say the name of third third-party player used by the organisation. Or any human-readable name of the player.

Mandatory

PLAYER_VERSION

String containing Player Version.

Mandatory

CUSTOM_KEY_1

Custom metadata key can be added here if required.

Optional

VALUE_1

Custom metadata value can be added here if required.

Optional

BASE_PLAYER_NAME

String containing base player name

Optional

BASE_PLAYER_VERSION

String containing base player version

Optional

EXPERIMENT_NAME

You can use this field to categorise views into different experiments, allowing you to filter by this dimension later.

Optional

SUB_PROPERTY_ID

A sub-property is an optional feature that allows you to organize data within a property. For instance, a video platform could use sub-properties to group data by customer, or a media company might use them to differentiate between its various websites.

Optional

VIEW_SESSION_ID

An ID that can be used to link the view with upstream platform services, such as CDN or origin logs, for correlation purposes.

Optional

hashSubscriberId

To hash the subscriber ID set this boolean variable to true, else set it to false.

Optional

player

Player Object.

Mandatory

streamURL

Current playing content stream URL.

Mandatory

isVideoLive

Set this boolean variable to true if the content is Live else set it to false for VOD content.

Optional

PreviousRoku SDK NextRoku with IMA SDK

Last updated 3 months ago

Was this helpful?