TruexAdRenderer Web Integration: Quick Guide

This document describes the how to use Infillion's TrueX web ad renderer, a library that allows the presentation of interactive ads, intended for use in "Full Episode Player" (FEP) scenarios such as video web sites or applications.

The library provides a class called the TruexAdRenderer (TAR). TAR supports running within any web content, specifically for desktop and mobile web content, as well as for the "Connected TV" (CTV) platforms, such as Smart TVs and game consoles, i.e. for the so-called "10 foot" experience.

Setup

The TrueX ad renderer is available as an npm module. For the typical web based development around a package.json project file, you add the TrueX dependency as follows:

npm add @truex/ad-renderer

this will add an entry in the "dependencies" section in the package.json file, something like:

    "dependencies": {
        "@truex/ad-renderer": "1.12.5",

You then build and run your web app like usual, e.g. invoking npm start for webpack-based projects.

Alternatively, if you prefer you can refer to the TAR library directly in a script tag, e.g.

<script src="https://cdn.jsdelivr.net/npm/@truex/ad-renderer@1.12.5"></script>

or if you want to always refer to the latest version:

<script src="https://cdn.jsdelivr.net/npm/@truex/ad-renderer@latest"></script>

Initialization

Once a TrueX ad is detected, the renderer needs to be created and displayed. The following code snippet provides an example of the typical approach of integrating to TAR. For example, it shows how you can call the init and start methods to get the ad displayed, and to listen for the key ad events a client publisher needs to respond to, ultimately to control how to resume the main video.

We refer to a vastConfigUrl in this snippet, which you should be pull out of the TrueX ad response in the ad schedule from your ad server / SSAI provider.

import { TruexAdRendererCTV } from '@truex/ad-renderer';

...

videoController.pause();

let adFreePod = false;

const tar = new TruexAdRendererCTV(vastConfigUrl); // or TruexAdRendererDesktop or TruexAdRendererMobile, as appropriate
tar.subscribe(handleAdEvent);

const vastConfig = await tar.init();
let adOverlay = await tar.start(vastConfig);

...

function handleAdEvent(event) {
  const adEvents = tar.adEvents;
  switch (event.type) {
    case adEvents.adFreePod:
      adFreePod = true; // the user did sufficient interaction for an ad credit
      break;

    case adEvents.adError:
      console.error('ad error: ' + event.errorMessage);
      resumePlayback();
      break;
      
    case adEvents.noAdsAvailable:
    case adEvents.adCompleted:
      // Ad is not available, or has completed. Depending on the adFreePod flag, either the main
      // video or the ad fallback videos are resumed.
      resumePlayback();
      break;
  }
}

function resumePlayback() {
    if (adFreePod) {
        // The user has the credit, resume the main video after the ad break.
        videoController.skipAdBreak();
        videoController.resumeMainVideo();
    } else {
        // Continue with playing the remaining fallback ad videos in the ad break.
        videoController.skipCurrentAd();
        videoController.resumeAdBreak();
    }
}

Next Steps

TruexAdRenderer-Web Documentation outlines use of the ad renderer, including its API interface and the observable events it fires.

Reference Apps

Here is a reference application example that uses the TruexAdRenderer, demonstrating its use from a main video, as well as including several platform launcher projects that demonstrate how to sideload the reference application to various devices.

1. Generic Reference App
   • Presents a "Generic" CSAI style web app that uses the TruexAdRenderer, demonstrating its use from a main video, as well as including several platform launcher projects that demonstrate how to sideload the reference application to various devices.
2. Google Ad Manager: Server-side Ad Insertion Reference App
3. Google Ad Manager: Client-side Ad Insertion Reference App