Interstitial

This page explains how to use the Equativ Display SDK to display an interstitial ad in your application.

Table of contents

1. Overview
2. Importing the SDK
3. Configuring the SDK
4. Creating a placement
5. Loading an interstitial using a manager
6. Showing an interstitial
7. Listening to ad audio events

---

Overview

Interstitials are loaded and displayed using a SASInterstitialManager instance.

To load and display an ad using an interstitial manager, you will need:

• An fully configured Equativ Display SDK.
• An instance of SASAdPlacement , that will be used to perform ad calls to the delivery engine.
• An instance of SASInterstitialManager , that will load and show the interstitial.
• A view controller implementing the SASInterstitialManagerDelegate protocol.

The next sections describe the whole process to load and show an interstitial.

You can also refer to the samples if you just want to copy/paste the complete integration.

Importing the SDK

Before using the SDK, you must import the framework:

import SASDisplayKit

Configuring the SDK

The SDK needs to be configured before making any ad calls. You will have to call the method configure() of SASConfiguration shared instance to do so.

This method should be called as soon as possible. A good place to do it is in your application’s delegate, in the application(_:didFinishLaunchingWithOptions:) method.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  // ...

  // Configuring the SDK
  SASConfiguration.shared.configure()

  // ...
}

Note that any ad call performed before calling the configure() method will fail.

Creating a placement

You will need an ad placement to perform an ad call.

Creating an ad placement is done by instantiating a SASAdPlacement object using a site ID, a page ID and a format ID. You can also provide some additional information, like targeting informations (more information in the API documentation).

let adPlacement = SASAdPlacement(siteId: SOME_SITE_ID, pageId: SOME_PAGE_ID, formatId: SOME_FORMAT_ID)

You can add several information to your ad placements in order to increase the monetization.

For instance you can provide a Seller Defined Audience object, or a Supply Chain Object if your are an inventory reseller.

For testing purposes, it is possible to instantiate generic ad placements that will always deliver an ad of a particular format. This is done by using the SASAdPlacement(testAd:) initializer (check the SASAdPlacementTest enum for an exhaustive list of the formats you can get using test placements).

Don’t forget to remove all test placements before releasing your app!

Loading an interstitial using a manager

Interstitials ads are managed using an interstitial manager which will first load the ad then show it when you want.

To load an interstitial, start by creating a new SASInterstitialManager instance using the ad placement defined earlier. You can also set a delegate implementing the SASInterstitialManagerDelegate protocol:

let interstitialManager = SASInterstitialManager(adPlacement: adPlacement)
interstitialManager.delegate = self

Here are the SASInterstitialManagerDelegate methods to implement:

func interstitialManager(_ interstitialManager: SASInterstitialManager, didLoadWith adInfo: SASAdInfo) {
    print("Interstitial ad loaded with info: \(adInfo)")
}

func interstitialManager(_ interstitialManager: SASInterstitialManager, didFailToLoad error: Error) {
    print("Interstitial did fail to load with error: \(error)")
}

func interstitialManagerDidShow(_ interstitialManager: SASInterstitialManager) {
    print("Interstitial ad was shown")
}

func interstitialManager(_ interstitialManager: SASInterstitialManager, didFailToShow error: Error) {
    print("Interstitial did fail to show with error: \(error)")
}

func interstitialManagerDidClose(_ interstitialManager: SASInterstitialManager) {
    print("Interstitial ad was closed")
}

Most methods of the delegate are optional, but you should at least implement the two methods interstitialManager(_:didLoadWith:) and interstitialManager(_:didFailToLoad:) used to check if an interstitial ad has been loaded or if it has failed to load.

Finally to actually trigger the interstitial ad loading process call the loadAd() method of the SASInterstitialManager :

interstitialManager.loadAd()

Showing an interstitial

When the interstitial manager has loaded an ad successfully, you can show it when needed using the show(from:) method.

It is also possible to check the current status of an interstitial manager at any time using the adStatus property.

if interstitialManager.adStatus == .ready {
  interstitialManager.show(from: self)
} else {
  // The interstitial manager's ad is either still loading, or not available.
}

Note that the show(from:) method can fail for several reasons. Use the interstitial manager delegate to check the result of your call to this method.

When an interstitial has been shown, it is discarded and a new one must be loaded (the same interstitial manager can be reused if the ad placement is identical).

Listening to ad audio events

You can listen to ad audio events by implementing the SASInterstitialManagerDelegate protocol.

let interstitialManager = SASInterstitialManager(adPlacement: adPlacement)
interstitialManager.delegate = self

The two optional delegate methods related to ad audio are:

func interstitialManagerWillStartAudioPlayback(_ interstitialManager: SASInterstitialManager) {
    print("Interstitial video ad will start to play audio")

    // Equativ Display SDK is notifying your app that it will play audio. You could optionally
    // pause music and/or manipulate your audio session category depending on your apps design.
}

func interstitialManagerDidStopAudioPlayback(_ interstitialManager: SASInterstitialManager) {
    print("Interstitial video ad did stop to play audio")

    // Equativ Display SDK is notifying your app that it has stopped playing audio. Depending 
    // on your apps design, you could resume music here and/or restore your audio session category.
}

• The SDK does not modify the app’s audio session category, so the app should handle it within the delegate methods.
• All video ads start muted and require user interaction to toggle audio.
• Developers should ensure that any changes to the audio session category are reverted in the dealloc of the ViewController, because the interstitialManagerDidStopAudioPlayback delegate method will not be called if the banner view is deallocated before the end of the ad.