# @truex/ad-renderer

JavaScript renderer for [Infillion Interactive Video (IDVx) and TrueX products](https://infillion.com/products/infinite-video/) on desktop, mobile, and connected TV.

The host app detects a TrueX placeholder, pauses playback, creates a renderer, and handles its events. The renderer requests the ad and draws the choice card and engagement.

Full integration guide: <https://socialvibe.github.io/infillion-ads-integration-docs/platforms/web/>

## Install

```bash
npm install @truex/ad-renderer
```

## Usage

Use the class that matches the client, so ad tracking is recorded for that surface. `TruexAdRenderer` is the older name for `TruexAdRendererCTV`.

```js
import { TruexAdRendererCTV, TruexAdEventType } from '@truex/ad-renderer';
// TruexAdRendererDesktop or TruexAdRendererMobile, when that is the client.

const tar = new TruexAdRendererCTV(adParameters);

tar.subscribe((event) => {
    switch (event.type) {
        case TruexAdEventType.AD_STARTED:
            // TrueX UI is being added to the page.
            // A missing adStarted can be treated as a load timeout.
            console.log(event);
            break;
        case TruexAdEventType.AD_DISPLAYED:
            // UI is visible and its image assets have loaded.
            console.log(event);
            break;
        case TruexAdEventType.AD_FETCH_COMPLETED:
            // Ad request finished. Call start, or drop a preload that timed out.
            console.log(event);
            break;
        case TruexAdEventType.AD_FREE_POD:
            // Credit earned. Do not resume yet.
            // On the next terminal event, skip the rest of this ad pod.
            console.log(event);
            break;
        case TruexAdEventType.OPT_IN:
            // User chose the interactive ad. May fire again after they back out.
            console.log(event);
            break;
        case TruexAdEventType.OPT_OUT:
            // User chose a normal video ad, or the choice-card countdown expired.
            console.log(event);
            break;
        case TruexAdEventType.USER_CANCEL:
            // User left the engagement and returned to the choice card.
            console.log(event);
            break;
        case TruexAdEventType.SKIP_CARD_SHOWN:
            // Skip card is showing after a completed sponsored stream.
            console.log(event);
            break;
        case TruexAdEventType.XTENDED_VIEW_STARTED:
            // Creative is playing its built-in extended fallback video.
            console.log(event);
            break;
        case TruexAdEventType.POPUP_WEBSITE:
            // User clicked an external link. The host app opens event.url.
            console.log(event);
            break;
        case TruexAdEventType.AD_COMPLETED:
            // Terminal. Resume playback and remove the renderer.
            // Skip the rest of the pod only if adFreePod already fired.
            console.log(event);
            break;
        case TruexAdEventType.AD_ERROR:
            // Terminal. Unrecoverable error. Handle it like adCompleted.
            console.log(event);
            break;
        case TruexAdEventType.NO_ADS_AVAILABLE:
            // Terminal. No TrueX ad for this user. Handle it like adCompleted.
            console.log(event);
            break;
        case TruexAdEventType.USER_CANCEL_STREAM:
            // Terminal, only when supportsUserCancelStream is set.
            // Leave the stream the same way any other exit would.
            console.log(event);
            break;
    }
});

await tar.init();
await tar.start();
```

`adParameters` is the `<AdParameters>` value from the VAST response, parsed as JSON. `init` can run ahead of the ad break. `start` shows the unit when the player reaches the placeholder.

## CDN

A script tag without a file path loads the minified build, `dist/tar.min.js`:

```
https://cdn.jsdelivr.net/npm/@truex/ad-renderer@<version>
```

The npm package entry, `dist/tar.js`, is the unminified build.