Getting started with the Comscore Connector for the Roku SDK

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

Prerequisites

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

• Your Comscore publisher ID and publisher secret (available in your Comscore Direct dashboard under Mobile Apps > Get Tag).
• An app with the THEOPlayer SDK for Roku already integrated, see our Getting Started guide.

Integration

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

<ComponentLibrary id="THEOComscoreConnector" uri="https://cdn.myth.theoplayer.com/roku/1.5.0/THEOComscoreConnector.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()
    THEOComscoreNode = m.top.findNode("THEOComscoreConnector")
    THEOComscoreNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

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

    if THEOComscoreNode = invalid
        return
    end if

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

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

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

4. Then configure the connector by calling the configure method, passing the player instance and your Comscore customer key.

m.player = m.top.findNode("THEOplayer")
m.comscoreConnector = m.top.findNode("THEOComscoreConnector")
m.comscoreConnector.callFunc("configure", m.player, { publisherId: "MY_PUBLISHER_ID", publisherSecret: "MY_PUBLISHER_SECRET", applicationName: "MY_APPLICATION_NAME"})

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 = {
	adLoadFlag: false,
	assetId: "myAssetId",
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	clipLength: 600,
	completeEpisodeFlag: true,
	contentGenre: "Sports",
	digitalAirDate: "2025-03-04",
	episodeNumber: "59",
	episodeSeasonNumber: "5",
	episodeTitle: "The Game Last Night",
	programTitle: "The Sports Show",
	publisherBrandName: "Sports Publisher Network",
	stationTitle: "KXYZ",
	tvAirDate: "2025-03-04"
}
m.comscoreConnector.callFunc("startSession", contentMetadata)

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

6. Comscore requests a call to their tick method when the main event loop executes. If you update a global field called tccTick, the THEOComscoreConnector will automatically observe that field and call tick for you. Otherwise, you can manually call the sendTick method on the THEOComscoreConnector.

m.global.addField("tccTick", "integer", false)
m.global.tccTick = 0

while true
    m.global.tccTick = m.global.tccTick + 1
    msg = wait(1000, m.port)
    msgType = type(msg)
    if msgType = "roSGScreenEvent"
        if msg.isScreenClosed() then return
    end if
end while

NOTE: the wait method is running for 1000ms here, making the tccTick field get updated every second. Setting it to 0ms will cause the tccTick field to not get updated regularly.

7. If the content metadata needs to change, you can update it by calling update. This method accepts partial content metadata: m.comscoreConnector.callFunc( "update", contentMetadata)
8. When the video has stopped playing because it ended or the user exited, end the Comscore session m.comscoreConnector.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.comscoreConnector.callFunc("destroy")
m.comscoreConnector = invalid

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