Integration Flow

A Roku integration is split between Infillion and the publisher. Infillion provides the VAST tag and renders the interactive ad. The publisher's app finds the Infillion ad in its ad break, hands it to TruexAdRenderer, and moves the playback timeline forward when the renderer is done.

1. Infillion provides a test VAST tag

   Your Infillion contact provides a test VAST tag that fits your ad setup. The generic tag is the preferred option. The companion tag is used when it works better with your ad stack. Both formats are described in VAST Tag Types.

2. The publisher traffics the tag

   Your ad ops team schedules the tag in your ad server. A TrueX tag must be the first ad in the pod. An IDVx tag can be placed in any slot.

3. The publisher integrates the SDK

   Your app resolves adParameters from the ad, starts the renderer when the ad plays, and handles the terminal events.

Resolving adParameters

The renderer is initialized with an adParameters associative array. Where that JSON comes from depends on the VAST tag format:

Tag format	Where adParameters is in the VAST	RAF	Custom VAST parsing
Generic	<Linear><AdParameters> as a JSON string	ad.adParameters	Text content of <AdParameters>
Companion	<Companion apiFramework="truex"><StaticResource creativeType="application/json"> as a base64 JSON data: URL	ad.companionAds, the entry whose provider is truex	Text content of <StaticResource>, base64-decoded after the comma

First, identify the ad by its <AdSystem> value, compared case-insensitively. trueX is a TrueX ad and IDVx is an IDVx ad; any other value is a regular linear ad. A TrueX ad that is not the first ad in the pod should play as a regular linear ad.

To support both formats, resolve the payload in this order:

1. Use the <AdParameters> JSON if the ad has it.
2. Otherwise, look for a companion with apiFramework="truex" and decode its JSON.
3. If neither one gives a JSON object, do not start the renderer. Treat the ad as a normal linear ad and continue the pod.

The decoding, adapted from the CSAI example:

function resolveAdParameters(ad as Object) as Object
    json = invalid

    if ad.adParameters <> invalid and ad.adParameters <> "" then
        json = ad.adParameters
    else if ad.companionAds <> invalid then
        for each companion in ad.companionAds
            if LCase(companion.provider) = "truex" and companion.url <> invalid then
                ' The ad server wraps the base64 payload across lines, so line breaks are removed before decoding.
                base64 = companion.url.Split("data:application/json;base64,")[1]
                if base64 <> invalid then
                    buffer = CreateObject("roByteArray")
                    buffer.FromBase64String(base64.Replace(Chr(10), ""))
                    json = buffer.ToAsciiString()
                end if
                exit for
            end if
        end for
    end if

    if json = invalid then
        return invalid
    end if

    return ParseJson(json)
end function

The result of ParseJson is passed to the renderer as is. Do not read or change its fields.

Starting the Renderer

When the Infillion ad starts playing:

1. Pause the content player and the ad playback.
2. Prepare to move past the placeholder ad video:
   • RAF and custom ad layers: do not play the placeholder; the renderer takes its place in the pod.
   • SSAI: the placeholder is stitched into the stream, so seek over it (for example, to the end of the placeholder ad) before or after the renderer runs.
3. Create a TruexAdRenderer with createChild, observe its event field, and send the init action with the adParameters. If the adParameters are missing or invalid, there will be no events: continue the pod.
4. Send the start action when your app is ready to show the ad.
5. Wait for a terminal event. While you wait, keep track of whether adFreePod has fired.

The actions are described in SDK Integration.

Handling Terminal Events

A terminal event means the renderer is done, and your app must move the playback timeline forward. What "forward" means depends on whether the user earned the ad-free pod reward and on how your ads are inserted:

Renderer result	What to do	RAF CSAI	Google IMA DAI (SSAI)	Custom ad layer
adCompleted after adFreePod	Skip all remaining ads in the pod and continue the content	Do not call showAds for the pod, resume the content	Seek past the end of the current ad break	End the pod and restore the content
adCompleted without adFreePod	Skip the Infillion placeholder ad and play the next ad in the pod	Play the remaining ads of the pod	Seek to just before the placeholder's end, so the next stitched ad plays	Play the next ad in the pod
adError or noAdsAvailable	Same as adCompleted without adFreePod	Same	Same	Same
userCancelStream	The user closed the Infillion ad because they want to leave - exit the playback screen	Close the player	Close the player	Close the player

adCompleted without adFreePod covers a TrueX user who opted out or let the choice card time out, and it is the normal outcome of every IDVx ad, because IDVx never fires adFreePod.

IMPORTANT

Do not resume or seek when adFreePod fires. Remember that it fired, and act only on the terminal event that follows.

After any terminal event, hide the renderer, stop observing its event field, remove the TruexAdRenderer node from its parent, and drop all references to it. The full list of terminal events is on the Events page.