Events

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

Method	Required	Terminal
onAdFetchCompleted
onAdStarted
onAdDisplayed
onAdCompleted	Yes	Yes
onAdError	Yes	Yes
onNoAdsAvailable	Yes	Yes
onAdFreePod	Yes
onPopupWebsite	Yes
onUserCancelStream		Yes
onOptIn
onOptOut
onSkipCardShown
onUserCancel

Event Flow

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

◇  onAdFetchCompleted
│     ↓
◇  onAdStarted
│     ↓
◇  onAdDisplayed
│     ↓
◇  onOptIn
│     ↓
◆  [User interacts with the ad]
│     ↓
◇  onAdFreePod
│     ↓
◇  onAdCompleted:

An IDVx ad has no choice card and no reward, so it goes from onAdDisplayed straight to onAdCompleted, without onOptIn, onOptOut, or onAdFreePod.

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.

Main Flow Events

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

onAdFetchCompleted

Swift

func onAdFetchCompleted()

Objective-C

- (void)onAdFetchCompleted;

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 before a midroll and show the ad with start once this event arrives; if your timeout is reached first, call stop and continue with the next ad.

onAdStarted

Swift

func onAdStarted()

Objective-C

- (void)onAdStarted;

Optional. Called after start when the renderer's view is added to the view hierarchy.

onAdDisplayed

Swift

func onAdDisplayed()

Objective-C

- (void)onAdDisplayed;

Optional. Called after onAdStarted when the initial ad assets are loaded and visible on the screen.

This is useful only if your app shows its own loading screen instead of the renderer's loading spinner: hide your loading screen when this event arrives.

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 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 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 a TrueX 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.

IDVx ads never call this method.

onPopupWebsite

Swift

func onPopupWebsite(_ url: String) {
    guard let pageUrl = URL(string: url) else {
        return
    }
    truexAdRenderer?.pause()
    let safari = SFSafariViewController(url: pageUrl)
    safari.delegate = self
    present(safari, animated: true)
}

// SFSafariViewControllerDelegate
func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
    truexAdRenderer?.resume()
}

Objective-C

- (void)onPopupWebsite:(NSString *)url {
    [self.truexAdRenderer pause];
    SFSafariViewController *safari = [[SFSafariViewController alloc] initWithURL:[NSURL URLWithString:url]];
    safari.delegate = self;
    [self presentViewController:safari animated:YES completion:nil];
}

// SFSafariViewControllerDelegate
- (void)safariViewControllerDidFinish:(SFSafariViewController *)controller {
    [self.truexAdRenderer resume];
}

Required. Called when the user taps an external link in the ad. Call pause on the renderer and show the page - in an SFSafariViewController, an in-app web view, or Safari. When the user comes back, call resume.

The parameters are:

• url: the URL to open

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. In a Swift app, set it 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()

Objective-C

- (void)onOptIn;

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.

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.

Deprecated Methods

Older integrations and reference apps may still implement these methods. They are still declared in the SDK but marked as deprecated - implement the replacements in new code:

Deprecated	Use instead
onAdStarted: (with campaignName)	onAdStarted
onOptIn:adId: (with campaignName and adId)	onOptIn
onAdsAvailable	onAdStarted