Events

TruexAdRenderer tells your app about the ad lifecycle through ad events. Subscribe to them with subscribe, using the event names below or the matching TruexAdEventType constants (for example TruexAdEventType.AD_FREE_POD for adFreePod). Four events are terminal, and adFreePod, userCancelStream, and popupWebsite need action from your app.

Event	Needs action	Terminal
adFetchCompleted
adStarted
adDisplayed
adCompleted	Yes	Yes
adError	Yes	Yes
noAdsAvailable	Yes	Yes
adFreePod	Yes
userCancelStream	Yes	Yes
popupWebsite	Mobile only
optIn
optOut
skipCardShown
userCancel
xtendedViewStarted
videoEvent

Event Flow

A typical TrueX ad where the user opts in and earns the reward:

◇  adFetchCompleted
│     ↓
◇  adStarted
│     ↓
◇  adDisplayed
│     ↓
◇  optIn
│     ↓
◆  [User interacts with the ad]
│     ↓
◇  adFreePod
│     ↓
◇  adCompleted

An IDVx ad has no choice card and no reward, so it goes from adDisplayed straight to adCompleted, without optIn, optOut, or adFreePod.

Terminal Events

A terminal event means the renderer is done, and your app must continue playback - see Handling Terminal Events for what to do in each case:

• adCompleted - the ad is finished
• adError - the renderer hit an unrecoverable error
• noAdsAvailable - there is no ad for this user
• userCancelStream - the user wants to exit the stream

After a terminal event, remove the ad overlay (the element that start resolves to) and all references to the renderer instance. stop is only needed to close an ad before a terminal event.

Main Flow Events

The following events signal the main flow of the TruexAdRenderer and may require action by the host app:

adFetchCompleted

This event fires in response to the init method when the TrueX ad request has successfully completed and the ad is ready to be presented. The host app may use this event to facilitate a loading screen for pre-rolls, or to facilitate an ad request timeout for mid-rolls.

For example: init is called for the pre-roll slot, and the host app code shows a loading indicator while waiting for adFetchCompleted. Then, either the event is received (and the app can call start) or a specific timeout is reached (and the app can discard the TruexAdRenderer instance and resume playback of normal video ads).

Another example: init is called well before a mid-roll slot to give the renderer a chance to preload its ad. If adFetchCompleted is received before the mid-roll slot is encountered, then the app can call start to immediately present the TrueX ad. If not, the app can wait for a specific timeout (if not already reached, in case the user has sought to activate the mid-roll) before removing the TruexAdRenderer instance and resuming playback with normal video ads.

adStarted

This event fires after the start call, when the TrueX UI is being constructed and connected to the web page.

adDisplayed

This event fires once the TrueX UI is loaded and visible, i.e. all image assets are loaded, etc.

This is useful if the host app is implementing its own loading indiciator UX (i.e. its own loading spinner), and needs to know when the ad UI is actually ready to be disabled without delays.

adCompleted

This is a terminal event. This event will fire when the TrueX unit is finished with its activities -- at this point, the app should resume playback and remove the TrueX ad renderer from its UI

Here are some examples where adCompleted will fire:

• The user opts for normal video ads (not TrueX)
• The choice card timeout runs out
• The user completes the TrueX ad unit
• After a "skip card" has been shown to a user for its duration

The event data field for this event is:

• timeSpent: The amount of time (in seconds) the user spent on the TrueX unit

adError

This is a terminal event. This event will fire when the TrueX unit has encountered an unrecoverable error. The host app code should handle this the same way as an adCompleted event -- resume playback and remove the TrueX ad renderer from its UI.

The event data field for this event is:

• errorMessage: A description of the cause of the error.

noAdsAvailable

This is a terminal event. This event will fire when the TrueX unit has determined it has no ads available to show the current user. The host app code should handle this the same way as an adCompleted event - resume playback and remove the TrueX ad renderer from its UI.

adFreePod

This event will fire when the user has earned a credit with TrueX. The host app code should notate that this event has fired, but should not take any further action. Upon receiving a terminal event, if adFreePod was fired, the app should skip all remaining ads in the current slot. If it was not fired, the app should resume playback without skipping any ads, so the user receives a normal video ad payload.

userCancelStream

This is a terminal event, and is only enabled when the supportsUserCancelStream property is set to true in the constructor options.

When enabled, the renderer will fire this event when the user intends to exit the stream entirely. The app, at this point, should treat this the same way it would handle any other "exit" action from within the stream -- in most cases this will result in the user being returned to an episode/series detail page.

If this event is not enabled, the renderer will emit an adCompleted event instead.

Informative Events

All following events are used mostly for tracking purposes -- no action is generally required.

optIn

This event will fire if the user selects to interact with the TrueX interactive ad.

Note that this event may be fired multiple times if a user opts in to the TrueX interactive ad and subsequently backs out.

optOut

This event will fire if the user opts for a normal video ad experience.

The event data field for this event is:

• userInitiated: This will be set to true if this was actively selected by the user, false if the user simply allowed the choice card countdown to expire.

skipCardShown

This event will fire anytime a "skip card" is shown to a user as a result of completing a TrueX Sponsored Stream interactive in an earlier pre-roll.

userCancel

This event will fire when a user backs out of the TrueX interactive ad unit after having opted in. This would be achieved by tapping the "Yes" link to the "Are you sure you want to go back and choose a different "ad experience" prompt inside the TrueX interactive ad. The user will be subsequently taken back to the Choice Card (with the countdown timer reset to full).

Note that after a userCancel, the user can opt-in and engage with an interactive ad again, so more optIn or optOut events may then be fired.

popupWebsite

On mobile platforms, ad units with links to external web sites fire this event when the user clicks on the web site link, e.g. typically via a "Learn More" link.

On mobile platforms, navigating to an external web site means leaving the current application. As such this ad event is used to communicate the user's intention, and the host app needs to open the external web page as appropriate for the platform. E.g. for Android, an intent is raised to open the web page in the phone's browser.

The event data field for this event is:

• url: Indicates the web page to navigate to.

xtendedViewStarted

This event fires for TrueX ad creatives that their own fallback extended videos built in.

From the host app's perspective, nothing more is needed to be done, and the regular ad event flow processing will occur, just with the extended ad content instead.

videoEvent

This event reports noteworthy video progress inside the TrueX unit.

The event data fields for this event are:

• subType: One of started, firstQuartile, secondQuartile, thirdQuartile, or completed
• videoName: The name of the video
• url: The video URL, when available