SDK Integration

Adding the SDK

TruexAdRenderer-Android is distributed through the Infillion Maven repository:

• Repository: https://s3.amazonaws.com/android.truex.com/tar/prod/maven
• Group ID: com.truex
• Artifact ID: TruexAdRenderer-Android
• Version: 2.10.4

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://s3.amazonaws.com/android.truex.com/tar/prod/maven")
    }
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://s3.amazonaws.com/android.truex.com/tar/prod/maven" }
    }
}

build.gradle.kts

dependencies {
    implementation("com.truex:TruexAdRenderer-Android:2.10.4")
}

build.gradle

dependencies {
    implementation 'com.truex:TruexAdRenderer-Android:2.10.4'
}

The SDK classes are in the com.truex.adrenderer package:

• TruexAdRenderer - renders the ad and is controlled by your app
• TruexAdOptions - configuration options for init
• TruexAdEvent - the events the renderer fires, see Events
• IEventEmitter.IEventHandler - the event listener interface

Renderer Container

The renderer shows the ad in a ViewGroup that you provide. Place a full-screen container above your video player:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.media3.ui.PlayerView
        android:id="@+id/playerView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

    <FrameLayout
        android:id="@+id/adContainer"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

Hide as much other UI as possible while the ad is showing, including player controls and status bars.

Quick Example

A complete start of an Infillion ad, where adParameters is the JSON resolved from the VAST response:

Kotlin

private var truexAdRenderer: TruexAdRenderer? = null
private var truexAdCreditReceived = false

private val truexAdEventHandler = IEventEmitter.IEventHandler { event, data ->
    when (event) {
        TruexAdEvent.AD_FREE_POD -> {
            // Remember the reward, act on it on AD_COMPLETED
            truexAdCreditReceived = true
        }
        TruexAdEvent.AD_COMPLETED -> {
            finishInfillionAd(skipRemainingAds = truexAdCreditReceived)
        }
        TruexAdEvent.AD_ERROR,
        TruexAdEvent.NO_ADS_AVAILABLE -> {
            finishInfillionAd(skipRemainingAds = false)
        }
        TruexAdEvent.USER_CANCEL_STREAM -> {
            exitPlayback()
        }
        else -> Unit
    }
}

private fun startInfillionAd(adParameters: JSONObject) {
    truexAdCreditReceived = false
    val options = TruexAdOptions().apply {
        supportsUserCancelStream = true
        appId = packageName
        enableWebViewDebugging = BuildConfig.DEBUG
    }
    truexAdRenderer = TruexAdRenderer(this).also { renderer ->
        renderer.addEventListener(null, truexAdEventHandler)
        renderer.init(adParameters, options)
        renderer.start(binding.adContainer)
    }
}

private fun disposeRenderer() {
    truexAdRenderer?.removeEventListener(null, truexAdEventHandler)
    truexAdRenderer?.stop()
    truexAdRenderer = null
}

Java

private TruexAdRenderer truexAdRenderer;
private boolean truexAdCreditReceived = false;

private final IEventEmitter.IEventHandler truexAdEventHandler = (event, data) -> {
    switch (event) {
        case AD_FREE_POD:
            // Remember the reward, act on it on AD_COMPLETED
            truexAdCreditReceived = true;
            break;
        case AD_COMPLETED:
            finishInfillionAd(truexAdCreditReceived);
            break;
        case AD_ERROR:
        case NO_ADS_AVAILABLE:
            finishInfillionAd(false);
            break;
        case USER_CANCEL_STREAM:
            exitPlayback();
            break;
        default:
            break;
    }
};

private void startInfillionAd(JSONObject adParameters) {
    truexAdCreditReceived = false;
    TruexAdOptions options = new TruexAdOptions();
    options.supportsUserCancelStream = true;
    options.appId = getPackageName();
    options.enableWebViewDebugging = BuildConfig.DEBUG;

    truexAdRenderer = new TruexAdRenderer(this);
    truexAdRenderer.addEventListener(null, truexAdEventHandler);
    truexAdRenderer.init(adParameters, options);
    truexAdRenderer.start(adContainer);
}

private void disposeRenderer() {
    if (truexAdRenderer != null) {
        truexAdRenderer.removeEventListener(null, truexAdEventHandler);
        truexAdRenderer.stop();
        truexAdRenderer = null;
    }
}

finishInfillionAd and exitPlayback are your app's code - what they have to do is described in Handling Terminal Events.

TruexAdRenderer Methods

init

Kotlin

fun init(adParameters: JSONObject)
fun init(adParameters: JSONObject, options: TruexAdOptions)

Java

public void init(JSONObject adParameters)
public void init(JSONObject adParameters, TruexAdOptions options)

Initializes the renderer with the adParameters JSON and starts the ad request to the Infillion ad server. The renderer fires AD_FETCH_COMPLETED when the request is done.

You can call init early, a few seconds before the ad break starts, to give the renderer more time for the request, and call start once the player reaches the ad.

The parameters are:

• adParameters: the JSON payload from the VAST response, see Resolving adParameters
• options: an optional TruexAdOptions object

start

Kotlin

fun start(baseView: ViewGroup)

Java

public void start(ViewGroup baseView)

Shows the ad to the user. Call it when your app is ready to display the ad; it can be called any time after init. If the ad request from init is not finished yet, the renderer waits for it, then adds its view to baseView and fires AD_STARTED.

After calling start, wait for a terminal event and keep track of whether AD_FREE_POD has fired.

• baseView: the ViewGroup the renderer adds its view to. It should cover the entire screen.

stop

Kotlin

fun stop()

Java

public void stop()

Stops the renderer immediately and releases its resources. Call it after a terminal event, and also when:

• the user leaves the playback screen while the ad is showing
• an unrelated error requires your app to stop the ad
• your own timeout for AD_FETCH_COMPLETED or AD_STARTED is reached

A stopped renderer cannot be resumed or reused - remove all references to it.

pause

Kotlin

fun pause()

Java

public void pause()

Pauses the ad's videos, audio, and timers. Call it when your app is paused, for example from onPause, and when your app shows a popup for POPUP_WEBSITE.

resume

Kotlin

fun resume()

Java

public void resume()

Resumes a paused renderer.

addEventListener / removeEventListener

Kotlin

fun addEventListener(event: TruexAdEvent?, handler: IEventEmitter.IEventHandler)
fun removeEventListener(event: TruexAdEvent?, handler: IEventEmitter.IEventHandler)

Java

public void addEventListener(TruexAdEvent event, IEventEmitter.IEventHandler handler)
public void removeEventListener(TruexAdEvent event, IEventEmitter.IEventHandler handler)

Registers or removes a listener for one event. Pass null as the event to register one handler for all events, as in the Quick Example. See Events for the full list.

TruexAdOptions

Option	Default	Description
supportsUserCancelStream	false	If true, a Back press during the ad fires USER_CANCEL_STREAM, so your app can exit the stream. If false, Back on a TrueX choice card fires OPT_OUT and then AD_COMPLETED, and Back during an IDVx ad does nothing.
appId	package name	Used for internal tracking. Computed from the context's getPackageName() if not set.
enableWebViewDebugging	false	If true, remote WebView debugging through chrome://inspect is enabled, even for release builds. Otherwise it is allowed only for debug builds and for QA ads (from qa-get.truex.com).

Activity Lifecycle

Forward your activity lifecycle to the renderer while it is active, and release it when the activity is destroyed:

Kotlin

override fun onPause() {
    if (truexAdRenderer != null) {
        truexAdRenderer?.pause()
    } else {
        player.pause()
    }
    super.onPause()
}

override fun onResume() {
    super.onResume()
    if (truexAdRenderer != null) {
        truexAdRenderer?.resume()
    } else {
        player.play()
    }
}

override fun onDestroy() {
    disposeRenderer()
    player.release()
    super.onDestroy()
}

Java

@Override
protected void onPause() {
    if (truexAdRenderer != null) {
        truexAdRenderer.pause();
    } else {
        player.pause();
    }
    super.onPause();
}

@Override
protected void onResume() {
    super.onResume();
    if (truexAdRenderer != null) {
        truexAdRenderer.resume();
    } else {
        player.play();
    }
}

@Override
protected void onDestroy() {
    disposeRenderer();
    player.release();
    super.onDestroy();
}