VPAID Integration

VPAID is the integration path for web sites and web apps that play ads through a client-side ad manager - for example Google IMA, or the built-in ad manager of a player such as Brightcove or Bitmovin. The ad manager loads Infillion's VPAID unit like any other VPAID ad, so you do not use the @truex/ad-renderer package or write any initialization code - see HTML5 Integration for that path.

It works on desktop and mobile browsers, and serves both TrueX and IDVx. The <AdSystem> value in the VAST response tells them apart, the same as in the other integrations.

Client-side only

VPAID needs a client-side ad manager that runs the unit in the player. It does not apply to SSAI, where the ads are stitched into the stream on the server. For SSAI, use the HTML5 Integration path.

What Does What

	Ad manager	Your app
Requests the VPAID tag	Yes
Loads and initializes the VPAID unit	Yes
Renders the choice card and the interactive ad	The VPAID unit, inside the ad manager's ad container
Handles the exit events - skips the ads in the pod, resumes the content		Yes

Your app only reacts to the events below. If your ad manager already forwards VPAID events, you can usually do all of this in an event listener.

Technical Requirements

• VAST and VPAID support. Your ad manager must support VPAID 2.0+, as defined by the IAB VAST and VPAID specifications. The unit is JavaScript-based and follows the VPAID 2.0 specification.
• The exit events below, handled by your app.
• Flighting. The tag must be in the right slot of each ad pod - see Flighting.

If your player shows an ad countdown (for example "30 seconds until content resumes" or "Ad 1 of 4"), disable it or switch to generic text such as "Your video will resume shortly" while the unit is loaded.

Exit Events

The unit dispatches standard VPAID events, and one custom event. Your app needs the following to move the playback forward.

Event	Meaning	What your app does
AdFreePod	TrueX only. The user fulfilled the time and interaction requirements of the ad. Custom event, not part of the VPAID specification	Do not present any more ads for the rest of the current ad pod. Keep the unit on screen - the user may keep interacting - until AdStopped
AdStopped	The unit is done and can be removed	Remove the unit. If AdFreePod fired, skip the rest of the pod; otherwise play the next ad
AdSkipped	The user opted out or the choice card timed out, or no ad was available for the user. A unit that identified itself as VPAID 1.0 in the handshake fires AdStopped instead	Play the next ad in the pod
AdError	The unit failed	Play the next ad in the pod

AdFreePod fires when the user earns the credit, but the user stays in the ad until they select "Return to content", which appears after about 30 seconds and one interaction. Do not skip the ads before the unit stops. AdFreePod never fires for IDVx - after an IDVx ad, always continue with the next ad in the pod.

When Custom Events Are Blocked

Some ad frameworks and VPAID libraries do not pass custom events such as AdFreePod to your app. In that case, listen for the standard VPAID AdInteraction event instead, and check for an Id of TrueXClosedAfterCredit. It fires when the user selects "Return to content" after earning the credit - the same moment as AdStopped after AdFreePod - so that is when you skip the rest of the ad pod. For example, with Google IMA, which passes AdInteraction as an INTERACTION event:

adsManager.addEventListener(
  google.ima.AdEvent.Type.INTERACTION,
  (event) => {
    if (event.getAdData().id === 'TrueXClosedAfterCredit') {
      // The user earned the credit and returned to the content:
      // skip the rest of the ad pod
      adsManager.discardAdBreak();
    }
  }
);

See the VPAID Examples for a complete page.

The unit fires these AdInteraction events, each identified by its Id:

Id	Fires when
TrueXChoiceCardLoaded	The choice card is shown to the user. Only fires if an ad is available
TrueXNoAdLoaded	The choice card would have been shown, but no ad was available, so it is skipped
TrueXUserOptIn	The user chooses to interact with the engagement ad
TrueXUserOptOut	The user chooses to watch the normal commercial breaks instead
TrueXUserTimeOut	The user does not choose in 15 seconds, and the choice card advances to the normal commercial breaks
TrueXCredit	The user fulfilled the time and interaction requirements - the same moment as AdFreePod. The user is still in the ad
TrueXClosedAfterCredit	The user selects "Return to content" after being credited - the same moment as AdStopped
TrueXClosedBeforeCredit	The user closes the engagement ad before being credited
TrueXSkipCardLoaded	The skip card ("Thank You" card) is shown to the user

Only TrueXClosedAfterCredit is needed to move the playback forward. The other events are for your own tracking.

Other Events

The unit also dispatches the other standard VPAID events: AdLoaded, AdStarted, AdImpression, AdVideoStart, AdVideoFirstQuartile, AdVideoMidpoint, AdVideoThirdQuartile, AdVideoComplete, AdClickThru, AdInteraction, and any event that follows a method call on the unit - for example AdSizeChange after resizeAd(), or AdPaused after pauseAd(). Your ad manager handles those.

For what the user sees and how the ads work, see TrueX and IDVx.