Events

TruexAdRenderer tells your app about the ad lifecycle through TruexAdEvent events. Each handler receives the event and a Map<String, ?> with the event's data.

You can listen to a single event, or pass null to handle all events in one place:

Kotlin

truexAdRenderer.addEventListener(TruexAdEvent.AD_STARTED) { event, data ->
    // ...
}

truexAdRenderer.addEventListener(null) { event, data ->
    when (event) {
        TruexAdEvent.AD_STARTED -> {
            // ...
        }
        // ...other events
        else -> Unit
    }
}

Java

truexAdRenderer.addEventListener(TruexAdEvent.AD_STARTED, (event, data) -> {
    // ...
});

truexAdRenderer.addEventListener(null, (event, data) -> {
    switch (event) {
        case AD_STARTED:
            // ...
            break;
        // ...other events
        default:
            break;
    }
});

Event Flow

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

◇  AD_FETCH_COMPLETED
│     ↓
◇  AD_STARTED
│     ↓
◇  AD_DISPLAYED
│     ↓
◇  OPT_IN
│     ↓
◆  [User interacts with the ad]
│     ↓
◇  AD_FREE_POD
│     ↓
◇  AD_COMPLETED

An IDVx ad has no choice card and no reward, so it goes from AD_DISPLAYED straight to AD_COMPLETED, without OPT_IN, OPT_OUT, or AD_FREE_POD.

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:

• AD_COMPLETED - the ad is finished
• AD_ERROR - the renderer hit an unrecoverable error
• NO_ADS_AVAILABLE - there is no ad for this user
• USER_CANCEL_STREAM - 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.

AD_FETCH_COMPLETED

Fired 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, call init 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.

AD_STARTED

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

AD_DISPLAYED

Fired after AD_STARTED 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.

AD_COMPLETED

Terminal event. Fired 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

Data key	Type	Description
timeSpent	Int	Time in seconds the user spent in the ad

Kotlin

truexAdRenderer.addEventListener(TruexAdEvent.AD_COMPLETED) { _, data ->
    val timeSpent = data?.get("timeSpent") as? Int
    finishInfillionAd(skipRemainingAds = truexAdCreditReceived)
}

Java

truexAdRenderer.addEventListener(TruexAdEvent.AD_COMPLETED, (event, data) -> {
    Integer timeSpent = (Integer) data.get("timeSpent");
    finishInfillionAd(truexAdCreditReceived);
});

AD_ERROR

Terminal event. Fired when the renderer hits an unrecoverable error. Handle it like AD_COMPLETED without AD_FREE_POD.

Data key	Type	Description
errorMessage	String	Description of the error

Kotlin

truexAdRenderer.addEventListener(TruexAdEvent.AD_ERROR) { _, data ->
    val errorMessage = data?.get("errorMessage") as? String
    finishInfillionAd(skipRemainingAds = false)
}

Java

truexAdRenderer.addEventListener(TruexAdEvent.AD_ERROR, (event, data) -> {
    String errorMessage = (String) data.get("errorMessage");
    finishInfillionAd(false);
});

NO_ADS_AVAILABLE

Terminal event. Fired when there is no ad available for this user. Handle it like AD_COMPLETED without AD_FREE_POD.

AD_FREE_POD

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

IDVx ads never fire this event.

Kotlin

truexAdRenderer.addEventListener(TruexAdEvent.AD_FREE_POD) { _, _ ->
    truexAdCreditReceived = true
}

Java

truexAdRenderer.addEventListener(TruexAdEvent.AD_FREE_POD, (event, data) -> {
    truexAdCreditReceived = true;
});

POPUP_WEBSITE

Fired when the ad wants to open a web page. Call pause() on the renderer and show the URL to the user, for example in a browser. When the user comes back, call resume().

This event is fired on mobile only.

Data key	Type	Description
url	String	The URL to open

Kotlin

truexAdRenderer.addEventListener(TruexAdEvent.POPUP_WEBSITE) { _, data ->
    val url = data?.get("url") as? String
    truexAdRenderer?.pause()
    startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
}

Java

truexAdRenderer.addEventListener(TruexAdEvent.POPUP_WEBSITE, (event, data) -> {
    String url = (String) data.get("url");
    truexAdRenderer.pause();
    startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(url)));
});

USER_CANCEL_STREAM

Terminal event. Fired when the user presses Back during 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 event is fired only if supportsUserCancelStream is true. Otherwise, Back on a TrueX choice card fires OPT_OUT and then AD_COMPLETED.

Informative Events

These events are mostly useful for tracking. Your app does not need to act on them.

OPT_IN

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

OPT_OUT

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

Data key	Type	Description
userInitiated	Boolean	true if the user selected it, false if the choice card countdown ran out

SKIP_CARD_SHOWN

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

USER_CANCEL

Fired 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 OPT_IN or OPT_OUT events can follow.