InRead - Classic integration

Latest Version: iOS release notes
Sample App: Teads iOS Sample App

This page explains how to integrate a Teads inRead placement into your iOS 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.

Integration
Ad Resizing
Slot monitoring
Event Monitoring
Brand Safety and web content URL
Check list
Additional Settings

Integration

Note

Check out the sample ViewController from our iOS GitHub repository

Check out the framework API documentation

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

See this page for more test PIDs and creative formats.

Add the TeadsInReadAdView to the storyboard:
Make sure Module TeadsSDK is set below Class TeadsInReadAdView
Then create an outlet of the teadsAdView:

step2

Note

If you don't want to use the storyboard you can add the TeadsInReadAdView programmatically as it inherits from UIView.
self.adView = TeadsInReadAdView()

Create a placement

You need to create a placement first using Teads.createInReadPlacement, this placement is linked to your PID.
The same placement will be reused for loading ads

Important

Instance of TeadsInReadAdPlacement must be owned / retained in order to be able to request ads properly

class InReadViewController : UIViewController, TeadsInReadAdPlacementDelegate {

    @IBOutlet weak var teadsAdView: TeadsInReadAdView!
    @IBOutlet weak var teadsAdHeightConstraint: NSLayoutConstraint! // set to 0 in InterfaceBuilder
    var placement: TeadsInReadAdPlacement? //keep a strong reference to placement instance

    override func viewDidLoad() {
        super.viewDidLoad()
        let placementSettings = TeadsAdPlacementSettings { (settings) in
            settings.setUsPrivacy([US_PRIVACY])
            settings.userConsent([SUBJECT_TO_GDPR], [CONSENT_STRING], .v2, sdkId)
        }
        placement = Teads.createInReadPlacement(
            pid: 84242,
            settings: placementSettings,
            delegate: self
        )
    }

    ...
}

Load an Ad

From the placement previously created you requestAd passing TeadsAdRequestSettings

override func viewDidLoad() {
placement?.requestAd(requestSettings: TeadsAdRequestSettings { settings in
    settings.pageUrl("https://example.com/article1")
})

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 flexible 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.

The Teads inApp SDK will notify you each resize request coming from the creative.
The mandatory delegate below will help you to adapt the size of the Ad container.

Use didUpdateRatio in addition to didReceiveAd 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.

func didReceiveAd(ad: TeadsInReadAd, adRatio: TeadsAdRatio) {
    teadsAdView.bind(ad)
    ad.delegate = self
    resizeTeadsAd(adRatio: adRatio)
}

func didUpdateRatio(ad: TeadsInReadAd, adRatio: TeadsAdRatio) {
    resizeTeadsAd(adRatio: adRatio)
}

func resizeTeadsAd(adRatio: TeadsAdRatio) {
    teadsAdHeightConstraint.constant = adRatio.calculateHeight(for: teadsAdView.frame.width)
}

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.

func adOpportunityTrackerView(trackerView: TeadsAdOpportunityTrackerView) {
    teadsAdView.addSubview(trackerView)
}

When using a slotView embedding TeadsInReadAdView you should add TeadsAdOpportunityTrackerView to the slotView.

func adOpportunityTrackerView(trackerView: TeadsAdOpportunityTrackerView) {
    slotView.addSubview(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 didCatchError, resize the ad view in case of didUpdateRatio.

protocol TeadsInReadAdPlacementDelegate {
    // When the Teads inApp SDK has received an ad for you to display
    func didReceiveAd(ad: TeadsInReadAd, adRatio: TeadsAdRatio)
    // When Teads inApp SDK has failed to retrieve an ad
    func didFailToReceiveAd(reason: AdFailReason)
    // This is the monitoring slot tracker view (see Slot Monitoring section below)
    func adOpportunityTrackerView(trackerView: TeadsAdOpportunityTrackerView)
    // When an ad has updated its ratio, you need to update your container view
    func didUpdateRatio(ad: TeadsInReadAd, adRatio: TeadsAdRatio)
}

The SDK provides a delegate to monitor events during the ad life cycle and help you customize the ad experience in your apps.

protocol TeadsAdDelegate {
    // When an impression has occured
    func didRecordImpression(ad: TeadsAd)
    // When an event click has been fired
    func didRecordClick(ad: TeadsAd)
    // When the ad experience has experienced an issue
    func didCatchError(ad: TeadsAd, error: Error)
    // When the ad has been closed
    func didCloseAd(ad: TeadsAd)
    // Wwhen ad wants to present viewController modally e.g: safariViewController (Click to action)
    func willPresentModalView(ad: TeadsAd) -> UIViewController?
}

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 advertisers.
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 pageUrl to provide the Web equivalent URL of the current article Grapeshot will perform analysis in.

TeadsAdPlacementSettings { settings in
    settings.pageUrl("https://example.com/article1")
}

Check list

✅ Ensure Brand Safety is enabled.
✅ Ensure you comply with privacy legal requirements (GDPR/CCPA/GPP)
✅ Enable ad view resizing
✅ Enable slot monitoring for ad opportunities
✅ Clean the ad view when necessary
✅ Test different PIDs for multiple ad format and size testing
✅ Validate your integration with the validation tool to ensure key features are working

Additional Settings

Find the full available TeadsAdPlacementSettings and TeadsAdRequestSettings settings here:

More information on Privacy consent management settings can be found here

TeadsAdPlacementSettings { settings in
  // To enable debug logger for Teads inApp SDK
  settings.enableDebug()
  // This is the CCPA string
  settings.setUsPrivacy([US_PRIVACY])
  // Here is the GDPR informations
  settings.userConsent([SUBJECT_TO_GDPR], [CONSENT_STRING], .V2, sdkId)
}

TeadsAdRequestSettings { settings in
  // this turn on the validation tool to validate your integration
  settings.enableValidationMode()
  // this provide about context your current page for brand safety
  settings.pageUrl([https://example.com/article_1])
}

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