Events

TruexAdRenderer tells your app about the ad lifecycle through its event field. Each event is an associative array whose type identifies it. adCompleted, adError, and noAdsAvailable must be handled, as well as adFreePod; the rest are optional.

Event	Required	Terminal
adFetchCompleted
adStarted
adCompleted	Yes	Yes
adError	Yes	Yes
noAdsAvailable	Yes	Yes
adFreePod	Yes
userCancelStream		Yes
adsAvailable
optIn
optOut
skipCardShown
userCancel
videoEvent

All events are read in the handler of the event field:

function handleTarEvent(evt as Object) as Void
    adEvent = evt.getData()
    ' adEvent.type is the event name
end function

Event Flow

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

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

An IDVx ad has no choice card and no reward, so it goes from adStarted 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 TruexAdRenderer component from the Scene Graph.

Main Flow Events

These events drive the integration and may require action from your app.

adFetchCompleted

' adEvent : {
'     type : "adFetchCompleted"
' }

Optional. Fires after init, when the ad request is done and the ad is ready to be shown.

You can use it for a loading screen or a timeout. For example, send init for a preroll, show your loading indicator, and send start when this event arrives - or, if your timeout is reached first, remove the renderer and continue with the regular ads. For a midroll, send init well before the slot; if the event arrived by the time the slot is reached, send start to show the ad immediately.

adStarted

' adEvent : {
'     type : "adStarted",
'     campaignName : <string with the campaign name>
' }

Optional. Fires after start, when the renderer's UI is ready and added to the component hierarchy. You can use it for your own timeout: if adStarted does not fire in time, continue with the regular ads.

The parameters are:

• campaignName: the name of the ad campaign available to the user

adCompleted

' adEvent : {
'     type : "adCompleted",
'     timeSpent : <integer, seconds>
' }

Required. Terminal event. Fires when the ad is finished, for example when:

• the TrueX user chooses the normal video ads, or the choice card countdown runs out
• the TrueX user completes the ad and exits it
• a TrueX skip card has been shown for its duration
• an IDVx ad ends

The parameters are:

• timeSpent: time in seconds the user spent in the ad

If adFreePod fired before, skip all remaining ads in the pod. Otherwise, continue with the next ad.

adError

' adEvent : {
'     type : "adError",
'     errorMessage : <string with the error message>
' }

Required. Terminal event. Fires when the renderer hits an unrecoverable error. Handle it like adCompleted without adFreePod.

The parameters are:

• errorMessage: a description of the error

noAdsAvailable

' adEvent : {
'     type : "noAdsAvailable"
' }

Required. Terminal event. Fires when there is no ad available for this user. Handle it like adCompleted without adFreePod.

adFreePod

' adEvent : {
'     type : "adFreePod"
' }

Required. Fires when a TrueX user has earned the reward. Do not resume or seek yet - remember that it fired, and when the terminal adCompleted arrives, skip all remaining ads in the pod.

IDVx ads never fire this event.

userCancelStream

' adEvent : {
'     type : "userCancelStream"
' }

Terminal event. Enabled only when supportsUserCancelStream is true in the init action. Fires when the user wants to exit the stream entirely. Treat it like any other "exit" action from the stream - usually, return the user to the episode or series page.

If it is not enabled, the renderer fires adCompleted instead.

Informative Events

These events are used mostly for tracking. No action is generally required.

adsAvailable

' adEvent : {
'     type : "adsAvailable"
' }

Fires after a successful ad request, together with adFetchCompleted, to tell that ad inventory is available. It is the opposite of noAdsAvailable, and helps you decide when a pre-loaded renderer can be started.

optIn

' adEvent : {
'     type : "optIn"
' }

Fires when the user chooses to interact with the TrueX ad. It can fire more than once if the user opts in, backs out, and opts in again. IDVx ads never fire it.

optOut

' adEvent : {
'     type : "optOut",
'     userInitiated : <true or false>
' }

Fires when the user chooses the normal video ad experience. IDVx ads never fire it.

The parameters are:

• userInitiated: true if the user chose it, false if the choice card countdown ran out

skipCardShown

' adEvent : {
'     type : "skipCardShown"
' }

Fires when a TrueX "skip card" is shown to the user, as a result of completing a TrueX Sponsored Stream ad in an earlier preroll.

userCancel

' adEvent : {
'     type : "userCancel"
' }

Fires when the user opted in and then backs out of the TrueX ad, and goes back to the choice card (with the countdown restarted). After a userCancel, the user can opt in again, so more optIn or optOut events can follow.

videoEvent

' adEvent : {
'     type : "videoEvent",
'     subType : "<the subType>",
'     videoName : "<the name of the video, if available>",
'     url : "<the source URL of the video, if available>"
' }

Fires when something noteworthy happens in a video inside the ad. The subType is one of:

• started: a video has started
• firstQuartile: a video has reached its first quartile
• secondQuartile: a video has reached its second quartile
• thirdQuartile: a video has reached its third quartile
• completed: a video has reached completion

The parameters are:

• subType: the type of the video event
• videoName: the name of the video, if available
• url: the source URL of the video, if available