- 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 ModuleTeadsSDK
is set below ClassTeadsInReadAdView
Then create an outlet of the teadsAdView:
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).
- ✅ 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])
}