iOS
The Ezoic Ads SDK for iOS lets you display banner, rewarded, interstitial, native, outstream video, and instream video ads in native iOS apps. The SDK initializes Ezoic configuration, Prebid header bidding, Google Ad Manager, and consent handling from one integration point.
Requirements
- iOS 15.0 or higher (SDK 1.13.0 raised the minimum from iOS 14.0)
- Xcode 26.2 or higher (required by Google Mobile Ads 13; the SDK is built with Xcode 26.6, and Xcode 27 is supported)
- Swift 5.9 or higher
- Google Mobile Ads application ID
Installation
The current SDK version is 1.25.0. The SDK is distributed as pre-built XCFrameworks attached to each GitHub release: EzoicAdsSDK, the consent management platform EzoicCmpSDK it includes, and the consent types library EzoicConsentCore both use. If your app uses another CMP, you can leave Ezoic's out; see Using your own CMP. Install it with Swift Package Manager. Swift Package Manager resolves the Prebid Mobile, Google Mobile Ads and Amazon Publisher Services SDKs as transitive dependencies, so you do not need to add them yourself.
CocoaPods stops getting SDK updates: the CocoaPods trunk becomes read-only on December 2, 2026, and the last version published there before December 1 is the final CocoaPods release. Apps already built with CocoaPods keep working and keep installing that version. To keep getting updates, move to Swift Package Manager.
Upgrading to 1.25.0: no code changes are needed. Rewarded ads no longer need an ad unit identifier: load them with EzoicRewardedAd.load { } or try await EzoicRewardedAd.load(). The old load(adUnitIdentifier:) calls are deprecated but still work the same. Other ad types still need their identifier. See Add a Rewarded Ad.
Upgrading to 1.24.0: one source change to check, if your code uses the CMP's own types next to EzoicAds.
import EzoicAdsSDKno longer makesEzoicCmp,EzoicCmpConfiguration,CmpErrorandCmpLoggeravailable. They are for apps that use the CMP without Ezoic ads; if your code uses them alongsideEzoicAds, addimport EzoicCmpSDK. ThroughEzoicAds, a.failedconsent outcome still always carries anEzoicError.ConsentOutcome,ConsentDecisionTypeandEzoicErrorCodemoved to a new module,EzoicConsentCore, whichimport EzoicAdsSDKstill makes available. Unqualified names compile unchanged; a module-qualified name such asEzoicCmpSDK.ConsentOutcomebecomesEzoicConsentCore.ConsentOutcome.- If your app uses another CMP, you can now leave the built-in CMP out with the new
EzoicAdsSDKWithoutCMPproduct; see Using your own CMP. By default nothing changes:EzoicAdsSDKincludes the CMP and it is on. - New
EzoicAds.isBuiltInCmpIncludedtells you whether the built-in CMP is linked into the app.
Upgrading to 1.23.2: no code changes are needed. The SDK now closes an interstitial that Google renders once it has been on screen for about 20 seconds without being dismissed, and interstitialAdDidDismiss fires as usual. Google decides when its close button appears, and some video ads withhold it for a long time. Rewarded ads are never closed this way. See Add an Interstitial Ad.
Upgrading to 1.23.1: no code changes are needed. loadAd() without a size now picks 728x90, 468x60 or 320x50 by the width the banner has (its own width, its superview's safe-area width and its window's width), not the screen width. Before, every banner on an iPad or a landscape iPhone asked for 728x90, which was clipped in a narrower spot and never counted as viewable. EzoicBannerSize.adaptiveSize still compiles but is deprecated; use EzoicBannerSize.adaptiveSize(forAvailableWidth:).
Upgrading to 1.23.0: no code changes are needed. Banners that let the SDK pick their slot number no longer get slot 20 (or 40, 60, …), which Ezoic serves as the bottom anchor placement; the 20th banner on a screen gets slot 21. A banner you pin with slotNumber = 20 keeps it.
Upgrading to 1.22.0: two source changes to check, if your code uses the consent types:
ConsentOutcome.failednow carries anErrorinstead of anEzoicError. ThroughEzoicAdsit is still anEzoicErrorat runtime, butcase .failed(let error): error.codeno longer compiles; read the code with(error as? EzoicErrorCode)?.code. See Consent management (CMP).ConsentOutcomeandConsentDecisionTypenow live in the consent module.import EzoicAdsSDKstill makes them available under the same names, but module-qualified names such asEzoicAdsSDK.ConsentOutcomeno longer compile; drop the prefix.
Also new, with no app changes needed:
- In the US states with consumer privacy laws, the built-in CMP now shows a privacy notice with a "Do Not Sell My Information" choice and writes the state's IAB GPP keys. Ads never wait for it. See US-state privacy.
presentConsentSettingsopens the US privacy settings in those states, so your existing "Privacy settings" button works for US users. NewisPrivacyOptionsRequiredtells you when to show it.- The
EzoicAdsSDKSwift package product brings in the consent library for you. Apps that don't use Ezoic ads can add theEzoicCmpSDKproduct on its own; see Consent management (CMP). - New
appPaidandsetAppContent(language:genre:)describe your app to bidders. See App details for bidders. - 1.22.0 is available through Swift Package Manager only.
Upgrading to 1.21.0: remove refreshIntervalSeconds and refreshMaxCount if you set them. Banners now refresh automatically every 30 seconds, or at the interval Ezoic sets for the ad unit, and those properties are deprecated and ignored (see Banner refresh). With debugEnabled = true, initialize now logs a warning when your Info.plist has no SKAdNetworkItems, is missing Google's or InMobi's identifier, or lists identifiers with uppercase letters, which Apple ignores (see SKAdNetwork identifiers). 1.21.0 is available through Swift Package Manager only.
Upgrading to 1.20.0: no code changes are needed. The SDK now gets Prebid Mobile from https://github.com/prebid/prebid-mobile-ios-sdk and Amazon Publisher Services 5.6.6 from Amazon's https://github.com/amzn/swift-package-manager-amazon-aps. If your app also adds Prebid Mobile or Amazon Publisher Services with Swift Package Manager, use those package URLs (Amazon at exactly 5.6.6); with the older prebid-mobile-ios or adsbynimbus/swift-package-aps packages, Xcode reports packages with conflicting target names. With CocoaPods, an app that pins the AmazonPublisherServicesSDK pod must allow 5.6.6, and an existing install upgrades with pod update EzoicAdsSDK AmazonPublisherServicesSDK.
Upgrading to 1.19.2: no app changes are needed. Bid requests now include your app's App Store ID alongside your SKAdNetworkItems identifiers, so buyers can use SKAdNetwork attribution (see SKAdNetwork identifiers).
Upgrading to 1.19.1: no app changes are needed. Consent set with setGDPRConsent or setGPPConsent is now written to the standard IAB keys in UserDefaults (IABTCF_gdprApplies, IABTCF_TCString, IABGPP_HDR_GppString, IABGPP_GppSID), so Google Mobile Ads, IMA and Amazon see it, including when set before initialize. clearManualConsent() restores the values your consent platform had stored.
Upgrading to 1.19.0: no app changes are needed.
- An interstitial now stays alive while it's on screen, even if your app drops its reference after
show(from:). Before, the dismiss callback and the ad's reporting could be lost. setSubjectToCOPPA(true)now also tags Google Ad Manager requests as child-directed, addstfcd=1to instream video tags, and skips Amazon bids.- The device ID the SDK sends is kept only while storage consent allows it.
- Calling
initializeagain now reports success instead ofalreadyInitialized. - Ad requests no longer wait 2 seconds for a pageview when none is pending.
Upgrading to 1.18.0: no app changes are needed. New EzoicNativeAdTemplateView is a ready-made native ad layout you can restyle with EzoicNativeAdStyle; see Use the ready-made template. Rewarded ads also report an outcome for every load.
Upgrading to 1.17.0: if you show native ads, call ad.registerView(adView) with the view that displays the ad (see Add a Native Ad); without it native ads are not reported as viewed. No other app changes are needed. Ad measurement now matches Ezoic's web reporting more closely: viewed impressions for every format, an outcome for every ad opportunity including no-fills, and revenue and floor values reported the same way as on the web. Automatic pageviews now count only your app's own view controllers, so full-screen ads, alerts and system screens no longer book a pageview. If you label your launch screen, see Labeling screens.
Upgrading to 1.16.0: no app changes are needed. Banners can now refresh when Ezoic enables it for the ad unit (see Banner refresh).
Upgrading to 1.15.0: the SDK now uses Google Mobile Ads 13. If your app pins Google Mobile Ads 12 in Swift Package Manager or CocoaPods, raise that pin to 13.
Swift Package Manager
In Xcode, go to File > Add Package Dependencies and enter:
https://github.com/ezoic/ezoic-swift-sdk-dist.git
Select Up to Next Major Version starting at 1.25.0, or select Exact Version if you want every SDK update to be intentional.
Or add the package to Package.swift:
dependencies: [
.package(url: "https://github.com/ezoic/ezoic-swift-sdk-dist.git", from: "1.25.0")
]
Then add the EzoicAdsSDK product to your app target and write import EzoicAdsSDK.
CocoaPods (no further updates)
The CocoaPods trunk becomes read-only on December 2, 2026. Versions already on the trunk keep installing, but no SDK versions are published to CocoaPods after the last one pushed before December 1, 2026. Use Swift Package Manager for new apps.
Add the pod to your Podfile, then run pod install:
pod 'EzoicAdsSDK', '~> 1.19'
With CocoaPods the SDK module is named EzoicAdsSDKBinary, so write import EzoicAdsSDKBinary where the examples on this page use import EzoicAdsSDK.
The trunk's last version is 1.19.1, so the line above installs 1.19.1. To install 1.20.0, point the pod at its podspec instead:
pod 'EzoicAdsSDK', :podspec => 'https://raw.githubusercontent.com/ezoic/ezoic-swift-sdk-dist/1.20.0/EzoicAdsSDK.podspec'
1.21.0 and later are available through Swift Package Manager only.
Move from CocoaPods to Swift Package Manager
- Remove
pod 'EzoicAdsSDK'from yourPodfileand runpod install. Also removePrebidMobile,Google-Mobile-Ads-SDKandAmazonPublisherServicesSDKif nothing else in the app needs them as pods. - Add
https://github.com/ezoic/ezoic-swift-sdk-dist.gitwith File > Add Package Dependencies as shown above, and add theEzoicAdsSDKproduct to your app target. - Change
import EzoicAdsSDKBinarytoimport EzoicAdsSDK. - If another SDK in your app still pulls in Prebid Mobile, Google Mobile Ads or Amazon Publisher Services through CocoaPods, move it to Swift Package Manager too, so each SDK is linked once.
Initialize the SDK
Initialize the SDK in your AppDelegate or app startup flow before loading ads.
import EzoicAdsSDK
let config = EzoicConfiguration(
domain: "example.com",
debugEnabled: false,
testMode: false
)
EzoicAds.shared.initialize(with: config) { result in
switch result {
case .success:
print("Ezoic SDK initialized")
case .failure(let error):
print("Ezoic initialization failed: \(error)")
}
}
domain must match the domain configured for your site in Ezoic. Authentication is handled by the app's bundle identifier and the configured domain — there is no client-side API key.
For apps using async/await:
try await EzoicAds.shared.initialize(with: config)
App details for bidders
SDK 1.22.0 and later can send two optional details about your app to bidders: whether it is a paid app (OpenRTB app.paid), and its content language and genre (app.content). Nothing is sent for a value you don't set.
let config = EzoicConfiguration(
domain: "example.com",
appPaid: false // true for a paid app, false for a free one
)
// Any time, before or after initialize. Every later ad request carries it.
EzoicAds.shared.setAppContent(language: "en", genre: "News")
EzoicAds.shared.setAppContent(language: nil, genre: nil) // clears it
language is an ISO-639-1 two-letter code such as "en" or "de"; case is ignored. Any other value is dropped, with a warning in the debug log. genre is free text. A nil or blank value is left out.
The SDK sends these through Prebid Mobile's global ORTB config. Setting either one replaces any global ORTB config your app set with Targeting.shared.setGlobalORTBConfig, so set these fields with appPaid and setAppContent instead.
Add a Banner Ad
Create an EzoicBannerView, add it to your view hierarchy, and call loadAd() after the SDK is initialized.
import EzoicAdsSDK
import UIKit
class ViewController: UIViewController {
private var bannerView: EzoicBannerView?
override func viewDidLoad() {
super.viewDidLoad()
let adView = EzoicBannerView(adUnitIdentifier: 12345)
adView.delegate = self
adView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(adView)
NSLayoutConstraint.activate([
adView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
adView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
adView.widthAnchor.constraint(equalToConstant: EzoicBannerSize.banner.width)
])
bannerView = adView
adView.loadAd()
}
}
extension ViewController: EzoicBannerViewDelegate {
func bannerViewDidLoad(_ bannerView: EzoicBannerView) {
print("Banner loaded")
}
func bannerView(_ bannerView: EzoicBannerView, didFailToLoadWithError error: EzoicError) {
print("Banner failed: \(error)")
}
func bannerView(_ bannerView: EzoicBannerView, didChangeSize size: CGSize) {
print("Banner size: \(Int(size.width))x\(Int(size.height))")
}
}
Replace 12345 with your numeric Ezoic ad unit identifier. The SDK fetches the Google Ad Manager ad unit, Prebid configuration, supported sizes, targeting values, and refresh interval from Ezoic servers. Height comes from the view's intrinsic content size — do not pin a fixed height constraint, or collapse will not take effect.
The delegate also reports bannerViewDidRecordImpression, bannerViewDidRecordClick, bannerViewWillPresentScreen, bannerViewDidDismissScreen, and bannerView(_:didChangeSize:) — all optional.
Banner refresh
Banners refresh automatically every 30 seconds, or at the interval Ezoic sets for the ad unit. You do not set a refresh timer in your app: refreshIntervalSeconds and refreshMaxCount are deprecated and ignored, so remove them if you set them. Older SDK versions still apply them, which overrides Ezoic's interval.
The countdown only runs while at least half of the banner is on screen and visible and your app is in the foreground; it pauses otherwise. If your Google Ad Manager ad unit has its own auto-refresh turned on, turn it off so the banner is not refreshed twice.
Unfilled ads
When no ad fills, EzoicBannerView collapses to zero height so it does not leave a blank gap. This is controlled by collapseOnNoFill (default true). If a refresh does not fill, the previous ad stays visible. bannerView(_:didChangeSize:) reports the displayed size, or .zero when the view collapses.
Banner Sizes
You can load ads with an adaptive default size, a typed size, one size string, or a list of size strings.
adView.loadAd()
adView.loadAd(size: EzoicBannerSize.mediumRectangle)
adView.loadAd(size: "300x250")
adView.loadAd(sizes: ["300x250", "320x50"])
Common sizes include:
EzoicBannerSize.banner: 320x50EzoicBannerSize.largeBanner: 320x100EzoicBannerSize.mediumRectangle: 300x250EzoicBannerSize.fullBanner: 468x60EzoicBannerSize.leaderboard: 728x90EzoicBannerSize.custom(width:height:): custom dimensions
loadAd() without a size picks the largest standard banner that fits the banner's width. To pick it yourself for a given width:
let size = EzoicBannerSize.adaptiveSize(forAvailableWidth: view.bounds.width)
Add a Rewarded Ad
Rewarded ads are full-screen ads that grant an in-app reward when the user finishes watching. They use a load-then-show lifecycle: load the ad ahead of time (for example, at the start of a level), then present it at a natural break and grant the reward when it is earned.
import EzoicAdsSDK
var rewardedAd: EzoicRewardedAd?
func loadRewardedAd() {
EzoicRewardedAd.load { [weak self] result in
switch result {
case .success(let ad):
self?.rewardedAd = ad
ad.delegate = self
case .failure(let error):
print("Rewarded load failed: \(error.localizedDescription)")
}
}
}
func showRewardedAd() {
rewardedAd?.show(from: self) { reward in
print("Earned \(reward.amount) \(reward.type)")
grantReward(reward.amount)
}
}
async/await is also supported:
rewardedAd = try await EzoicRewardedAd.load()
Rewarded ads don't need an ad unit identifier. From SDK 1.25.0, the load(adUnitIdentifier:) calls that take a number are deprecated: they still compile and work the same, and you can remove the number when you next update your app. Call show(from:) only after the ad has loaded; showing before the load completes (or after the ad was already shown) reports EzoicError.adNotReady. If you pass nil (or omit from:), the SDK presents from the app's top view controller. Rewarded ads are single-use — load a new ad for each opportunity.
You can pass a reward name when you show the ad. The name appears in your reports.
rewardedAd?.show(from: self, rewardName: "extra life") { reward in
grantReward(reward.amount)
}
Lifecycle events are delivered through EzoicRewardedAdDelegate. The reward type and amount come from the reward configured on the Google Ad Manager rewarded ad unit.
extension ViewController: EzoicRewardedAdDelegate {
func rewardedAd(_ rewardedAd: EzoicRewardedAd, userDidEarn reward: EzoicReward) {
grantReward(reward.amount)
}
func rewardedAdDidDismiss(_ rewardedAd: EzoicRewardedAd) {
print("Rewarded ad closed")
}
}
The delegate also reports rewardedAdDidPresent, rewardedAd(_:didFailToPresentWithError:), rewardedAdDidRecordImpression, and rewardedAdDidRecordClick. All delegate methods are optional.
Add an Interstitial Ad
Interstitial ads are full-screen ads shown at natural transition points (for example, between levels or screens). Unlike rewarded ads, they grant no reward. They use the same load-then-show lifecycle: load the ad ahead of time, then present it at a natural break.
import EzoicAdsSDK
var interstitialAd: EzoicInterstitialAd?
func loadInterstitialAd() {
EzoicInterstitialAd.load(adUnitIdentifier: 12345) { [weak self] result in
switch result {
case .success(let ad):
self?.interstitialAd = ad
ad.delegate = self
case .failure(let error):
print("Interstitial load failed: \(error.localizedDescription)")
}
}
}
func showInterstitialAd() {
interstitialAd?.show(from: self)
}
async/await is also supported:
interstitialAd = try await EzoicInterstitialAd.load(adUnitIdentifier: 12345)
Replace 12345 with your numeric Ezoic ad unit identifier. Call show(from:) only after the ad has loaded; showing before the load completes (or after the ad was already shown) reports EzoicError.adNotReady. If you pass nil (or omit from:), the SDK presents from the app's top view controller. Interstitial ads are single-use — load a new ad for each opportunity.
Lifecycle events are delivered through EzoicInterstitialAdDelegate.
extension ViewController: EzoicInterstitialAdDelegate {
func interstitialAdDidDismiss(_ interstitialAd: EzoicInterstitialAd) {
print("Interstitial ad closed")
}
}
The delegate also reports interstitialAdDidPresent, interstitialAd(_:didFailToPresentWithError:), and interstitialAdDidRecordImpression/interstitialAdDidRecordClick. All delegate methods are optional.
From SDK 1.23.2, the SDK closes an interstitial that Google renders once it has been on screen for about 20 seconds without being dismissed, and interstitialAdDidDismiss fires as usual. Time the ad spends covered (a store page, a browser, your app in the background) does not count, and rewarded ads are never closed this way.
Add an Outstream Video Ad
Outstream video ads render inline in your own view hierarchy, like a banner, but with a video creative in an SDK-built player. Create an EzoicOutstreamAdView, set its delegate, add it to your view hierarchy, and call loadAd().
import EzoicAdsSDK
var outstreamAd: EzoicOutstreamAdView?
func loadOutstreamAd() {
let adView = EzoicOutstreamAdView(adUnitIdentifier: 12345)
adView.delegate = self
adContainer.addSubview(adView)
outstreamAd = adView
adView.loadAd()
}
Replace 12345 with your numeric Ezoic ad unit identifier. Set delegate before calling loadAd() so the load callback isn't missed. Unlike EzoicBannerView, loadAd() takes no size — the SDK renders at the size configured on the server (640×360 by default). Call destroy() when the hosting view is torn down (e.g. in deinit, or when a cell is recycled) so the underlying ad is released.
Lifecycle events are delivered through EzoicOutstreamAdViewDelegate.
extension ViewController: EzoicOutstreamAdViewDelegate {
func outstreamViewDidLoad(_ outstreamView: EzoicOutstreamAdView) {
print("Outstream ad loaded")
}
func outstreamView(_ outstreamView: EzoicOutstreamAdView, didFailToLoadWithError error: EzoicError) {
print("Outstream failed: \(error.localizedDescription)")
}
}
The delegate also reports outstreamViewDidRecordImpression, outstreamViewDidRecordClick, outstreamViewWillPresentScreen, outstreamViewDidDismissScreen, and outstreamView(_:didChangeSize:) — all optional. EzoicOutstreamAdView collapses on no-fill the same way as EzoicBannerView (collapseOnNoFill, default true).
Add an Instream Video Ad
Instream video ads play inside your own video content. Your app owns the video player and the Google IMA SDK; the Ezoic SDK's job is to build the Google Ad Manager VAST ad-tag URL you hand to IMA. There is no Ezoic view — the deliverable is a URL string, so you retain the EzoicInstreamAd instance yourself. EzoicInstreamAd is a view-less, multi-use controller: unlike rewarded and interstitial ads it is not single-use, so keep the instance and call load(contentUrl:delegate:) again for the next video.
import EzoicAdsSDK
import GoogleInteractiveMediaAds
let instreamAd = EzoicInstreamAd(adUnitId: 12345)
func loadInstreamAd() {
instreamAd.load(contentUrl: playingVideoUrl, delegate: self)
}
Tag delivery and failures arrive through EzoicInstreamAdDelegate:
extension ViewController: EzoicInstreamAdDelegate {
func instreamAd(_ instreamAd: EzoicInstreamAd, didReceiveAdTag adTagUrl: String) {
// Feed the tag to your own IMA ads request.
let request = IMAAdsRequest(
adTagUrl: adTagUrl,
adDisplayContainer: adDisplayContainer,
contentPlayhead: contentPlayhead,
userContext: nil
)
adsLoader.requestAds(with: request)
}
func instreamAd(_ instreamAd: EzoicInstreamAd, didFailToLoadWithError error: EzoicError) {
print("Instream load failed: \(error.localizedDescription)")
// Play content without a preroll.
}
}
Replace 12345 with your numeric Ezoic ad unit identifier. contentUrl (the URL of the video being played) is optional and, when supplied, is added to the ad tag for contextual targeting. On an IMA ad error, call getNextAdTagUrl() to retry the next floor in the waterfall — it returns nil once exhausted. On the IMA STARTED event, call reportImpression() (optionally passing a revenueUsd value) to record the Ezoic impression. Call destroy() when the player is torn down (e.g. in deinit) to cancel any in-flight request; the controller is otherwise reusable across loads.
Add a Native Ad
Native ads deliver ad assets (headline, image, body text, call to action) that you render inside your own view hierarchy instead of a fixed banner or full-screen format, so the ad matches the look and feel of your content.
import EzoicAdsSDK
import GoogleMobileAds
var nativeAd: EzoicNativeAd?
func loadNativeAd() {
EzoicNativeAd.load(adUnitIdentifier: 12345) { [weak self] result in
switch result {
case .success(let ad):
self?.nativeAd = ad
ad.delegate = self
guard let gmaAd = ad.nativeAd else { return }
// Build a NativeAdView, populate its asset views, then attach the ad.
let adView = NativeAdView()
let headline = UILabel()
headline.text = gmaAd.headline
adView.headlineView = headline
adView.addSubview(headline)
adView.nativeAd = gmaAd
// Lets the SDK report the ad as viewed (half on screen for one second).
ad.registerView(adView)
self?.adContainer.addSubview(adView)
case .failure(let error):
print("Native load failed: \(error.localizedDescription)")
}
}
}
async/await is also supported:
nativeAd = try await EzoicNativeAd.load(adUnitIdentifier: 12345)
Replace 12345 with your numeric Ezoic ad unit identifier. The SDK returns the underlying Google Mobile Ads NativeAd on ad.nativeAd; populate a NativeAdView with your own styling and assign the ad to its nativeAd property.
Then call ad.registerView(adView) with the view that shows the ad (SDK 1.17.0 and later). The SDK uses it to measure viewability: the ad is reported as viewed once at least half of it has been on screen for one continuous second. A native ad whose view is never registered is not reported as viewed.
Use the ready-made template
SDK 1.18.0 and later include EzoicNativeAdTemplateView, a complete native ad layout: an "Ad" badge, icon, headline, advertiser, media, body text and a call-to-action button. Restyle it with EzoicNativeAdStyle so it matches your app. The template fills in every asset and calls registerView for you.
import EzoicAdsSDK
let template = EzoicNativeAdTemplateView()
template.style = EzoicNativeAdStyle(
backgroundColor: UIColor(red: 0.12, green: 0.12, blue: 0.18, alpha: 1),
cornerRadius: 16,
headlineTextColor: .white,
bodyTextColor: UIColor(red: 0.80, green: 0.84, blue: 0.96, alpha: 1),
callToActionBackgroundColor: UIColor(red: 0.54, green: 0.71, blue: 0.98, alpha: 1),
callToActionTextColor: UIColor(red: 0.12, green: 0.12, blue: 0.18, alpha: 1),
callToActionCornerRadius: 22,
adLabelText: "Sponsored"
)
adContainer.addSubview(template)
// Pin the template to the container with Auto Layout; it sizes itself vertically.
EzoicNativeAd.load(adUnitIdentifier: 12345) { [weak self] result in
if case .success(let ad) = result {
self?.nativeAd = ad
template.nativeAd = ad
}
}
Every parameter is optional. Leave a color out (nil) to use the system default, which follows light and dark appearance. Sizes are in points. Assigning a new style redraws the ad in place without reloading it. EzoicNativeAdStyle(dictionary:) accepts the same keys, with colors as CSS hex strings such as "#1E1E2E" or ARGB numbers.
| Property | Default | Notes |
|---|---|---|
backgroundColor |
none (transparent) | Card background |
cornerRadius |
0 |
Card corners; content is clipped to them |
padding |
8 |
Inner padding |
headlineTextColor, headlineTextSize |
theme, 16 |
The headline is bold |
advertiserTextColor, advertiserTextSize |
theme, 12 |
|
bodyTextColor, bodyTextSize |
theme, 14 |
|
callToActionBackgroundColor, callToActionTextColor |
platform button | |
callToActionTextSize, callToActionCornerRadius |
14, 4 |
The radius applies when a background color is set |
mediaHeight |
175 |
At least 120, which Google requires for native media |
adLabelText |
"Ad" |
The ad attribution badge; a blank value falls back to "Ad" |
adLabelTextColor, adLabelBackgroundColor |
#202124, #FBBC04 |
Build your own layout
For full control over the layout, draw the ad yourself: the layout, fonts, colors, spacing, and light and dark appearance are whatever you build in your NativeAdView. Style it like any other view in your app, in code or in a XIB.
A complete layout built in code:
import GoogleMobileAds
import UIKit
func makeNativeAdView(for gmaAd: NativeAd) -> NativeAdView {
let adView = NativeAdView()
let attribution = UILabel()
attribution.text = " Ad "
attribution.font = .boldSystemFont(ofSize: 12)
attribution.textColor = .white
attribution.backgroundColor = .systemOrange
let headline = UILabel()
headline.text = gmaAd.headline
headline.font = .boldSystemFont(ofSize: 16)
headline.numberOfLines = 0
adView.headlineView = headline
let advertiser = UILabel()
advertiser.text = gmaAd.advertiser
advertiser.font = .systemFont(ofSize: 12)
advertiser.textColor = .secondaryLabel
advertiser.isHidden = gmaAd.advertiser == nil
adView.advertiserView = gmaAd.advertiser == nil ? nil : advertiser
let icon = UIImageView(image: gmaAd.icon?.image)
icon.isHidden = gmaAd.icon == nil
icon.widthAnchor.constraint(equalToConstant: 40).isActive = true
icon.heightAnchor.constraint(equalToConstant: 40).isActive = true
adView.iconView = gmaAd.icon == nil ? nil : icon
let media = MediaView()
media.mediaContent = gmaAd.mediaContent
media.heightAnchor.constraint(equalToConstant: 180).isActive = true
adView.mediaView = media
let body = UILabel()
body.text = gmaAd.body
body.font = .systemFont(ofSize: 14)
body.numberOfLines = 0
body.isHidden = gmaAd.body == nil
adView.bodyView = gmaAd.body == nil ? nil : body
let cta = UIButton(type: .system)
cta.setTitle(gmaAd.callToAction, for: .normal)
// The NativeAdView handles the tap, so the button must not.
cta.isUserInteractionEnabled = false
cta.isHidden = gmaAd.callToAction == nil
adView.callToActionView = gmaAd.callToAction == nil ? nil : cta
let titles = UIStackView(arrangedSubviews: [headline, advertiser])
titles.axis = .vertical
let header = UIStackView(arrangedSubviews: [icon, titles])
header.spacing = 8
header.alignment = .top
let stack = UIStackView(arrangedSubviews: [attribution, header, media, body, cta])
stack.axis = .vertical
stack.spacing = 8
stack.alignment = .fill
stack.setCustomSpacing(4, after: attribution)
attribution.setContentHuggingPriority(.required, for: .horizontal)
stack.translatesAutoresizingMaskIntoConstraints = false
adView.addSubview(stack)
NSLayoutConstraint.activate([
stack.topAnchor.constraint(equalTo: adView.topAnchor, constant: 12),
stack.leadingAnchor.constraint(equalTo: adView.leadingAnchor, constant: 12),
stack.trailingAnchor.constraint(equalTo: adView.trailingAnchor, constant: -12),
stack.bottomAnchor.constraint(equalTo: adView.bottomAnchor, constant: -12),
])
// Assign last, after every asset view is set.
adView.nativeAd = gmaAd
return adView
}
Any asset other than the headline can be missing, so hide the view for a missing asset and leave its property nil, as above.
Each ad asset comes from a NativeAd property and is shown in the view you assign to the matching NativeAdView property:
| Asset | NativeAd property |
NativeAdView property |
View |
|---|---|---|---|
| Headline | headline |
headlineView |
UILabel |
| Main image or video | mediaContent |
mediaView |
MediaView |
| Body text | body |
bodyView |
UILabel |
| Call to action | callToAction |
callToActionView |
UIButton |
| Icon | icon |
iconView |
UIImageView |
| Advertiser | advertiser |
advertiserView |
UILabel |
| Star rating | starRating |
starRatingView |
your own view |
| Store | store |
storeView |
UILabel |
| Price | price |
priceView |
UILabel |
Google requires the following of every native ad layout:
- Label the ad. Show an ad attribution such as "Ad" or "Sponsored", like the badge at the top of the layout above.
- Keep assets inside the ad view. Every asset view must sit inside the
NativeAdView, and each one you show must be assigned to its property. Unassigned views don't respond to taps. - Show the media in a
MediaView. Give it at least 120x120 points so images and video display. - Leave the AdChoices icon visible. Google Mobile Ads adds it to a corner of the
NativeAdView; don't cover it. - Let the ad view take the call-to-action tap. Set
isUserInteractionEnabled = falseon the call-to-action button, as above.
For SwiftUI, wrap the NativeAdView in a UIViewRepresentable.
NativeAdView. Clear any issues it lists before you release. Google's native ads guide for Ad Manager covers the layout rules in full.
Call destroy() when the hosting view is torn down (for example in deinit, or when a table or collection view cell is recycled) so the underlying ad is released.
Lifecycle events are delivered through EzoicNativeAdDelegate. All delegate methods are optional.
extension ViewController: EzoicNativeAdDelegate {
func nativeAdDidRecordImpression(_ nativeAd: EzoicNativeAd) {
print("Native ad impression")
}
func nativeAdDidRecordClick(_ nativeAd: EzoicNativeAd) {
print("Native ad clicked")
}
}
The delegate also reports nativeAdWillPresentScreen and nativeAdDidDismissScreen, which fire when a click opens and closes an overlay such as the ad's destination.
Required App Setup for Ads to Serve
A few configuration steps live in your app project and on your website, not in the SDK. Apple and Google require them, and they directly affect whether — and how well — ads fill. The SDK cannot add them for you (see What the SDK does vs. what you must add), so complete all of the following before testing fill.
1. Google Mobile Ads application ID
Add your Google Mobile Ads application ID to Info.plist. This ID is provided by Ezoic and can be found in your Ezoic dashboard. Use the value assigned to your app unless your Ezoic representative gives you a different one. Also set GADIsAdManagerApp so Google Mobile Ads runs in Ad Manager mode.
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX</string>
<key>GADIsAdManagerApp</key>
<true/>
Without a valid GADApplicationIdentifier, the Google Mobile Ads SDK will not initialize and no ads will serve.
2. App Tracking Transparency (ATT)
ATT has the single biggest impact on fill and CPM. Without it, the IDFA is unavailable (all zeros) and a large share of programmatic demand will not bid or will bid much lower.
Add the tracking usage description to Info.plist. Apple requires this string to live in the app's Info.plist — it cannot be supplied by the SDK because it is shown in the App Store privacy label and the system prompt.
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>
The SDK presents the ATT prompt for you. During initialize, when the status is still undetermined, the SDK shows the prompt and waits for the user's decision before starting the ad stack, so the IDFA (if granted) is attached to the first ad request. You only need to supply the NSUserTrackingUsageDescription string above — no extra code.
// The SDK requests ATT (if undetermined) before loading ads.
EzoicAds.shared.initialize(with: config) { _ in
// SDK ready — banners can load with the IDFA available.
}
If you prefer to drive the ATT flow yourself (for example, to show a pre-prompt or to control its timing), set requestATTBeforeAds: false on EzoicConfiguration and request authorization before initializing the SDK so the IDFA is available on the first ad request:
import AppTrackingTransparency
let config = EzoicConfiguration(domain: "example.com", requestATTBeforeAds: false)
ATTrackingManager.requestTrackingAuthorization { _ in
EzoicAds.shared.initialize(with: config) { _ in }
}
3. SKAdNetwork identifiers
SKAdNetworkItems lets buyers attribute installs when the IDFA is unavailable; missing identifiers suppress demand from buyers that require SKAdNetwork. Apple reads this key only from the app's main Info.plist — it is not aggregated from frameworks or SDKs, so it must be added to your app even though the SDK depends on Google Mobile Ads.
Your inventory is sold through Google Ad Manager, Amazon Publisher Services and Prebid buyers such as InMobi, Magnite, PubMatic and Index Exchange. Google's list only covers buyers that bid through Google, so Ezoic publishes a combined list at https://docs.ezoic.com/skadnetworkids.xml. It contains Google's published identifiers plus the lists published by InMobi, PubMatic, Magnite, Index Exchange, Equativ, Smaato, Yieldmo, Ogury, TripleLift and Amazon Publisher Services, lowercased and deduplicated.
To add it, run this from the folder that contains your Info.plist. It adds only the identifiers you don't have yet, keeps the ones you already list, and is safe to re-run:
curl -fsSL https://docs.ezoic.com/skadnetworkids.xml -o skadnetworkids.xml
plutil -extract SKAdNetworkItems raw Info.plist >/dev/null 2>&1 || plutil -insert SKAdNetworkItems -array Info.plist
for id in $(grep -o '[a-z0-9]*\.skadnetwork' skadnetworkids.xml); do
grep -q "<string>$id</string>" Info.plist ||
plutil -insert SKAdNetworkItems -xml "<dict><key>SKAdNetworkIdentifier</key><string>$id</string></dict>" -append Info.plist
done
Or copy the SKAdNetworkItems array from the file into Info.plist by hand. Either way the result has this shape:
<key>SKAdNetworkItems</key>
<array>
<dict>
<key>SKAdNetworkIdentifier</key>
<string>cstr6suwn9.skadnetwork</string>
</dict>
<!-- … one dict per identifier in skadnetworkids.xml … -->
</array>
Identifiers must be lowercase. The list grows as buyers register with Apple, so refresh it when you ship a new app version. If you add mediation partners or other ad SDKs, also include any identifiers those partners require.
From SDK 1.19.2, bid requests also carry your app's App Store ID, which buyers need before they use these identifiers. The SDK takes it from the App Store URL registered for your app with Ezoic, so there is nothing to configure; an app without a registered App Store URL is sent without SKAdNetwork attribution.
4. app-ads.txt on your website
Host an app-ads.txt file at the root of the developer/website domain listed on your app's App Store page (for example, https://example.com/app-ads.txt). It authorizes the buyers and exchanges that may sell your inventory; a missing or incomplete file causes most programmatic demand to be filtered out. Ezoic provides the required entries — confirm the file is published and current. See app-ads.txt setup to redirect it to Ezoic or update it automatically.
What the SDK does vs. what you must add
| Item | Provided automatically by the SDK | You must add |
|---|---|---|
| Google Mobile Ads + Prebid SDKs | Yes (transitive dependencies) | — |
| Ad unit, sizes, targeting, Prebid config | Yes (fetched from Ezoic) | — |
GADApplicationIdentifier / GADIsAdManagerApp |
No (per-app value) | Yes, in Info.plist |
| ATT prompt (request + wait before ads) | Yes (SDK presents it during initialize) |
— |
NSUserTrackingUsageDescription string |
No (App Store privacy requirement) | Yes, in Info.plist |
SKAdNetworkItems |
No (Apple reads app Info.plist only) |
Yes, in Info.plist |
app-ads.txt |
No (hosted on your domain) | Yes, on your website |
Apple and Google deliberately require these to live in the app bundle or on the publisher domain, so they cannot be bundled inside the SDK. Keep them in mind whenever you ship a new app.
Privacy and Consent
Built-in consent dialog
Starting with SDK 1.13.0, the SDK includes an IAB TCF 2.4 consent management platform (CMP ID 299). It acts for users in GDPR regions and, from SDK 1.22.0, for users in the US states with consumer privacy laws (see US-state privacy). Elsewhere nothing is shown and ads load as before. Consent management (CMP) covers the CMP on every platform, including how to use it in an app without Ezoic ads.
The dialog is used only when both of these are true:
- Ezoic has enabled the consent dialog for your domain. This is a server-side setting.
cmpEnabledistrueinEzoicConfiguration. This is the default.
cmpEnabled: false. See Using your own CMP.
Call presentConsentIfRequired once per process from your first view controller's viewDidAppear, right after EzoicAds.shared.initialize. It is safe to call before initialization finishes: it waits for the init response. Calling it again is harmless: you get .alreadyPresenting while a dialog is in flight and .alreadyDecided once a valid decision is stored.
You must also add a "Privacy choices" button or menu item that calls presentConsentSettings. TCF policy requires users to be able to reopen the dialog and withdraw consent at any time, and users in covered US states need a way to opt out. Show it unless isPrivacyOptionsRequired is false.
import EzoicAdsSDK
private static var consentRequested = false // once per process
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
guard !Self.consentRequested else { return }
Self.consentRequested = true
EzoicAds.shared.presentConsentIfRequired(from: self) { outcome in
switch outcome {
case .decided(let decision):
print("User chose \(decision)")
case .failed(let error):
print("Consent UI failed: \(error.localizedDescription)")
default:
break // .notRequired, .alreadyDecided, .dismissed, .alreadyPresenting
}
}
}
// "Privacy choices" entry point (required): the TCF dialog with the user's stored
// choices in GDPR regions, the US privacy settings in a covered US state
override func viewWillAppear(_ animated: Bool) {
super.viewWillAppear(animated)
privacyButton.isHidden = EzoicAds.shared.isPrivacyOptionsRequired == false
}
@objc func privacySettingsTapped() {
EzoicAds.shared.presentConsentSettings(from: self) { outcome in /* ... */ }
}
isPrivacyOptionsRequired is nil until the SDK has loaded your settings, so read it again when the screen with the entry point appears, as in viewWillAppear above.
async/await is also supported:
let outcome = await EzoicAds.shared.presentConsentIfRequired(from: self)
cmpEnabled: true and never call presentConsentIfRequired, ad loads for GDPR-region users will fail once Ezoic enables the consent dialog for your domain. Either add the call above or set cmpEnabled: false if you run your own CMP.
Consent outcomes
Completions run on the main thread. When the dialog was shown, the outcome is delivered after it has finished dismissing, so you can present your next screen from the completion. ConsentOutcome tells you what happened:
| Outcome | When |
|---|---|
.notRequired |
GDPR doesn't apply (for presentConsentIfRequired, this includes covered US states), the built-in CMP is disabled (cmpEnabled: false or by Ezoic), another CMP owns consent, or consent is managed by the app (see Setting consent manually) |
.alreadyDecided |
A still-valid decision is stored; no dialog shown |
.decided(decision) |
The user chose .acceptAll, .rejectAll or .custom; the choice is saved. From the US privacy settings, .acceptAll means not opted out and .rejectAll means opted out |
.dismissed |
The dialog closed without a choice; in GDPR regions ads stay gated for this session. From the US privacy settings, the user closed them without saving. This can happen without user action (the dialog failed to start, or resetConsent() ran while it was loading or open) |
.alreadyPresenting |
A consent dialog is already on screen, or one is being prepared with nothing on screen yet |
.failed(error) |
The dialog couldn't be shown (for example a network error, or no view controller in a window within 10 seconds). .failed(.notInitialized) means it was called before initialize, or init failed |
From SDK 1.22.0, .failed carries an Error. Through EzoicAds it is always an EzoicError; read its code with (error as? EzoicErrorCode)?.code.
Other consent calls:
presentConsentSettingsdepends on where the user is. In GDPR regions it always reopens the dialog, even if the user already decided; if the dialog can't be loaded (for example offline) and a still-valid decision is stored, it returns.alreadyDecided. In a covered US state it opens the US privacy settings. It returns.notRequiredelsewhere, whencmpEnabledisfalse, when another CMP is present, or when consent is managed by the app.isPrivacyOptionsRequired(Bool?, SDK 1.22.0 and later) tells you whether to show the "Privacy choices" entry point:truein a GDPR region or a covered US state while the built-in CMP handles consent,falseotherwise, andnilwhile still unknown.isConsentRequired(Bool?) isniluntil the init request completes, or when the server sent no consent information. It istruewhenever GDPR applies and the built-in CMP is in charge, including after the user has decided, andfalseotherwise. It staysfalsein US states.resetConsent()deletes the stored decision so the dialog shows again. Ads are gated again until the user decides. It also forgets the US-state choice: the GPP keys go back to "not opted out", and the US notice shows again at the next launch. Keys written by another CMP are left alone.
Decisions are written as standard IABTCF_* keys to UserDefaults.standard, with the Google Additional Consent string in IABTCF_AddtlConsent, so Prebid, Google Ad Manager, and other IAB-aware SDKs read them as usual. A stored decision is asked for again after the publisher's consent interval (at most 390 days), when the TCF policy version changes, or when the vendor list moves more than 2 versions ahead.
How ad loads wait for consent
In GDPR regions, while the built-in CMP is in charge and no decision is stored, ad loads wait for the user's decision:
- While the consent dialog is loading or on screen, ad loads wait up to 5 minutes in total per dialog, counted from
presentConsentIfRequiredand shared by all waiting ad loads. - While no dialog is in progress, the app is in the background, or the dialog has been replaced by a full-screen presentation, ad loads wait up to 10 seconds.
If the wait runs out, the ad load fails with EzoicError.consentRequired. iOS can't tell when the dialog is only covered by a sheet or an alert, so ad loads keep waiting in that case, up to the 5-minute cap.
If the dialog can't be shown (.failed), the SDK fails open: ads proceed with IABTCF_gdprApplies=1 and no TC string, which Google treats as limited ads and many Prebid bidders skip. An earlier TC string, if any, is cleared when the stored decision was stale. .failed(.notInitialized) writes nothing.
Ad loads never wait for the US-state notice.
US-state privacy
From SDK 1.22.0, for users in the 15 US states with consumer privacy laws (California, Colorado, Connecticut, Delaware, Florida, Iowa, Montana, Nebraska, New Hampshire, New Jersey, Oregon, Tennessee, Texas, Utah and Virginia), the built-in CMP does what Ezoic's web CMP does. There is nothing to call and no new setting; it runs whenever the built-in CMP is on.
- Notice: until the user chooses, a card slides up at the bottom of the screen: "Privacy Preferences", with Consent and Do Not Sell My Information. It doesn't block the screen, and ads keep loading. Only a choice dismisses it; until then it follows the user to the next screen when its screen goes away, stays through backgrounding, and never sits over a full-screen ad or another SDK screen. It appears only in your app's own key window. Ezoic anchor ads are hidden while it shows. Without a choice, it shows again at the next launch.
- Settings: Do Not Sell My Information opens a full screen with one "Do not sell or share my information" toggle and Save Settings.
presentConsentSettingsopens the same screen. - Signals: the CMP writes the state's IAB GPP section to
UserDefaults.standard(IABGPP_HDR_GppString,IABGPP_GppSID,IABGPP_<section>_Stringand the decoded fields such asIABGPP_<section>_SaleOptOut), starting as "not opted out" with the notice given. Prebid, Google Ad Manager and other GPP-aware SDKs read them as usual. After an opt-out, Google Ad Manager requests also ask for restricted data processing. - Hands off: the CMP writes no GPP keys and shows no notice when another CMP has written
IABGPP_*keys, when you callsetGPPConsent, or withautoReadConsent: false. When the user is no longer in a covered state, or the built-in CMP is turned off, it removes only the keys it wrote.
See Consent management (CMP) for more detail.
Using your own CMP
Set cmpEnabled: false. The SDK then reads your CMP's IABTCF_* and IABGPP_* keys as before. The built-in CMP also stays out of the way automatically if it finds IABTCF_CmpSdkID set to another CMP's ID, and writes no GPP keys if another CMP has already written IABGPP_* keys.
let config = EzoicConfiguration(domain: "example.com", cmpEnabled: false)
From SDK 1.24.0 you can also remove the built-in CMP from your app: add the EzoicAdsSDKWithoutCMP product instead of EzoicAdsSDK and keep cmpEnabled: false. It is the same SDK with the same import EzoicAdsSDK, without any of the CMP's code (about 600 KB of linked code and data in an arm64 app). In Xcode, select your target, then under Frameworks, Libraries, and Embedded Content remove EzoicAdsSDK and add EzoicAdsSDKWithoutCMP from the ezoic-swift-sdk-dist package. In Package.swift:
.product(name: "EzoicAdsSDKWithoutCMP", package: "ezoic-swift-sdk-dist")
Don't combine EzoicAdsSDKWithoutCMP with the standalone EzoicCmpSDK product; an app that shows Ezoic ads and wants Ezoic's CMP uses EzoicAdsSDK.
Without the CMP the SDK behaves exactly as with cmpEnabled: false: presentConsentIfRequired and presentConsentSettings return .notRequired, isConsentRequired and isPrivacyOptionsRequired are false once initialized, ad loads never wait for a consent decision, and resetConsent() does nothing. If you remove the CMP but leave cmpEnabled at its default true, initialize logs a warning (with debugEnabled = true): "Ezoic CMP is not included in this app, so consent is not collected by the SDK. If you use another CMP, set cmpEnabled = false." EzoicAds.isBuiltInCmpIncluded is false in an app built with EzoicAdsSDKWithoutCMP.
Without the built-in CMP, initialize also removes the consent keys an Ezoic CMP from an earlier version of your app wrote, so its old decision isn't sent along with your new CMP's. It never removes another CMP's keys or the ones your app wrote:
IABTCF_TCStringandIABTCF_gdprAppliesgo only when Ezoic's in-app CMP wrote them (the TC string's CMP ID andIABTCF_CmpSdkIDare both 299). They stay while you pass consent yourself withsetGDPRConsentorautoReadConsentset tofalse, and a string you pass tosetGDPRConsentis kept even if it carries CMP ID 299 (for example one from Ezoic's web CMP).- The other
IABTCF_*keys the Ezoic CMP writes go whileIABTCF_CmpSdkIDis still 299. IABGPP_*keys go only while they still hold the values the Ezoic CMP wrote.
Whichever CMP writes them, the SDK automatically reads consent signals from UserDefaults:
- TCF v2 consent is read from
IABTCF_*keys. - GPP consent is read from
IABGPP_*keys. - US Privacy consent is read from the standard IAB privacy key.
Setting consent manually
You can also set consent in code. Manual consent and the built-in CMP are mutually exclusive: once setGDPRConsent is called, or when autoReadConsent is false, the built-in CMP doesn't gate ad loads, show its dialog, or write IABTCF_* keys, and resetConsent() leaves the keys alone. Likewise, once setGPPConsent is called, the built-in CMP writes no IABGPP_* keys and shows no US notice.
The setGDPRConsent value lasts for the current process only. Call setGDPRConsent before EzoicAds.shared.initialize on every launch, or set cmpEnabled: false. Otherwise each cold start begins with the built-in CMP in charge until your call lands, and it can gate ad loads, show its dialog, and write IABTCF_* keys.
Since SDK 1.19.1, the SDK writes the consent you pass to the standard IAB keys in UserDefaults.standard as soon as you call it, before initialize too, so Google Mobile Ads, IMA, Amazon and other SDKs in the app see it: setGDPRConsent writes IABTCF_gdprApplies and IABTCF_TCString, and setGPPConsent writes IABGPP_HDR_GppString and IABGPP_GppSID. The SDK doesn't write the decoded keys, such as IABTCF_PurposeConsents, so an SDK that reads those still needs them from your CMP. EzoicAds.shared.consentManager.clearManualConsent() restores the values those keys held before, unless a CMP has written them since.
EzoicAds.shared.setGDPRConsent(
applies: true,
consentString: "TCF_CONSENT_STRING"
)
// A California (section 8) string, not opted out
EzoicAds.shared.setGPPConsent(
gppString: "DBABBg~BVoAAACA.QA",
sectionIds: "8"
)
EzoicAds.shared.setSubjectToCOPPA(true)
// Then initialize
EzoicAds.shared.initialize(with: config) { result in /* ... */ }
sectionIds lists the GPP sections in your string, comma-separated. It depends on the user's state: 8 is California, and each other state has its own section. Ezoic's CMP writes the section for the user's state, not the national section (7).
Pageview Tracking
Ezoic reports app traffic per screen, the way it reports a website per URL. Apps have no URLs, so the SDK gives each screen one:
https://<your domain>/<bundle identifier>/<screen label>
That URL is what per-page reporting and placement optimization key on, so the screen label is what you will see in the Ezoic dashboard.
Automatic tracking
The SDK automatically tracks a pageview for every UIViewController that appears after initialization (container and system controllers are excluded). Without any code from you, the screen label defaults to the view controller's class name, for example https://example.com/com.example.app/SettingsViewController.
Labeling screens
To name screens the way you want to see them in reporting, call trackPageview(screen:) when the user lands on a screen, typically from viewDidAppear. Available in SDK 1.12.0 and later.
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
EzoicAds.shared.trackPageview(screen: "members area")
// reported as https://example.com/com.example.app/members-area
}
For apps using async/await:
let success = await EzoicAds.shared.trackPageview(screen: "members/profile")
// reported as https://example.com/com.example.app/members/profile
Labels are free text. Use / for hierarchy (members/profile); spaces become -, punctuation is dropped, and case is kept. The label is also attached to every ad request on that screen, so impressions and pageviews report under the same page.
A labeled trackPageview(screen:) takes precedence over the automatic pageview for the same navigation, so you can label only the screens you care about without double counting. Calling trackPageview() with no label still records a pageview under the current screen label:
EzoicAds.shared.trackPageview { success in
print("Pageview tracked: \(success)")
}
Label your launch screen early. If you label the first screen, call trackPageview(screen:) before EzoicAds.shared.initialize or from its completion handler. A launch-screen label that arrives more than about 1 second after initialization finishes (outside a consent dialog) records a second launch pageview.
Manual tracking only
If you would rather the SDK never guess, disable automatic tracking and label every screen yourself:
let config = EzoicConfiguration(
domain: "example.com",
autoTrackPageviews: false
)
Troubleshooting
SDK Not Initializing
- Confirm the configured
domainmatches your Ezoic dashboard. - Confirm the app has network access.
- Enable
debugEnabled: trueand review SDK logs in the Xcode console.
Ads Not Loading
- Initialize the SDK before calling
loadAd(). - Confirm the Ezoic ad unit identifier is configured in Ezoic.
- Confirm the Google Mobile Ads application ID is present in
Info.plist. - Check consent configuration if traffic is subject to privacy regulations.
- If ad loads fail with
EzoicError.consentRequired, the built-in consent dialog is waiting for a decision. CallpresentConsentIfRequiredafter initializing, or setcmpEnabled: falseif you run your own CMP. See Built-in consent dialog.