InRead - Classic Integration

This page explains how to integrate a Teads inRead placement into your Android application.

If you are using a WebView to display a web based content, please refer to the Webview integration documentation.

If your application already integrates the Teads inApp SDK v4, you may want to check v4 to v5 migration documentation.

Prerequisites
Implementation
Ad Resizing
Slot monitoring
Event Monitoring
Clean
Brand Safety and web content URL
Check list
Additional settings

Prerequisites

Import the Teads inApp SDK in your project.

Implementation

The article is using the landscape test PID 84242. This PID is meant for testing purpose and shall not be released into production.

Please retrieve your production PID from your local account manager.

See this page for more test PIDs and creative formats.

Add a container view to your layout

<?xml version="1.0" encoding="utf-8"?>
<ScrollView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="vertical">
        <TextView
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:text="@string/lorem_medium"/>
        <FrameLayout
            android:id="@+id/containerAdView"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />
        <TextView
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:text="@string/lorem_medium"/>
    </LinearLayout>
</ScrollView>

Load an Ad

class MainActivity : AppCompatActivity(), InReadAdListener {
    private lateinit var adPlacement: InReadAdPlacement

    private lateinit var binding: ActivityInReadBasicBinding

    override fun onCreate(savedInstanceState: Bundle) {
        super.onCreate(savedInstanceState)
        binding = ActivityInReadBasicBinding.inflate(layoutInflater)
        setContentView(binding.root)

        val requestSettings = AdRequestSettings.Builder().build()

        adPlacement = TeadsSDK.createInReadPlacement(this, 84242)
        adPlacement.requestAd(requestSettings, this)
    }

    override fun onAdReceived(inReadAdView: InReadAdView, adRatio: AdRatio) {
        binding.containerAdView.addView(inReadAdView)
    }

    override fun adOpportunityTrackerView(trackerView: AdOpportunityTrackerView) {
        binding.containerAdView.addView(trackerView)
    }

    // This should be implemented if slot height is not set to wrap_content
    override fun onAdRatioUpdate(adRatio: AdRatio) {}
}

Ad Resizing

Having the ad creative correctly rendered is crucial to ensure great user experience and good performance measurement.

Allowed by VPAID standard; ads can adopt modular dimensions and ratio in place of pre-defined fixed sizes making necessary to be able to dynamically adapt the size and ratio of the ad view depending on the loaded creative.

Even though resize requests occur generally in the ad initialisation steps, it is necessary to be able to satisfy them all along the ad experience.

No action is required if the height constraint of the ad view (and its parent) is set to "wrap_content". The ad View will natively adapt to the requested ratio.

In the other case, it is mandatory to programmatically adapt the size of the Ad container.
The Teads inApp SDK will notify you each resize request coming from the creative.

Use onAdRatioUpdate in addition to onAdReceived to listen to resize updates all along the ad experience.

AdRatio contains all information to calculate the corresponding height for the requested width.
Use calculateHeight to ease the calculation.

We encourage you testing different creative sizes from the test PIDs article.

override fun onAdReceived(inReadAdView: InReadAdView, adRatio: AdRatio) {
    // Get layoutParams from your ad view container
    val containerAdView = binding.containerAdView
    val containerAdViewParams = containerAdView.layoutParams

    // Add the received ad view to your ad container
    containerAdView.addView(inReadAdView)

    // Calculate the height of the ad view container and update the layoutParams
    containerAdViewParams.height = adRatio.calculateHeight(containerAdViewParams.measuredWidth)
    containerAdView.layoutParams = containerAdViewParams
}

override fun onAdRatioUpdate(adRatio: AdRatio) {
    // Get layoutParams from your ad view container
    val containerAdView = binding.containerAdView
    val containerAdViewParams = containerAdView.layoutParams

    // Calculate the height of the ad view container and update the layoutParams
    containerAdViewParams.height = adRatio.calculateHeight(containerAdView.measuredWidth)
    containerAdView.layoutParams = containerAdViewParams
}

Slot monitoring

adOpportunity is a key metrics to evaluate the performance of your inventory.
It builds the visibility score of your placement in publisher dashboards.

The Teads inApp SDK provides a method adOpportunityTrackerView to enable this measurement.

It is mandatory to implement it, a bad visibility measurement will impact your placement fill rate.

override fun adOpportunityTrackerView(trackerView: AdOpportunityTrackerView) {
    binding.containerAdView.addView(trackerView)
}

Event Monitoring

The Teads inApp SDK provides a set of listeners to let you monitor a large scope of events all along ad life cycle. This helps tailor the ad experience in your app, e.g., closing the ad view in case of onAdError, resize the ad view in case of onAdRatioUpdate.

interface InReadAdListener {
    // When an impression has occurred
    fun onAdImpression()
    // When an event click has been fired
    fun onAdClicked()
    // When the ad experience has experienced an issue
    fun onAdError(code: Int, description: String)
    // When the ad has been closed
    fun onAdClosed()
    // This is the entry point of an Ad correctly loaded by Teads
    fun onAdReceived(inReadAdView: InReadAdView, adRatio: AdRatio)
    // When Teads inApp SDK has failed to retrieve an ad
    fun onFailToReceiveAd(failReason: String)
    // This is the monitoring slot tracker view (see Slot Monitoring section below)
    fun adOpportunityTrackerView(trackerView: AdOpportunityTrackerView)
    // When an ad has updated its ratio, you need to update your container view
    fun onAdRatioUpdate(adRatio: AdRatio)
}

Clean

To prevent any performance leak, clean the InReadAdView using inReadAdView.clean() whenever it's needed.
For instance, when the user leaves the page or no ad has to be shown (see the event monitoring section)

inReadAdView.clean()

Brand Safety and web content URL

Having brand safe content will optimize fill rate since advertisers are less keen to have their brand associated with "bad" context (violence/adult etc.).

⚠️ Teads guarantees brand safe contents to advertiser by analysing the overall content of the loaded page. This is an important requirement for advertiser. The Fill Rate of your app could be impacted if BrandSafety analysis is not enabled.

The categorization is done on the fly by a 3rd party partner, Grapeshot.

Brand safe analyze is limited to web content only.
This technical limitation is bypassed inApp using pageSlotUrl to provide the Web equivalent URL of the current article Grapeshot will perform analysis in.
If your application doesn't have a website equivalent, the pageSlotUrl method can be ignored.

AdSettings.Builder()
.pageSlotUrl("https://example.com/my_article_1")
.build()

Check list

✅ Ensure Brand Safety is enabled
✅ Ensure you comply with privacy legal requirements (GDPR/CCPA/GPP)
✅ Comply with app-ads.txt
✅ Enable ad view resizing
✅ Enable slot monitoring for ad opportunities
✅ Clean the ad view when necessary
✅ Test different PIDs with various ad formats and sizes
✅ Enable validation mode to ensure key features are working

Additional settings

Find the full available AdPlacementSettings and AdRequestSettings settings here:

Example:

AdPlacementSettings.Builder()
  // Enable debug logs
  .enableDebug()
  // GDPR
  .userConsent([SUBJECT_TO_GDPR], [CONSENT_STRING], TCFVersion.V2, cmpSdkId)
  .build()

Modified on: Wed, 23 Oct, 2024 at 10:12 AM