AdMob Mediation SDK (iOS)

Overview

We have 3 parts to integrate the Appier Mobile SDK through the AdMob Mediation SDK for iOS

• Ad Server Setting
• Integrating Appier Mobile SDK
• Enabling Test Ads

Current Supported Ad Formats

• Native Ads (image and video)

1. Ad Server Settings

Step 1 - Ad Unit Settings

• Get the AdMob Ad Unit ID for the App
  You will need the ad unit ID from AdMob and place it in the iOS App. To find out your ad unit ID, go to the ad unit page and get the ad unit ID.
  Note: This is NOT the ad unit ID from Appier.

Step 2 - Line item for Appier Mediation

• 2.1 Set up your mediation group
  On the Mediation page, please click the CREATE MEDIATION GROUP button if you do not have a mediation group.

Choose your ad format and select the iOS platform. After finishing the settings, click the CONTINUE button.

Fill in the mediation group name and add your ad units in the Ad units block. After adding your ad unit in the Ad units block, the Ad sources block will appear.

• 2.2 Set up custom event
  Click ADD CUSTOM EVENT and set your label for the Appier custom event. Also, use the price you discussed with the Appier Partnership team to set the eCPM.
  After all the settings are ready, click CONTINUE.

Next, we should set up the custom event class name and parameter.

Class Name: Fill in AppierAdsAdMobMediation.APRAdAdapter

Parameter: Fill in the JSON {"zoneId": "<your_zone_id>"}, where zoneId is provided by Appier.

Click DONE when you finish the settings.

After finishing all of the mediation group settings, you can click SAVE and integrate your iOS app with Appier Mobile SDK.

2. Integrating Appier Mobile SDK

In the previous section, we went through the setup of the AdMob web UI. I believe you've already had at least one ad unit ID. In this section, we will focus on how to integrate Appier's SDK and start monetizing your app.

Steps Overview

1. Prerequisites
2. Installation
   • Swift Package Manager
   • CocoaPods
3. Initialize the Ads SDK
4. Prepare for iOS 14+
   • Enable SKAdNetwork to track conversions
   • Request App Tracking Transparency authorization
5. GDPR Consent
6. Ad Format Integration
   • Native Ads Integration

Step 1 - Prerequisites

• Use Google Mobile Ads iOS SDK version >= 12.4.0 if using GMA 12, >= 13.0.0 if using GMA 13.

• Set your project's iOS deployment target to >= 12.0 if using GMA 12, >= 13.0 if using GMA 13.

Step 2 - Installation

Choose the instructions that match the Google Mobile Ads SDK (GMA) major version already used by your app:

Use AppierAdsAdMobMediation 2.x with GMA 12.x, or AppierAdsAdMobMediation 3.x with GMA 13.x. Both versions use AppierAds 2.x, starting from 2.1.0.

2.1 - Swift Package Manager

In Xcode, go to File > Add Package Dependencies…. Add the packages for your GMA version below, select Up to Next Major Version with the specified starting version, and link each listed product to your app target.
If your app already includes Google Mobile Ads through Swift Package Manager, keep that package and confirm that its major version matches the AppierAdsAdMobMediation version you select.

For GMA 12.x:

For GMA 13.x:

AppierAdsAdMobMediation declares AppierAds and Google Mobile Ads as package dependencies. Linking their products to your app target also makes the modules available to the app code that imports AppierAds and GoogleMobileAds.

If you manage dependencies in Package.swift, use the matching configuration:

dependencies: [
    .package(
        url: "https://github.com/appier/ads-ios-admob-mediation",
        .upToNextMajor(from: "2.1.0")
    ),
    .package(
        url: "https://github.com/appier/ads-ios-sdk",
        .upToNextMajor(from: "2.1.0")
    ),
    .package(
        url: "https://github.com/googleads/swift-package-manager-google-mobile-ads",
        .upToNextMajor(from: "12.4.0")
    )
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "AppierAdsAdMobMediation", package: "ads-ios-admob-mediation"),
            .product(name: "AppierAds", package: "ads-ios-sdk"),
            .product(name: "GoogleMobileAds", package: "swift-package-manager-google-mobile-ads")
        ]
    )
]

dependencies: [
    .package(
        url: "https://github.com/appier/ads-ios-admob-mediation",
        .upToNextMajor(from: "3.0.0")
    ),
    .package(
        url: "https://github.com/appier/ads-ios-sdk",
        .upToNextMajor(from: "2.1.0")
    ),
    .package(
        url: "https://github.com/googleads/swift-package-manager-google-mobile-ads",
        .upToNextMajor(from: "13.0.0")
    )
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "AppierAdsAdMobMediation", package: "ads-ios-admob-mediation"),
            .product(name: "AppierAds", package: "ads-ios-sdk"),
            .product(name: "GoogleMobileAds", package: "swift-package-manager-google-mobile-ads")
        ]
    )
]

For Swift Package Manager installations, add -ObjC to your app target’s Build Settings > Other Linker Flags. Google Mobile Ads locates the Appier mediation class by name; this flag prevents the linker from removing that class.

2.2 - CocoaPods

Add the dependencies for your GMA version to your Podfile. If Google Mobile Ads is already listed in your Podfile, update its existing entry instead of adding a second one.

platform :ios, '12.0'

pod 'AppierAdsAdMobMediation', '~> 2.1'
pod 'AppierAds', '~> 2.1'
pod 'Google-Mobile-Ads-SDK', '~> 12.4'

platform :ios, '13.0'

pod 'AppierAdsAdMobMediation', '~> 3.0'
pod 'AppierAds', '~> 2.1'
pod 'Google-Mobile-Ads-SDK', '~> 13.0'

Run pod install after updating the Podfile. CocoaPods adds the required -ObjC linker flag for this installation method.

Step 3 - Initialize the Ads SDK

Before loading ads, call the start method on APRAds.shared, which initializes the SDK and calls back a completion handler once initialization is complete. This only needs to be done once, ideally at app launch and before initializing the AdMob Ads SDK.

Here's an example of how to call the start method in your AppDelegate:

import AppierAds
import GoogleMobileAds

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        // ...
        APRAds.shared.start(completion: nil)
        // ...
        MobileAds.shared.start(completionHandler: nil)
        // ...
        return true
    }
}

Step 4 - Prepare for iOS 14+

4.1 - Enable SKAdNetwork to track conversions

The Appier Ads SDK supports conversion tracking using Apple's SKAdNetwork, which lets Appier attribute an app install when the IDFA is not available.

To enable this functionality, update the SKAdNetworkItems key with an additional dictionary that defines Appier SKAdNetworkIdentifier values in your Info.plist

The snippet below includes Appier(x8uqf25wch.skadnetwork, v72qych5uu.skadnetwork) identifiers.

<key>SKAdNetworkItems</key>
<array>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>x8uqf25wch.skadnetwork</string>
  </dict>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>v72qych5uu.skadnetwork</string>
  </dict>
</array>

4.2 - Request App Tracking Transparency authorization

To display the App Tracking Transparency authorization request for accessing the IDFA, update your Info.plist to add the NSUserTrackingUsageDescription key with a custom message describing your usage. Here is an example description text:

<key>NSUserTrackingUsageDescription</key>
<string>The identifier will be used to deliver personalized ads to you.</string>

To present the App Tracking Transparency dialog, call requestTrackingAuthorization. We recommend waiting for the completion callback prior to loading ads so that if the user grants the permission, the Appier Ads SDK can use the IDFA in ad requests.

Here's an example of how to call the requestTrackingAuthorization method in your AppDelegate:

import AppTrackingTransparency

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func applicationDidBecomeActive(_ application: UIApplication) {
        if #available(iOS 14, *) {
            ATTrackingManager.requestTrackingAuthorization { _ in }
        }
    }
}

The description would display in the App Tracking Transparency dialog:

Step 5 - GDPR Consent (Recommended)

If your app is subject to GDPR, pass the user's consent decision to the Appier Ads SDK through APRAds.shared.configuration.gdprApplies. Despite its name, this property represents the user's consent to the use of their personal data:

• true — the user has consented. The SDK may use personal data (such as the IDFA, when App Tracking Transparency allows it) in ad requests.
• false — the user has declined. The SDK will not use personal data in ad requests.
• Not set (default) — consent is treated as unknown, and the SDK follows the App Tracking Transparency authorization status only.

Set this value once you have obtained the user's decision from your consent management flow, ideally at app launch and before initializing the Appier Ads SDK. If the user changes their choice later, update the value accordingly.

Note that not using personal data may reduce advertising performance and therefore revenue.

import AppierAds

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        // ...
        // `userHasConsented` comes from your consent management flow.
        APRAds.shared.configuration.gdprApplies = userHasConsented
        // ...
        APRAds.shared.start(completion: nil)
        // ...
        return true
    }
}

Step 6 - Ad Format Integration

6.1 - Native Ads Integration

To render Appier's native ads via AdMob mediation, you need to provide <your_ad_unit_id_from_admob> through APRAdExtras. The zoneId is provided by the custom event Parameter in AdMob.
Also, if you want to attach your own information to the ad (for example, which screen or placement requested it), you can pass any value through the .appInfo key of APRAdExtras. You will receive the same value back with the loaded native ad and in the event callbacks.

import AppierAds
import GoogleMobileAds
import AppierAdsAdMobMediation

class AdMobNativeViewController: UIViewController, NativeAdLoaderDelegate {
    private var adLoader: AdLoader!

    func loadNativeAd() {
        // Register APRAdMobAdEventDelegate (optional, see below)
        APRAdMobAdManager.shared.eventDelegate = self

        // Set APRAdExtras
        let appierExtras = APRAdExtras()
        appierExtras.set(key: .adUnitId, value: "<your_ad_unit_id_from_admob>")
        appierExtras.set(key: .appInfo, value: ["placement": "home_feed"])  // (Optional) your own information, any value

        // Build Request
        adLoader = AdLoader(
            adUnitID: "<your_ad_unit_id_from_admob>",
            rootViewController: self,
            adTypes: [.native],
            options: nil)
        adLoader.delegate = self

        // Load Ad
        let request = Request()
        request.register(appierExtras)
        adLoader.load(request)
    }
}

AdMob provides the delegate function adLoader to handle native ads. You should create a NativeAdView to render the Appier Native ad. You can get more details in the Native Ads Advanced guide.

The adLoader sets the text, images, and the native ad, etc into the ad view. You can specify the Appier native view through the advertiser variable of the AdMob native ad.

For Appier ads, bind the advertiserView of your NativeAdView to a UIImageView: Appier provides an advertiser icon (instead of advertiser text) that links to Appier's advertising policy.

import GoogleMobileAds
import AppierAdsAdMobMediation

extension AdMobNativeViewController {
    func adLoader(_ adLoader: AdLoader, didReceive nativeAd: NativeAd) {
        // `nativeAdView` is the NativeAdView you created to display this ad.

        // when the advertiser name is `Appier`, the ad is provided by Appier.
        if let advertiser = nativeAd.advertiser, advertiser == APRAdMobMediation.shared.advertiserName {
            // We provide advertiser image for user to get our advertising policy.
            (nativeAdView.advertiserView as? UIImageView)?.image = nativeAd.extraAssets?[APRAdMobMediation.shared.advertiserIcon] as? UIImage

            // Get the information you passed through .appInfo of APRAdExtras.
            let appInfo = nativeAd.extraAssets?[APRAdMobMediation.shared.appInfo] as? [String: String]
        }

        // ...
        (nativeAdView.headlineView as? UILabel)?.text = nativeAd.headline
        (nativeAdView.bodyView as? UILabel)?.text = nativeAd.body
        (nativeAdView.callToActionView as? UIButton)?.setTitle(nativeAd.callToAction, for: .normal)
        (nativeAdView.iconView as? UIImageView)?.image = nativeAd.icon?.image
        nativeAdView.mediaView?.mediaContent = nativeAd.mediaContent

        // Associate the native ad view with the native ad object. This is
        // required to make the ad clickable.
        // Note: this should always be done after populating the ad views.
        nativeAdView.nativeAd = nativeAd
    }

    func adLoader(_ adLoader: AdLoader, didFailToReceiveAdWithError error: Error) {
        // Handle the failure, e.g. hide the ad slot.
    }
}

Appier provides APRAdMobAdEventDelegate to allow Apps to receive notifications after impression/click events are recorded by AppierSDK. Set APRAdMobAdManager.shared.eventDelegate before loading the ad, as shown above. Only one delegate is active at a time.

extension AdMobNativeViewController: APRAdMobAdEventDelegate {
    func onNativeAdImpressionRecorded(nativeAd: APRAdMobNativeAd) {
        print("adunit id: \(nativeAd.adUnitId)")  // Get ad unit id
        print("zone id: \(nativeAd.zoneId)")  // Get zone id
        let appInfo = nativeAd.appInfo as? [String: String]  // Get the information you passed through .appInfo of APRAdExtras
    }

    func onNativeAdImpressionRecordedFailed(nativeAd: APRAdMobNativeAd, error: APRError) {}

    func onNativeAdClickedRecorded(nativeAd: APRAdMobNativeAd) {}

    func onNativeAdClickedRecordedFailed(nativeAd: APRAdMobNativeAd, error: APRError) {}
}

Native Video Ads

Appier native video ads are delivered through the same native ad flow; no extra request setup is needed. A video ad is a regular NativeAd whose mediaContent contains video, and it plays inside the MediaView of your NativeAdView.

• Make sure your NativeAdView contains a MediaView and assign nativeAd.mediaContent to it, as shown in the example above.
• Use nativeAd.mediaContent.hasVideoContent to check whether the ad contains video, and nativeAd.mediaContent.aspectRatio to size the MediaView.
• For video ads, nativeAd.images still contains the main image, which is also used as the video poster.
• Playback is managed by the Appier Ads SDK. The video plays automatically when the MediaView is visible and starts muted; users can toggle sound with the mute button on the video. Tapping the video opens the ad's destination.
• Custom playback controls through the Google Mobile Ads VideoController (play, pause, mute) are not supported for Appier ads.

Enabling Test Ads

After integrating the Appier Ads SDK, you can verify that ads are displayed correctly by setting APRAds.shared.configuration.testMode before initializing the SDK. By default (.none), test mode is off and real ads are served.

Important: Remove the test mode setting (or set it back to .none) before releasing your app.

APRAds.shared.configuration.testMode = .bid              // Always return a test ad.
APRAds.shared.configuration.testMode = .noBid            // Always return no bid, to test your no-fill handling.
APRAds.shared.configuration.testMode = .bidWithStoreView // Always return a test ad that opens an in-app App Store page (SKStoreProductViewController), when the device supports it.

// Initialize Appier Ads SDK after setting the test mode.
APRAds.shared.start(completion: nil)