SwiftyAds

A Swift library to display banner, interstitial, rewarded and native ads from Google AdMob and supported mediation partners.

• Requirements
• Create Accounts
• Mediation
• Installation
• Pre-Usage
• Usage
• App Store release information
• Demos
• License

Requirements

• iOS 13.0+
• Swift 5.6+

Create Accounts

AdMob

Sign up for an AdMob account and create your required AdUnitIDs for the types of ads you would like to display.

Funding Choices (Optional)

SwiftyAds uses Google`s User Messaging Platform (UMP) SDK to handle user consent if required. This SDK can handle both GDPR (EEA) requests and also the iOS 14 ATT alert.

This step can be skipped if you would like to disable user consent requests, see Add SwiftyAds.plist part of pre-usage section below. Otherwise please read the Funding Choices documentation to ensure they are setup up correctly for your requirements.

NOTE: Apple may be rejecting apps that use the UMP SDK to display the iOS 14 ATT alert. As a workaround you may have to tweak the wording of the explainer message or you can manually display the ATT alert before configuring SwiftyAds.

Installation

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

To add a swift package to your project simple open your project in xCode and click File > Swift Packages > Add Package Dependency. Than enter https://github.com/crashoverride777/swifty-ads.git as the repository URL and finish the installation wizard.

Alternatively if you have another swift package that requires SwiftyAds as a dependency it is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
.package(url: "https://github.com/crashoverride777/swifty-ads.git", from: "14.0.0")
]

Cocoa Pods

CocoaPods is a dependency manager for Cocoa projects. Simply install the pod by adding the following line to your pod file

pod 'SwiftyAds'

Manually

Alternatively you can copy the Sources folder and its containing files into your project and install the required dependencies.

• AdMob
• UMP

Pre-Usage

Update Info.plist

• AdMob
• UMP

Add SwiftyAds.plist

Download the template plist and add it to your projects main bundle. Than enter your required ad unit ids and other required fields. All entries all optional and can be removed if not needed.

• bannerAdUnitId (String)
• interstitialAdUnitId (String)
• rewardedAdUnitId (String)
• rewardedInterstitialAdUnitId (String)
• nativeAdUnitId (String)
• isTaggedForChildDirectedTreatment (Boolean) (COPPA)
• isTaggedForUnderAgeOfConsent (Boolean) (GDPR)
• isUMPDisabled (Boolean)

NOTE: Adding the isUMPDisabled entry and setting it to true means SwiftyAds will not carry out any consent requests using the User Messaging Platform (UMP) SDK. In that case you will have to manually support GDPR (EEA) and ATT (Apple) alerts if required.

Link AppTrackingTransparency framework

Link the AppTrackingTransparency framework in Framework, Libraries and Embedded Content under the general tab, otherwise iOS 14 ATT alerts will not display.

If you are supporting iOS 13 and below you will also have to make it optional in BuildPhases->Link Binary With Libraries to avoid a crash.

Usage

Add import (CocoaPods or SwiftPackageManager)

• Add the import statement to your swift file(s) if you installed via CocoaPods or SwiftPackageManager

import SwiftyAds

Create GADRequest builder

Create a SwiftyAdsRequestBuilder class, implementing the SwiftyAdsRequestBuilderType protocol, that SwiftyAds will use to load ads. Some mediation networks such as Vungle may required specific GADRequest extras. Please check the AdMob mediation documentation.

import SwiftyAds
import GoogleMobileAds

final class SwiftyAdsRequestBuilder {}

extension SwiftyAdsRequestBuilder: SwiftyAdsRequestBuilderType {

    func build() -> GADRequest {
        GADRequest()
    }
}

Create Mediation Configurator (Optional)

Create a SwiftyAdsMediationConfigurator class, implementing the SwiftyAdsMediationConfiguratorType protocol, to manage updating mediation networks for COPPA/GDPR consent status changes. Please check the AdMob mediation documentation.

App Lovin Example

import SwiftyAds
import AppLovinAdapter

final class SwiftyAdsMediationConfigurator {}

extension SwiftyAdsMediationConfigurator: SwiftyAdsMediationConfiguratorType {

    func updateCOPPA(isTaggedForChildDirectedTreatment: Bool)
        // App Lovin mediation network example
        ALPrivacySettings.setIsAgeRestrictedUser(isTaggedForChildDirectedTreatment)
    }

    func updateGDPR(for consentStatus: SwiftyAdsConsentStatus, isTaggedForUnderAgeOfConsent: Bool) {
        // App Lovin mediation network example
        ALPrivacySettings.setHasUserConsent(consentStatus == .obtained)
        if !ALPrivacySettings.isAgeRestrictedUser() { // skip if already age restricted e.g. enableCOPPA called
            ALPrivacySettings.setIsAgeRestrictedUser(isTaggedForUnderAgeOfConsent)
        }
    }
}

Configure

Create a configure method and call it as soon as your app launches e.g. AppDelegate didFinishLaunchingWithOptions. This will also trigger the initial consent flow if consent has not been disabled. Ads can only be displayed after the completion handler was called.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    if let rootViewController = window?.rootViewController {
        configureSwiftyAds(from: rootViewController)
    }
    return true
}

private func configureSwiftyAds(from viewController: UIViewController) {
    #if DEBUG
    // testDeviceIdentifiers: The test device identifiers used for debugging purposes.
    // consentConfiguration: The debug consent configuration:
    //    1) .default(geography: UMPDebugGeography), 
    //    2) .resetOnLaunch(geography: UMPDebugGeography) 
    //    3) .disabled
        
    let environment: SwiftyAdsEnvironment = .development(testDeviceIdentifiers: [], consentConfiguration: .resetOnLaunch(geography: .EEA))
    #else
    let environment: SwiftyAdsEnvironment = .production
    #endif
    
    SwiftyAds.shared.configure(
        from: viewController,
        for: environment,
        requestBuilder: SwiftyAdsRequestBuilder(),
        mediationConfigurator: SwiftyAdsMediationConfigurator(), // set to nil if no mediation is required
        consentStatusDidChange: { status in
            print("The consent status has changed")
        },
        completion: { result in
            switch result {
            case .success(let consentStatus):
                print("Configure successful")
                // Ads will preload and sohuld be ready for displaying
            case .failure(let error):
                print("Setup error: \(error)")
            }
        }
    )
}

NOTE: If you do not use the Google UMP SDK to display the iOS 14 App Tracking Transparency (ATT) alert, it is recommended to ask for permission before configuring SwiftyAds.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    if let rootViewController = window?.rootViewController {
        if  #available(iOS 14, *)  {
            ATTrackingManager.requestTrackingAuthorization { status in
                self.configureSwiftyAds(from: rootViewController)
            }
        } else {
            configureSwiftyAds(from: rootViewController)
        }
    }
    return true
}

Showing ads outside a UIViewController

SwiftyAds requires reference to a UIViewController to present ads. If you are not using SwiftyAds inside a UIViewController you can do the following to get reference the rootViewController.

AppDelegate

if let viewController = window?.rootViewController {
    SwiftyAds.shared.show(...)
}

SKScene

if let viewController = view?.window?.rootViewController {
    SwiftyAds.shared.show(...)
}

Banner Ads

Create a property in your UIViewController for the banner to be displayed

class SomeViewController: UIViewController {

    private var bannerAd: SwiftyAdsBannerType?
}

Prepare the banner in viewDidLoad

override func viewDidLoad() {
    super.viewDidLoad()
    
    bannerAd = SwiftyAds.shared.makeBannerAd(
        in: self,
        adUnitIdType: .plist, // set to `.custom("AdUnitId")` to add a different AdUnitId for this particular banner ad
        position: .bottom(isUsingSafeArea: true) // banner is pinned to bottom and follows the safe area layout guide
        animation: .slide(duration: 1.5),
        onOpen: {
            print("SwiftyAds banner ad did receive ad and was opened")
        },
        onClose: {
            print("SwiftyAds banner ad did close")
        },
        onError: { error in
            print("SwiftyAds banner ad error \(error)")
        },
        onWillPresentScreen: {
            print("SwiftyAds banner ad was tapped and is about to present screen")
        },
        onWillDismissScreen: {
            print("SwiftyAds banner ad presented screen is about to be dismissed")
        },
        onDidDismissScreen: {
            print("SwiftyAds banner did dismiss presented screen")
        }
    )
}

and show it in viewDidAppear. This is to ensure that the view has been layed out correctly and has a valid safe area.

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    
    bannerAd?.show(isLandscape: view.frame.width > view.frame.height)
}

To handle orientation changes, simply call the show method again in viewWillTransition

override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
    super.viewWillTransition(to: size, with: coordinator)
    
    coordinator.animate(alongsideTransition: { [weak self] _ in
        self?.bannerAd?.show(isLandscape: size.width > size.height)
    })
}

You can hide the banner by calling the hide method.

bannerAd?.hide() 

You can remove the banner from its superview by calling the remove method and afterwards nil out the reference.

bannerAd?.remove() 
bannerAd = nil

Interstitial Ads

SwiftyAds.shared.showInterstitialAd(
    from: self,
    afterInterval: 2, // every 2nd time method is called ad will be displayed. Set to nil to always display.
    onOpen: {
        print("SwiftyAds interstitial ad did open")
    },
    onClose: {
        print("SwiftyAds interstitial ad did close")
    },
    onError: { error in
        print("SwiftyAds interstitial ad error \(error)")
    }
)

Rewarded Ads

Rewarded ads may be non-skippable and should only be presented when pressing a dedicated button.

SwiftyAds.shared.showRewardedAd(
    from: self,
    onOpen: {
        print("SwiftyAds rewarded ad did open")
    },
    onClose: {
        print("SwiftyAds rewarded ad did close")
    }, 
    onError: { error in
        print("SwiftyAds rewarded ad error \(error)")
    },
    onNotReady: { [weak self] in
        guard let self = self else { return }
        print("SwiftyAds rewarded ad was not ready")
        
        // If the user presses the rewarded video button and watches a video it might take a few seconds for the next video to reload.
        // Use this callback to display an alert incase the video was not ready. 
        let alertController = UIAlertController(
            title: "Sorry",
            message: "No video available to watch at the moment.",
            preferredStyle: .alert
        )
        alertController.addAction(UIAlertAction(title: "Ok", style: .cancel))
        DispatchQueue.main.async {
            self.present(alertController, animated: true)
        }
    },
    onReward: { [weak self] rewardAmount in
        print("SwiftyAds rewarded ad did reward user with \(rewardAmount)")
        // Provide the user with the reward e.g coins, diamonds etc
    }
)

NOTE: AdMob provided a new rewarded video API which lets you preload multiple rewarded videos with different AdUnitIds. While SwiftyAds uses this new API it currently only supports loading 1 rewarded ad at a time.

Rewarded Interstitial Ads

Rewarded interstitial ads can be presented naturally in your apps flow, similar to interstitial ads, and do not require a dedicated button like regular rewarded ads. Before displaying a rewarded interstitial ad, you must present the user with an intro screen that provides clear reward messaging and an option to skip the ad before it starts.

SwiftyAds.shared.showRewardedInterstitialAd(
    from: self,
    afterInterval: 2, // every 2nd time method is called ad will be displayed. Set to nil to always display.
    onOpen: {
        print("SwiftyAds rewarded interstitial ad did open")
    },
    onClose: {
        print("SwiftyAds rewarded interstitial ad did close")
    }, 
    onError: { error in
        print("SwiftyAds rewarded interstitial ad error \(error)")
    },
    onReward: { [weak self] rewardAmount in
        print("SwiftyAds rewarded interstitial ad did reward user with \(rewardAmount)")
        // Provide the user with the reward e.g coins, diamonds etc
    }
)

Native Ads

To present a native ad simply call the load method. Once a native ad has been received you can update your custom ad view with the native ad content.

You can set the amount of ads to load (GADMultipleAdsAdLoaderOptions) via the loaderOptions parameter. Set to .single to use the default options.

As per Googles documentation, requests for multiple native ads don't currently work for AdMob ad unit IDs that have been configured for mediation. Publishers using mediation should avoid using the GADMultipleAdsAdLoaderOptions class when making requests. In that case you can also set the loaderOptions parameter to .single.

SwiftyAds.shared.loadNativeAd(
    from: self,
    adUnitIdType: .plist, // set to `.custom("AdUnitId")` to add a different AdUnitId for this particular native ad
    loaderOptions: .single, // set to `.multiple(2)` to load multiple ads for example 2
    onFinishLoading: {
        // Native ad has finished loading and new ads can now be loaded
    },
    onError: { error in
        // Native ad could not load ad due to error
    },
    onReceive: { nativeAd in
        // show native ad (see demo app or google documentation)
    }
)

NOTE: While prefetching ads is a great technique, it's important that you don't keep old native ads around forever without displaying them. Any native ad objects that have been held without display for longer than an hour should be discarded and replaced with new ads from a new request.

Errors

Use can use the SwiftyAdsError enum to handle SwiftyAds specific errors.

if let swiftyAdsError = error as? SwiftyAdsError {
    switch swiftyAdsError { 
    case .interstitialAdNotLoaded:
        // Ad was not loaded
    default:
        break
    }
}

Consent Status

// Check current consent status
SwiftyAds.shared.consentStatus

Booleans

// Check if interstitial ad is ready, for example to show an alternative ad
SwiftyAds.shared.isInterstitialAdReady

// Check if rewarded ad is ready, for example to show/hide button
SwiftyAds.shared.isRewardedAdReady

// Check if rewarded interstitial ad is ready, for example to show an alternative ad
SwiftyAds.shared.isRewardedInterstitialAdReady

// Check if child directed treatment is tagged on/off. Nil if not indicated how to be treated. (COPPA)
SwiftyAds.shared.isTaggedForChildDirectedTreatment

// Check if under age of consent is tagged on/off (GDPR)
SwiftyAds.shared.isTaggedForUnderAgeOfConsent

// Check if ads have been disabled
SwiftyAds.shared.isDisabled

Disable/Enable Ads (In App Purchases)

Call the disable(_ isDisabled: Bool) method and banner, interstitial and rewarded interstitial ads will no longer display. This will not stop regular rewarded ads from displaying as they should have a dedicated button. This way you can remove banner, interstitial and rewarded interstitial ads but still have rewarded ads.

SwiftyAds.shared.setDisabled(true)

For permanent storage you will need to create your own boolean logic and save it in something like NSUserDefaults, or preferably Keychain. Than at app launch, before you call SwiftyAds.shared.configure(...), check your saved boolean and disable the ads if required.

if UserDefaults.standard.bool(forKey: "RemovedAdsKey") == true {
    SwiftyAds.shared.setDisabled(true)
}

Ask for consent again

It is required that the user has the option to change their GDPR consent settings, usually via a button in settings.

func consentButtonPressed() {
    SwiftyAds.shared.askForConsent(from: self) { result in
        switch result {
        case .success(let status):
            print("Did change consent status")
        case .failure(let error):
            print("Consent status change error \(error)")
        }
    }
}

The consent button can be hidden if consent is not required or user is tagged for under age of consent.

// If consent is not required e.g. outside EEA than we do not need to show consent button.
// If inside EEA we need to display the consentButton unless user is tagged for under age of consent
if SwiftyAds.shared.consentStatus == .notRequired {
    consentButton.isHidden = true
} else {
    consentButton.isHidden = SwiftyAds.shared.isTaggedForUnderAgeOfConsent
}

App Store release information

Make sure to prepare for Apple's App Store data disclosure requirements

Demos

https://github.com/crashoverride777/swifty-ads-demo

License

SwiftyAds is released under the MIT license. See LICENSE for details.