TruexAdRenderer-Vega

TrueX Ad Renderer for Amazon Vega OS (Kepler) - A React Native library for integrating interactive TrueX ads into your Vega-based applications.

Installation

Install the package via npm:

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

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

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

Usage

Import the Component

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

Create an Instance

The TruexAd component can be instantiated in your React Native application by providing the required props:

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

function MyVideoPlayer({ adParameters }) {
  const [ showTruexAd, setShowTruexAd ] = useState(false);
  const [ hasAdCredit, setHasAdCredit ] = useState(false);

  // Configure TrueX ad options
  const tarOptions = useMemo<TruexAdRendererOptions>(() => ({
    supportsUserCancelStream: false, // Optional: enable user cancel stream events
    enableWebViewDebugging: false, // Optional: enable WebView debugging
  }), []);

  // Handle ad events
  const onAdEvent = useCallback<TruexAdEventHandler>((event) => {
    console.log(`TrueX event: ${event.type}`);

    switch (event.type) {
      case TruexAdEventType.AD_STARTED:
        // Ad UI is being constructed
        break;

      case TruexAdEventType.AD_DISPLAYED:
        // Ad UI is fully loaded and visible
        break;

      case TruexAdEventType.AD_FREE_POD:
        // User earned credit - skip remaining ads in this slot
        setHasAdCredit(true);
        break;

      case TruexAdEventType.AD_COMPLETED:
        // Ad finished - resume video playback
        setShowTruexAd(false);
        resumeVideoPlayback();
        break;

      case TruexAdEventType.AD_ERROR:
        // Error occurred - resume video playback
        console.error('TrueX ad error:', event.errorMessage);
        setShowTruexAd(false);
        resumeVideoPlayback();
        break;

      case TruexAdEventType.NO_ADS_AVAILABLE:
        // No ads to show - resume video playback
        setShowTruexAd(false);
        resumeVideoPlayback();
        break;
    }
  }, []);

  const resumeVideoPlayback = () => {
    // Resume your video player
  };

  return (
    <View>
      {/* Your video player UI */}

      {showTruexAd && (
        <TruexAd
          adParameters={adParameters}
          options={tarOptions}
          onAdEvent={onAdEvent}
        />
      )}
    </View>
  );
}

Listen to Events

The onAdEvent callback receives event objects with different types. Here are the key events to handle:

Terminal Events

These events indicate the ad experience is complete and you should resume playback:

• adCompleted - User finished interacting with the ad
• adError - An error occurred (includes errorMessage property)
• noAdsAvailable - No ads available for this user
• userCancelStream - User wants to exit the stream (requires supportsUserCancelStream: true)

Informational Events

• adStarted - Ad UI construction has begun
• adDisplayed - Ad UI is fully loaded and visible
• adFetchCompleted - Ad request completed successfully, ready to present
• adFreePod - User earned credit to skip ads
• optIn - User chose to engage with interactive ad
• optOut - User chose normal video ad experience
• userCancel - User backed out of interactive ad
• skipCardShown - Skip card is shown
• popupWebsite - User clicked external link (includes url property)

Event Handler Type Safety

The library exports TypeScript types for full type safety:

import {
  TruexAdEventType,
  TruexAdEventHandler,
  isTerminalEvent
} from '@truex/ad-renderer-vega';

const onAdEvent: TruexAdEventHandler = (event) => {
  // event.type is properly typed
  if (isTerminalEvent(event)) {
    // Handle terminal events
  }

  // Access event-specific properties with type safety
  if (event.type === TruexAdEventType.AD_ERROR) {
    console.error(event.errorMessage);
  }

  if (event.type === TruexAdEventType.OPT_IN) {
    console.log('User initiated:', event.userInitiated);
  }
};

API Reference

TruexAd Component Props

type TruexAdProps = {
  adParameters?: TruexAdParameters,  // `<AdParameters/>` json object from VAST response
  options?: TruexAdRendererOptions,  // TruexAdRenderer configuration options
  onAdEvent: TruexAdEventHandler,    // Event callback (required)
};

TruexAdRendererOptions

type TruexAdRendererOptions = {
  supportsUserCancelStream?: boolean,  // Enable user cancel stream events
  userAdvertisingId?: string,          // User ID for analytics
  appId?: string,                      // Application identifier
  enableWebViewDebugging?: boolean,    // Enable WebView debugging
};

Best Practices

1. Always handle terminal events: Ensure you handle adCompleted, adError, noAdsAvailable, and optionally userCancelStream to properly resume playback.

2. Track ad credits: When adFreePod fires, remember to skip remaining ads in the current ad slot.

3. Hide controls during ad: Prevent user interaction with your video player controls while the TrueX ad is showing.

Example Integration Flow

// 1. Detect ad break in your video
const onAdBreak = () => {
  pauseVideoPlayer();
  setShowTruexAd(true);
};

// 2. Show TruexAd component
<TruexAd
  adParameters={adParameters}
  options={tarOptions}
  onAdEvent={onAdEvent}
/>

// 3. Handle terminal ad events (completion, errors, no-ads)
const onAdEvent = (event) => {
  if (isTerminalEvent(event)) {
    setShowTruexAd(false);

    if (hasAdCredit) {
      // Skip to end of ad break
      seekToEndOfAdBreak();
    } else {
      // Resume normal playback
      resumeVideoPlayer();
    }
  }
};

Version Information

Access the library version at runtime:

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

console.log('TruexAd Version:', version);
console.log('Build Info:', buildInfo);

License

MIT