# 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](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## 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. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0:

```xml
<ComponentLibrary id="THEOComscoreConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/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.

```brightscript
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

```xml
<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.

```brightscript
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:

```brightscript
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](https://www.theoplayer.com/docs/theoplayer/connectors/roku/comscore/API-reference/) 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.

```brightscript
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:

```brightscript
m.comscoreConnector.callFunc("destroy")
m.comscoreConnector = invalid

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