SDK Integration

Loading the Library

The TrueX ad renderer and its rendering logic are distributed as a Roku component library. Add a reference to it, for example in your app's main scene:

<ComponentLibrary id="TruexAdRendererLib" uri="https://ctv.truex.com/roku/v1/release/TruexAdRenderer-Roku-v1.pkg" />

The library loads asynchronously. Observe its loadStatus field and create the renderer only when it is ready:

sub init()
    m.tarLibrary = m.top.findNode("TruexAdRendererLib")
    m.tarLibrary.observeFieldScoped("loadStatus", "onTruexLibraryLoadStatusChanged")
end sub

sub onTruexLibraryLoadStatusChanged(event as Object)
    if m.tarLibrary.loadStatus = "ready" then
        ' It is safe to create TruexLibrary:TruexAdRenderer now
    else if m.tarLibrary.loadStatus = "failed" then
        ' Play your regular ads - there will be no TrueX or IDVx ads in this session
    end if
end sub

Library version

We recommend the URL above, because it distributes performance and functionality updates without a new app release. A major/minor/build-specific library URL is available on request if you need to link to a specific build.

Renderer Container

The renderer adds its UI as a child of the TruexAdRenderer node, so create the renderer in a full-screen node above your video player. Hide as much other UI as possible while the ad is showing, including player controls, status bars, and keyboards.

Quick Example

sub startTruexAd(adParameters as Object, slotType as String)
    m.tar = m.top.createChild("TruexLibrary:TruexAdRenderer")
    m.tar.observeFieldScoped("event", "onTruexEvent")
    m.tar.setFocus(true)

    m.truexAdFreePod = false

    m.tar.action = {
        type: "init",
        adParameters: adParameters,
        slotType: UCase(slotType),
        supportsUserCancelStream: true
    }
    m.tar.action = { type: "start" }
end sub

sub onTruexEvent(msg as Object)
    event = msg.getData()

    if event.type = "adFreePod" then
        m.truexAdFreePod = true
    else if event.type = "adCompleted" or event.type = "noAdsAvailable" then
        disposeTruexRenderer()
        continuePlayback(m.truexAdFreePod)
    else if event.type = "adError" then
        disposeTruexRenderer()
        continuePlayback(false)
    else if event.type = "userCancelStream" then
        disposeTruexRenderer()
        exitPlayback()
    end if
end sub

sub disposeTruexRenderer()
    m.tar.visible = false
    m.tar.setFocus(false)
    m.tar.unobserveFieldScoped("event")
    m.tar.getParent().removeChild(m.tar)
    m.tar = invalid
end sub

continuePlayback and exitPlayback are your app's code - see Handling Terminal Events. The init and start actions are described below, and the events on the Events page.

TruexAdRenderer Actions

You control the renderer by assigning an associative array with a type to its action field. The renderer reports back through its event field, which is declared with alwaysNotify.

init

m.tar.action = {
    type: "init",
    adParameters: adParameters,
    slotType: "PREROLL",
    supportsUserCancelStream: true,
    logLevel: 1,
    channelWidth: 1920,
    channelHeight: 1080
}

Initializes the renderer. The renderer reads the adParameters, requests the ad from Infillion, and prepares the UI. init can only be sent once per renderer instance: create a new TruexAdRenderer for every ad.

You can initialize the renderer early - a few seconds before the pod starts - to give it more time to finish the ad request. It fires adFetchCompleted when the request is done. Use that event for a loading indicator, or for a timeout before you call start.

The parameters are:

Parameter	Required	Description
adParameters	Yes	The ad parameters associative array resolved from the VAST - see Resolving adParameters
slotType	Yes	The type of the current ad pod: PREROLL or MIDROLL
supportsUserCancelStream	No	Set to true to enable the userCancelStream event. Without it, the renderer fires adCompleted instead
logLevel	No	Verbosity of TrueX logging, from 0 (mute) to 5 (verbose). Defaults to 5
channelWidth	No	Width in pixels of your app's UI. Defaults to 1920
channelHeight	No	Height in pixels of your app's UI. Defaults to 1080

start

m.tar.action = { type: "start" }

Tells the renderer that your app is ready to show the ad. It can be sent any time after init. If the ad request is still running, the renderer waits for it to finish.

After start, the renderer adds its UI to the TruexAdRenderer node and fires adStarted. Then wait for a terminal event.

stop

m.tar.action = { type: "stop" }

Stops the renderer and dismisses the ad that is showing. Use it when your app has to end the ad - for example, when a timeout is reached or the app is closing. Remove the renderer node afterwards.

get_tar_info

m.tar.action = { type: "get_tar_info" }

Returns runtime metadata about the renderer. The result arrives on the event field as { type: "tarInfo", fullVersionString: "<version>" }.

fireDebugPixel

m.tar.action = { type: "fireDebugPixel", name: "my-debug-name", value: "optional value" }

Fires a TrueX t.gif debug pixel with the given name (required) and value (optional). Use it only when your Infillion contact asks you to.

Handling Events

Observe the event field of the renderer, and read the event with getData():

sub onTruexEvent(msg as Object)
    event = msg.getData()
    ? "TrueX event: "; event.type
end sub

See Events for every event type and its parameters.