Event Handling

The TrueX Ad Renderer uses an event-driven architecture to communicate ad lifecycle states to your application.

Event Flow Diagram

Typical event sequence for a successful ad interaction:

◇  adStarted
│     ↓
◇  adFetchCompleted
│     ↓
◇  adDisplayed
│     ↓
◇  optIn (if user chooses interactive ad)
│     ↓
◆  [User interacts with ad]
│     ↓
◇  adFreePod (if user completes interaction)
│     ↓
◇  adCompleted

Event Handler Implementation

Basic Event Handler

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

const [ shouldSkipRemainingAds, setShouldSkipRemainingAds ] = useState(false);

const handleTruexAdEvent = useCallback<TruexAdEventHandler>(
  (event: TruexAdEvent) => {
    console.log('Event:', event.type);

    switch (event.type) {
      case TruexAdEventType.AD_COMPLETED:
        (shouldSkipRemainingAds)
          ? discardCurrentAdBreak()
          : startNextAdInCurrentAdBreak();
        break;
      case TruexAdEventType.AD_ERROR:
        startNextAdInCurrentAdBreak();
        break;
      case TruexAdEventType.NO_ADS_AVAILABLE:
        startNextAdInCurrentAdBreak();
        break;
      case TruexAdEventType.USER_CANCEL_STREAM:
        exitPlaybackScreen();
        break;
      case TruexAdEventType.AD_FREE_POD:
        setShouldSkipRemainingAds(true);
        break
    }
  },
  [ shouldSkipRemainingAds ]
);

Type-Safe Event Handling

TypeScript provides discriminated union types for type-safe event handling:

const handleTruexAdEvent = useCallback<TruexAdEventHandler>(
  (event: TruexAdEvent) => {
    switch (event.type) {
      case TruexAdEventType.AD_ERROR:
        // TypeScript knows errorMessage exists on this event
        logError(event.errorMessage);
        break;

      case TruexAdEventType.POPUP_WEBSITE:
        // TypeScript knows url exists on this event
        openBrowser(event.url);
        break;

      case TruexAdEventType.AD_COMPLETED:
        // TypeScript knows this event has only type property (and timeSpent)
        resumePlayback();
        break;
    }
  },
  []
);

Terminal Events

Terminal events indicate that the ad experience has concluded and your application should resume normal operation:

---

adCompleted

{ type: TruexAdEventType.AD_COMPLETED, timeSpent: number }

User successfully completed the interactive ad experience. Resume video playback.

Properties:

• timeSpent: Time spent in the ad experience in seconds.

---

adError

{ type: TruexAdEventType.AD_ERROR, errorMessage: string }

An error occurred during ad playback. Resume video playback and log the error.

Properties:

• errorMessage: Human-readable error description

---

noAdsAvailable

{ type: TruexAdEventType.NO_ADS_AVAILABLE }

No ads are available to display. Resume video playback immediately.

---

userCancelStream

{ type: TruexAdEventType.USER_CANCEL_STREAM }

User chose to exit the stream entirely. Navigate away from video playback.

Note: Only fired when supportsUserCancelStream: true is set in options.

Informational Events

Informational events provide status updates but don't require immediate action:

---

adStarted

{ type: TruexAdEventType.AD_STARTED }

Ad UI construction has begun. Consider showing a loading indicator.

---

adFetchCompleted

{ type: TruexAdEventType.AD_FETCH_COMPLETED }

Ad creative has been fetched and is ready to be presented.

---

adDisplayed

{ type: TruexAdEventType.AD_DISPLAYED }

Ad is fully loaded and displayed to the user. Hide loading indicators.

---

adFreePod

{ type: TruexAdEventType.AD_FREE_POD }

User has earned ad-free viewing credit. Skip remaining ads in the current pod.

---

optIn

{ type: TruexAdEventType.OPT_IN, userInitiated: boolean }

User chose to engage with the interactive ad experience.

Properties:

• userInitiated - true if actively selected by user, false if choice card countdown expired.

---

optOut

{ type: TruexAdEventType.OPT_OUT, userInitiated: boolean }

User declined to engage with the interactive ad.

Properties:

• userInitiated: true if actively selected by user, false if choice card countdown expired.

---

userCancel

{ type: TruexAdEventType.USER_CANCEL }

User backed out of the ad but did not exit the stream.

Properties:

• url: The URL to open in an external browser

Helper Functions

isTerminalEvent

Determines if an event is a terminal event.

function isTerminalEvent(event: TruexAdEvent): boolean

Parameters:

• event - The event to check

Returns: true if the event is terminal, false otherwise

Example:

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

const handleTruexAdEvent = (event: TruexAdEvent) => {
  if (isTerminalEvent(event)) {
    // Handle terminal event
    hideAd();
    resumeVideo();
  }
};

Checking for Terminal Events

Use the helper function to determine if an event is terminal:

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

const handleTruexAdEvent = (event: TruexAdEvent) => {
  console.log('Event:', event.type);

  if (isTerminalEvent(event)) {
    // This is a terminal event - resume app
    hideAd();
    resumeVideo();
  }
};

Best Practices

Always Handle All Terminal Events

const handleTruexAdEvent = (event: TruexAdEvent) => {
  if (isTerminalEvent(event)) {
    cleanupAd();
    resumeApp();
  }
};

Track Ad Credits

case TruexAdEventType.AD_COMPLETED:
  // Skip remaining ads in this pod if `adFreePodEearnd` is true
  adFreePodEarned
    ? skipRemainingAds()
    : startNextAdInCurrentAdBreak()
  ;
  break;

case TruexAdEventType.AD_FREE_POD:
  // Mark that user earned ad-free viewing
  // and call `skipRemainingAds` on `adCompleted`
  setAdFreePodEarned(true);
  break;

Use Callbacks Properly

Wrap event handlers in useCallback to prevent unnecessary re-renders:

const handleTruexAdEvent = useCallback((event: TruexAdEvent) => {
  // Handler implementation
}, [/* dependencies */]);