Getting Started

This guide will help you add the TrueX Ad Renderer to your existing FireTV app's advertising setup.

Installation

Install the TrueX Ad Renderer for Vega and its required dependencies.

1. Install the Package

   Using npm:

   npm install --save @truex/ad-renderer-vega

2. Peer Dependencies

   The TrueX Ad Renderer requires specific peer dependencies. Install all required packages:

   npm install \
     @amazon-devices/react-native-device-info@~2.0.0 \
     @amazon-devices/webview@~3.3.0

3. Verify Installation

   After installation, verify that the package is correctly installed:

   npm list @truex/ad-renderer-vega

   You should see output similar to:

   your-app@1.0.0
   └── @truex/ad-renderer-vega@x.x.x

Basic Usage

Learn how to integrate the TrueX Ad Renderer component into your React Native application.

Import the Component

In your React Native component, import the TrueX Ad component:

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

Import Types

For TypeScript projects, import the type definitions:

import {
  TruexAd,
  TruexAdEvent,
  TruexAdEventType,
  TruexAdRendererOptions,
  TruexAdProps
} from '@truex/ad-renderer-vega';

Minimal Example

Here's the simplest way to render a TrueX ad:

import React, { useCallback } from 'react';
import { TruexAd, TruexAdEventType, TruexAdEventHandler } from '@truex/ad-renderer-vega';

function TruexAdContainer({ truexAdInfo, onTruexAdFinished, onTruexAdFreePod}) {
  const handleTruexAdEvent = useCallback<TruexAdEventHandler>(
    event: TruexAdEvent) => {
      switch (event.type) {
        case TruexAdEventType.AD_COMPLETED:
        case TruexAdEventType.AD_ERROR:
        case TruexAdEventType.NO_ADS_AVAILABLE:
        case TruexAdEventType.USER_CANCEL_STREAM:
          // Ad finished, resume content
          onTruexAdFinished();
          break;

        case TruexAdEventType.AD_FREE_POD:
          // User earned ad credit
          onTruexAdFreePod()
          break;
      }
    },
    [ onTruexAdFinished, onTruexAdFreePod ]
  );

  // Parse the ad parameters from the VAST <AdParameters> node
  const adParameters = JSON.parse(truexAdInfo.adParameters);

  return (
    <TruexAd
      adParameters={adParams}
      onAdEvent={handleTruexAdEvent}
    />
  );
}

export default TruexAdContainer;

Component Props

The TruexAd component accepts the following props:

Required Props

• adParameters: An object containing the ad configuration. This object is obtained by parsing the JSON content of the <AdParameters> node from the VAST/VMAP response.
• onAdEvent: A callback function to handle ad lifecycle events.

// Parse the JSON string from the <AdParameters> node in your VAST response
const adParams = JSON.parse(adParametersStringFromVast);

<TruexAd
  adParameters={adParams}
  onAdEvent={handleTruexAdEvent}
/>

Optional Props

• options: Configuration options for the renderer.

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

const options: TruexAdRendererOptions = {
  supportsUserCancelStream: true,
  appId: 'my-firetv-app',
  enableWebViewDebugging: __DEV__
};

<TruexAd
  adParameters={adParams}
  options={options}
  onAdEvent={handleTruexAdEvent}
/>

Configuration Options

The options prop accepts a TruexAdRendererOptions object:

type TruexAdRendererOptions = {
  supportsUserCancelStream?: boolean,
  appId?: string,
  enableWebViewDebugging?: boolean,
};

---

supportsUserCancelStream

• Type: boolean
• Default: false
• Description: Enables the USER_CANCEL_STREAM terminal event. When enabled, users can exit the entire stream from within the ad experience.

<TruexAd
  adParameters={params}
  onAdEvent={handleTruexAdEvent}
  options={{ supportsUserCancelStream: true }}
/>

---

appId

• Type: string
• Default: undefined
• Description: Your application identifier for reporting and analytics.

<TruexAd
  adParameters={params}
  onAdEvent={handleTruexAdEvent}
  options={{ appId: 'my-firetv-app' }}
/>

---

enableWebViewDebugging

• Type: boolean
• Default: false
• Description: Enables WebView debugging tools. Should only be enabled in development builds.

<TruexAd
  adParameters={params}
  onAdEvent={handleEvent}
  options={{ enableWebViewDebugging: __DEV__ }}
/>

Runtime Version Information

Access the TrueX Ad Renderer version at runtime:

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

console.log(`Package: ${buildInfo.name}`);    // Package: @truex/ad-renderer-vega
console.log(`Version: ${buildInfo.version}`); // Version: 0.7.1
console.log(`Date: ${buildInfo.date}`);       // Date: 2025-12-04T16:06:55.046Z

Understanding the Integration Flow

Before diving into code, it's helpful to understand the integration workflow:

1. Video Playback - Your app plays video content
2. Ad Break Detected - Video player encounters ad break (pre-roll/mid-roll)
3. Pause Video & Show TrueX Ad - Pause playback, render TrueX component, hide controls
4. User Interaction - User engages with interactive ad experience
5. Terminal Event Received - Ad completion, error, or cancellation
6. Resume Video Playback - Hide ad, resume video, skip remaining ads if credit earned

Key Integration Points

Your integration will involve:

1. Ad Break Detection: Identifying when to show TrueX ads
2. Component Rendering: Displaying the <TruexAd> component
3. Event Handling: Responding to ad lifecycle events
4. Video Control: Managing video playback state
5. Ad Credit Tracking: Honoring earned ad-free viewing

What if I'm using a different video player?

The TrueX Ad Renderer is video-player agnostic. You'll need to integrate it with your specific player's API for pausing/resuming playback.

Is this only for FireTV?

The @truex/ad-renderer-vega package is specifically designed for Amazon Vega (FireTV). Other platforms have their own integration packages:

• Web/HTML Integration
• Roku Integration
• Android TV & Mobile Integration
• tvOS Integration