Getting started with the Conviva Connector for the Roku SDK

Here's how to get started integrating the Conviva Connector with the THEOplayer Roku SDK.

Prerequisites

In order to set up the Conviva Connector in your Roku application, you'll need the following:

• Your Conviva customer key (available in your Conviva Pulse dashboard)
• An app with the THEOPlayer SDK for Roku already integrated, see our Getting Started guide.
• Optionally for debug and testing, your Conviva Touchstone gateway URL, which should be in the format of "https://MY_TOUCHSTONE_DOMAIN.ts-testonly.conviva.com/"

Integration

1. First you must download the THEO Conviva Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of THEOConvivaConnector and providing the URI for the THEOConvivaConnector.pkg:

<ComponentLibrary id="THEOConvivaConnector" uri="https://cdn.myth.theoplayer.com/roku/1.5.0/THEOConvivaConnector.pkg" />

2. Then in the Brightscript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the loadStatus field.

sub Init()
    THEOConvivaNode = m.top.findNode("THEOConvivaConnector")
    THEOConvivaNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOConvivaNode = event.getROSGNode()

    if THEOConvivaNode = invalid
        return
    end if

    if THEOConvivaNode.loadStatus = "ready"
		' Success
    else if THEOConvivaNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOConvivaNode.uri
	end if
end sub

3. Add the THEOConvivaConnector component to the SceneGraph file where your THEOPlayer is defined

<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOConvivaConnector:THEOConvivaConnector id="THEOConvivaConnector" />

4. Then in the Brightscript file, configure the connector by calling the configure method, passing the player instance and your Conviva customer key.

m.player = m.top.findNode("THEOPlayer")
m.convivaConnector = m.top.findNode("THEOConvivaConnector")
m.convivaConnector.callFunc("configure", m.player, "MY_CUSTOMER_KEY")

NOTE: that if you want to debug first and use Conviva's Touchstone service to validate your integration, you can include the gateway URL and a debug parameter in the configure call: m.convivaConnector.callFunc("configure", m.player, "MY_CUSTOMER_KEY", "MY_TOUCHSTONE_GATEWAY_URL", true)

5. Next, when you start playing the asset, call the startSession method and pass it the content metadata for the asset you're playing:

m.player.source = sourceDescription
contentMetadata = {
    defaultReportingResource: "MyCDN",
    playerName: "My Player",
    assetName: "My Asset Name",
    encodedFramerate: 24
}
m.convivaConnector.callFunc("startSession", contentMetadata)

See the API documentation for more on how to structure the content metadata for Conviva.

6. If you desire to monitor for CDN changes, you can optionally add a configuration for that after starting the session. m.convivaConnector.callFunc("monitorCdnChanges", { mycdn: ["my-cdn.net"], theo: ["cdn.theoplayer.com"] })
7. If the content metadata needs to change, you can update it by calling setContentInfo. This method accepts partial content metadata: m.convivaConnector.callFunc( "setContentInfo", {assetName: "New Program"})
8. When the video has stopped playing because it ended or the user exited, end the Conviva session m.convivaConnector.callFunc("endSession")
9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

m.convivaConnector.callFunc("destroy")
m.convivaConnector = invalid

m.player.callFunc("destroy")
m.player = invalid