SDK 3.x Events

TruexAdRenderer tells your app about the ad lifecycle by calling methods of its TruexAdRendererDelegate, declared in TruexShared.h. Five methods are required, and the rest are optional.

Method	Required	Terminal
onFetchAdComplete
onAdStarted	Yes
onAdCompleted	Yes	Yes
onAdError	Yes	Yes
onNoAdsAvailable	Yes	Yes
onAdFreePod	Yes
onUserCancelStream		Yes
onOptIn
onOptOut
onSkipCardShown
onUserCancel

Event Flow

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

◇  onFetchAdComplete
│     ↓
◇  onAdStarted
│     ↓
◇  onOptIn
│     ↓
◆  [User interacts with the ad]
│     ↓
◇  onAdFreePod
│     ↓
◇  onAdCompleted

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:

• onAdCompleted - the ad is finished
• onAdError - the renderer hit an unrecoverable error
• onNoAdsAvailable - there is no ad for this user
• onUserCancelStream - the user wants to exit the stream

After a terminal event, call stop and remove all references to the renderer instance. Do not resume playback when onAdFreePod is called - wait for a terminal event.

Main Flow Events

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

onFetchAdComplete

Swift

func onFetchAdComplete()

Objective-C

- (void)onFetchAdComplete;

Optional. Called after the renderer is created, 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, create the renderer for a pre-roll and show a loading indicator until this event arrives, then call start; if your timeout is reached first, call stop and continue with the next ad. For a mid-roll, create the renderer before the slot, and call start right away if the event has arrived by the time the player reaches it.

onAdStarted

Swift

func onAdStarted(_ campaignName: String)

Objective-C

- (void)onAdStarted:(NSString *)campaignName;

Required. Called after start when the renderer's UI is ready and added to the view hierarchy. Your app does not need to act on it, but you can use it for a timeout: if it has not arrived in a reasonable time after start, call stop and continue with the next ad.

The parameters are:

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

onAdCompleted

Swift

func onAdCompleted(_ timeSpent: Int)

Objective-C

- (void)onAdCompleted:(NSInteger)timeSpent;

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

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

The parameters are:

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

If onAdFreePod was called before, skip all remaining ads in the pod. Otherwise, continue with the next ad.

onAdError

Swift

func onAdError(_ errorMessage: String)

Objective-C

- (void)onAdError:(NSString *)errorMessage;

Required. Terminal event. Called when the renderer hits an unrecoverable error. Handle it like onAdCompleted without onAdFreePod.

The parameters are:

• errorMessage: a description of the error

onNoAdsAvailable

Swift

func onNoAdsAvailable()

Objective-C

- (void)onNoAdsAvailable;

Required. Terminal event. Called when there is no ad available for this user. Handle it like onAdCompleted without onAdFreePod.

onAdFreePod

Swift

func onAdFreePod()

Objective-C

- (void)onAdFreePod;

Required. Called when the user has earned the reward. Do not resume or seek yet - remember that it was called, and when the terminal onAdCompleted arrives, skip all remaining ads in the pod. If it was not called before the terminal event, continue with the next ad so the user gets the normal video ads.

onUserCancelStream

Swift

func onUserCancelStream()

Objective-C

- (void)onUserCancelStream;

Optional. Terminal event. Called when the user closes the Infillion ad because they want to exit the stream. Handle it like any other exit from your player - usually by returning the user to the episode or series page.

This method is called only if supportsUserCancelStream is YES. Otherwise the renderer calls onAdCompleted instead. In a Swift app, set the option through the Objective-C helper described in Using TruexAdOptions from Swift.

Informative Events

These events are mostly useful for tracking. Your app does not need to act on them, and all of them are optional.

onOptIn

Swift

func onOptIn(_ campaignName: String, adId: Int)

Objective-C

- (void)onOptIn:(NSString *)campaignName adId:(NSInteger)adId;

Called when the user chooses the TrueX interactive ad on the choice card. It can be called more than once if the user opts in, backs out, and opts in again.

The parameters are:

• campaignName: the name of the ad campaign
• adId: the ad ID

onOptOut

Swift

func onOptOut(_ userInitiated: Bool)

Objective-C

- (void)onOptOut:(BOOL)userInitiated;

Called when the user chooses the normal video ads on the TrueX choice card.

The parameters are:

• userInitiated: YES if the user selected it, NO if the choice card countdown ran out

onSkipCardShown

Swift

func onSkipCardShown()

Objective-C

- (void)onSkipCardShown;

Called when a skip card is shown, because the user completed a TrueX Sponsored Stream ad earlier in the stream.

onUserCancel

Swift

func onUserCancel()

Objective-C

- (void)onUserCancel;

Called when the user backs out of the TrueX interactive ad after opting in, by confirming the "go back and choose a different ad experience" prompt. The user returns to the choice card with a full countdown, so more onOptIn or onOptOut calls can follow.