View as Markdown

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 EzoicAdsSDK no longer makes EzoicCmp, EzoicCmpConfiguration, CmpError and CmpLogger available. They are for apps that use the CMP without Ezoic ads; if your code uses them alongside EzoicAds, add import EzoicCmpSDK. Through EzoicAds, a .failed consent outcome still always carries an EzoicError.
  • ConsentOutcome, ConsentDecisionType and EzoicErrorCode moved to a new module, EzoicConsentCore, which import EzoicAdsSDK still makes available. Unqualified names compile unchanged; a module-qualified name such as EzoicCmpSDK.ConsentOutcome becomes EzoicConsentCore.ConsentOutcome.
  • If your app uses another CMP, you can now leave the built-in CMP out with the new EzoicAdsSDKWithoutCMP product; see Using your own CMP. By default nothing changes: EzoicAdsSDK includes the CMP and it is on.
  • New EzoicAds.isBuiltInCmpIncluded tells 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.failed now carries an Error instead of an EzoicError. Through EzoicAds it is still an EzoicError at runtime, but case .failed(let error): error.code no longer compiles; read the code with (error as? EzoicErrorCode)?.code. See Consent management (CMP).
  • ConsentOutcome and ConsentDecisionType now live in the consent module. import EzoicAdsSDK still makes them available under the same names, but module-qualified names such as EzoicAdsSDK.ConsentOutcome no 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.
  • presentConsentSettings opens the US privacy settings in those states, so your existing "Privacy settings" button works for US users. New isPrivacyOptionsRequired tells you when to show it.
  • The EzoicAdsSDK Swift package product brings in the consent library for you. Apps that don't use Ezoic ads can add the EzoicCmpSDK product on its own; see Consent management (CMP).
  • New appPaid and setAppContent(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, adds tfcd=1 to instream video tags, and skips Amazon bids.
  • The device ID the SDK sends is kept only while storage consent allows it.
  • Calling initialize again now reports success instead of alreadyInitialized.
  • 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

  1. Remove pod 'EzoicAdsSDK' from your Podfile and run pod install. Also remove PrebidMobile, Google-Mobile-Ads-SDK and AmazonPublisherServicesSDK if nothing else in the app needs them as pods.
  2. Add https://github.com/ezoic/ezoic-swift-sdk-dist.git with File > Add Package Dependencies as shown above, and add the EzoicAdsSDK product to your app target.
  3. Change import EzoicAdsSDKBinary to import EzoicAdsSDK.
  4. 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.

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.

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: 320x50
  • EzoicBannerSize.largeBanner: 320x100
  • EzoicBannerSize.mediumRectangle: 300x250
  • EzoicBannerSize.fullBanner: 468x60
  • EzoicBannerSize.leaderboard: 728x90
  • EzoicBannerSize.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 = false on the call-to-action button, as above.

For SwiftUI, wrap the NativeAdView in a UIViewRepresentable.

On test devices, Google Mobile Ads shows an Ad Manager native ad validator popup over each native ad. It reports layout problems, such as an asset view outside the 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 }
}
If you disable the SDK's ATT handling, resolve the prompt before initializing the ad SDK. Initializing first means the first ad requests go out without the IDFA even when the user later grants permission, which lowers fill on the initial screen.

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.

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.
  • cmpEnabled is true in EzoicConfiguration. This is the default.
If your app already runs another CMP (for example UMP or OneTrust), you must set 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)
Upgrading to 1.13.0: if you keep the default 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.

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:

  • presentConsentSettings depends 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 .notRequired elsewhere, when cmpEnabled is false, 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: true in a GDPR region or a covered US state while the built-in CMP handles consent, false otherwise, and nil while still unknown.
  • isConsentRequired (Bool?) is nil until the init request completes, or when the server sent no consent information. It is true whenever GDPR applies and the built-in CMP is in charge, including after the user has decided, and false otherwise. It stays false in 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.

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 presentConsentIfRequired and 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. presentConsentSettings opens the same screen.
  • Signals: the CMP writes the state's IAB GPP section to UserDefaults.standard (IABGPP_HDR_GppString, IABGPP_GppSID, IABGPP_<section>_String and the decoded fields such as IABGPP_<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 call setGPPConsent, or with autoReadConsent: 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_TCString and IABTCF_gdprApplies go only when Ezoic's in-app CMP wrote them (the TC string's CMP ID and IABTCF_CmpSdkID are both 299). They stay while you pass consent yourself with setGDPRConsent or autoReadConsent set to false, and a string you pass to setGDPRConsent is 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 while IABTCF_CmpSdkID is 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.

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

  1. Confirm the configured domain matches your Ezoic dashboard.
  2. Confirm the app has network access.
  3. Enable debugEnabled: true and review SDK logs in the Xcode console.

Ads Not Loading

  1. Initialize the SDK before calling loadAd().
  2. Confirm the Ezoic ad unit identifier is configured in Ezoic.
  3. Confirm the Google Mobile Ads application ID is present in Info.plist.
  4. Check consent configuration if traffic is subject to privacy regulations.
  5. If ad loads fail with EzoicError.consentRequired, the built-in consent dialog is waiting for a decision. Call presentConsentIfRequired after initializing, or set cmpEnabled: false if you run your own CMP. See Built-in consent dialog.