Integration Flow

An HTML5 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 constructed with an adParameters object. Where that JSON comes from depends on the VAST tag format and the ad framework your app uses:

Tag format	Where adParameters is in the VAST	Google IMA (CSAI and DAI)	Custom VAST parsing
Generic	<Linear><AdParameters> as a JSON string	ad.getTraffickingParametersString()	Text content of <AdParameters>
Companion	<Companion apiFramework="truex"><StaticResource creativeType="application/json"> as a base64 JSON data: URL	Use the generic tag with Google IMA	Text content of <StaticResource>, base64-decoded after the comma

Some ad vendors, such as Verizon / Uplynk, return the ad schedule in a JSON object from their own API instead of a VAST response. With these vendors, adParameters is part of that response - work with your Infillion contact to identify it.

First, identify the ad by its <AdSystem> value (ad.getAdSystem() in Google IMA), 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. Look for a companion with apiFramework="truex" and decode its JSON.
2. If there is none, parse the <AdParameters> 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 same parser reads both formats - the companion's data: URL and the plain <AdParameters> JSON:

// Reads `adParameters` from a `data:application/json;base64,...` URL or from plain JSON text.
// Returns undefined unless the result is a JSON object.
function parseAdParameters(resource) {
  let adParameters;
  try {
    const text = resource.trim();
    let json = text;
    if (text.toLowerCase().startsWith('data:')) {
      // The ad server may wrap the base64 payload across lines, so whitespace is removed before decoding.
      const base64 = text.replace(/\s+/g, '').split(',')[1];
      json = atob(base64);
    }
    const value = JSON.parse(json);
    if (value && typeof value === 'object' && !Array.isArray(value)) {
      adParameters = value;
    }
  } catch (err) {
    console.error('Could not parse adParameters: ' + err);
  }
  return adParameters;
}

With Google IMA, pass ad.getTraffickingParametersString() to parseAdParameters.

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:
   • CSAI and custom ad layers: the placeholder plays as a short video, so it can be skipped when the renderer is done.
   • SSAI: the placeholder is stitched into the stream, so remember where it ends (the placeholder start plus its duration) to seek there later.
3. Create the renderer class for your device - see Choosing the Renderer Class - with the adParameters object, and subscribe to its events.
4. Call init and then start. To save loading time, init can be called earlier, before the ad break is reached.
5. Wait for a terminal event. While you wait, keep track of whether adFreePod has fired.

The calls are described in SDK Integration.

Device Differences

	CTV	Desktop and mobile
Renderer class	TruexAdRendererCTV	TruexAdRendererDesktop or TruexAdRendererMobile
Input	The renderer maps remote and game controller keys to actions. Use keyMapOverrides on a device that is not supported yet	Mouse and touch
Main video	Hide player controls. On constrained devices, unload the main video if possible and resume it when the ad is done	Hide player controls, status bars, and soft keyboards
popupWebsite	Not used	The app must open the page (mobile only) - see popupWebsite

On CTV, if your app handles history.back(), add a popstate handler that only reacts to your own app's history state, so the renderer's back-action blocking keeps working while an ad is shown. On Fire TV, the back key cannot be reliably overridden, so popstate is the only option. The Examples show this in onBackAction.

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	Client-side ads (CSAI)	Server-side ads (SSAI)
adCompleted after adFreePod	Skip all remaining ads in the pod and continue the content	Skip the rest of the ad break, then resume the content	Seek past the end of the current ad break
adCompleted without adFreePod	Skip the Infillion placeholder ad and play the next ad in the pod	Play the next ad in the pod	Seek to just before the placeholder's end, so the next stitched ad plays
adError or noAdsAvailable	Same as adCompleted without adFreePod	Same	Same
userCancelStream	The user closed the Infillion ad because they want to leave - exit the playback screen	Close the player	Close the player

userCancelStream is only fired when the renderer is created with the supportsUserCancelStream option; otherwise a back action ends with adCompleted.

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 seek or resume playback when adFreePod fires. Remember that it fired, and act only on the terminal event that follows.

Skipping the remaining video ads is the responsibility of your app. Ad SDKs such as Google IMA provide enough information to find where the current pod ends; when the user earned the reward, fast-forward directly to that point when resuming playback.

After any terminal event, remove the ad overlay (the element that start resolves to) and drop all references to the renderer instance. The full list of terminal events is on the Events page.