Interstitial

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

  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

Overview

Interstitials are loaded and displayed using a SASInterstitialManager instance.

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

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


#import <SASDisplayKit/SASDisplayKit.h>

Configuring the SDK

The SDK needs to be configured with your own site ID and base URL before making any ad calls. You will have to call the method configure(siteId:) 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 with your own site ID and base URL.
  SASConfiguration.shared.configure(siteId: YOUR_SITE_ID)

  // ...
}


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // ...

  // Configuring the SDK with your own site ID and base URL.
  [[SASConfiguration sharedInstance] configureWithSiteId:YOUR_SITE_ID];

  // ...
}

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, keywordTargeting: SOME_KEYWORD_TARGETING)


SASAdPlacement *adPlacement = [SASAdPlacement adPlacementWithSiteId:SOME_SITE_ID pageId:SOME_PAGE_ID formatId:SOME_FORMAT_ID keywordTargeting:SOME_KEYWORD_TARGETING];

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).

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.

The separation of the load and show actions also means that having a delegate is mandatory (contrary to banner integrations).

To load an interstitial, start by creating a new SASInterstitialManager instance using the ad placement defined earlier and a delegate that implements the SASInterstitialManagerDelegate protocol: 


let interstitialManager = SASInterstitialManager(placement: adPlacement, delegate: self)


SASInterstitialManager *interstitialManager = [[SASInterstitialManager alloc] initWithPlacement:adPlacement delegate:self];

There are a lot of interstitial events that you can listen to using the interstitial manager delegate, but you should at least implement the two methods informing you about the ad loading result.

This will allow you to know if the interstitial can be shown or if you need to load an ad again:


func interstitialManager(_ manager: SASInterstitialManager, didLoad ad: SASAd) {
  NSLog("Interstitial has been loaded")
}

func interstitialManager(_ manager: SASInterstitialManager, didFailToLoadWithError error: Error) {
  NSLog("Interstitial has failed to load with error: \(error.localizedDescription)")
}


- (void)interstitialManager:(SASInterstitialManager *)manager didLoadAd:(SASAd *)ad {
  NSLog(@"Interstitial has been loaded and is ready to be shown");
}

- (void)interstitialManager:(SASInterstitialManager *)manager didFailToLoadWithError:(NSError *)error {
  NSLog(@"Interstitial did fail to load with error: %@", [error localizedDescription]);
}

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


      interstitialManager.load()
      

        [self.interstitialManager load];

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 isn't ready or is maybe expired…
}


if (interstitialManager.adStatus == SASAdStatusReady) {
  [interstitialManager showFromViewController:self];
} else {
  // The interstitial isn't ready or is maybe expired…
}

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:


func interstitialManager(_ manager: SASInterstitialManager, didAppearFrom controller: UIViewController) {
  NSLog("Interstitial did appear successfully")
}

func interstitialManager(_ manager: SASInterstitialManager, didFailToShowWithError error: Error) {
  NSLog("Interstitial has failed to show with error: \(error.localizedDescription))")
}


- (void)interstitialManager:(SASInterstitialManager *)manager didAppearFromViewController:(nonnull UIViewController *)controller {
  NSLog("Interstitial did appear successfully");
}

- (void)interstitialManager:(SASInterstitialManager *)manager didFailToShowWithError:(NSError *)error {
  NSLog(@"Interstitial did fail to show with error: %@", [error localizedDescription]);
}

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).