Interstitial
An interstitial ad is a fullscreen format, usually skippable after the first few seconds of its display. Because of this, it's commonly used in transitions of the app or game, such as completing a level or navigating to a different screen.
To start using interstitial ads, just call load() using a valid placement id and then use one of the available present() functions when you need it to be displayed.
Start loading an ad
Presenting an ad
Calling isReady() will return if there's an interstitial available to be shown, regardless of its placement id. If multiple ads with different placement ids were previously loaded, the SDK will try to show the best one available.
Presenting an ad with placementId
When the app needs to present an ad for a specific placement id, isReady(withPlacementId:) and present(withPlacementId:) can be alternatively used.
Built-in features
Auto loading
Dismissed or failed to show ads will automatically trigger a new load request.
Auto retry
Failed to load ads will make a retry attempts, with an exponential backoff.
Additional settings
Register ad callbacks
Every ad callback indicates the placement id of the interstitial ad that triggered the event.
// Assign a delegate to handle the ad callbacks
XMediatorAds.interstitial.addDelegate(self)
// [...]
func didLoad(placementId: String, result: LoadResult) {
print("Interstitial loaded! placementId: \(placementId)")
}
func didPresent(placementId: String) {
print("Interstitial is being presented! placementId: \(placementId)")
}
func failedToPresent(placementId: String, error: PresentError) {
// If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
print("Interstitial failed to present. placementId: \(placementId), Reason: \(error.localizedDescription)")
}
func didRecordImpression(placementId: String, data: ImpressionData) {
print("Interstitial impression, with revenue: \(data.revenue). placementId: \(placementId)")
}
func willDismiss(placementId: String) {
print("Interstitial will be dismissed! placementId: \(placementId)")
}
func didDismiss(placementId: String) {
// If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
print("Interstitial dismissed! placementId: \(placementId)")
}
func didClick(placementId: String) {
print("Interstitial clicked! placementId: \(placementId)")
}
// Assign a delegate to handle the ad callbacks
[X3MXMediatorAds.interstitial addDelegate:self];
// [...]
- (void)didLoadWithPlacementId:(NSString * _Nonnull)placementId result:(X3MLoadResult * _Nonnull)result {
NSLog(@"Interstitial loaded! placementId: %@", placementId);
}
- (void)didPresentWithPlacementId:(NSString * _Nonnull)placementId {
NSLog(@"Interstitial is being presented! placementId: %@", placementId);
}
- (void)failedToPresentWithPlacementId:(NSString * _Nonnull)placementId error:(NSError * _Nonnull)error {
// If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
NSLog(@"Interstitial failed to present. placementId: %@. Reason %@", placementId, error);
}
- (void)didRecordImpressionWithPlacementId:(NSString * _Nonnull)placementId data:(X3MImpressionData * _Nonnull)data {
NSLog(@"Interstitial impression, with revenue: %f. PlacementId %@", data.revenue, placementId);
}
- (void)willDismissWithPlacementId:(NSString * _Nonnull)placementId {
NSLog(@"Interstitial will be dismissed! placementId: %@", placementId);
}
- (void)didDismissWithPlacementId:(NSString * _Nonnull)placementId {
// If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
NSLog(@"Interstitial dismissed! placementId: %@", placementId);
}
- (void)didClickWithPlacementId:(NSString * _Nonnull)placementId {
NSLog(@"Interstitial clicked! placementId: %@", placementId);
}
Advanced use cases
This guide provides the recommended integration steps to show an interstitial ad using X3M, which covers most of the common scenarios. For advanced use cases, where manually handling the lifecycle of the ad object is needed, refer to this section.
Code example
InterstitialViewController.swift
import UIKit
import XMediator
class InterstitialViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
}
@IBAction func startButtonTouchUpInside(_ sender: Any) {
XMediatorAds.startWith(appKey: "<your-app-key>") { result in
XMediatorAds.interstitial.addDelegate(self)
// Start loading an interstitial. Subsequent loads or retries are handled by the sdk
XMediatorAds.interstitial.load(placementId: "<placement-id>")
}
}
@IBAction func presentButtonTouchUpInside(_ sender: Any) {
if XMediatorAds.interstitial.isReady() {
XMediatorAds.interstitial.present(fromViewController: self)
}
}
}
extension InterstitialViewController: InterstitialAdsDelegate {
func didLoad(placementId: String, result: LoadResult) {
print("Interstitial loaded! placementId: \(placementId)")
}
func didPresent(placementId: String) {
print("Interstitial is being presented! placementId: \(placementId)")
}
func failedToPresent(placementId: String, error: PresentError) {
// If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
print("Interstitial failed to present. placementId: \(placementId), Reason: \(error.localizedDescription)")
}
func didRecordImpression(placementId: String, data: ImpressionData) {
print("Interstitial impression, with revenue: \(data.revenue). placementId: \(placementId)")
}
func willDismiss(placementId: String) {
print("Interstitial will be dismissed! placementId: \(placementId)")
}
func didDismiss(placementId: String) {
// If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
print("Interstitial dismissed! placementId: \(placementId)")
}
func didClick(placementId: String) {
print("Interstitial clicked! placementId: \(placementId)")
}
}
InterstitialViewController.m
@import UIKit;
@import XMediatorObjC;
@interface InterstitialViewController ()<X3MInterstitialAdsDelegate>
@end
@implementation InterstitialViewController
- (void)viewDidLoad {
[super viewDidLoad];
}
- (IBAction)startButtonTouchUpInside:(id)sender {
[X3MXMediatorAds startWithAppKey:@"<your-app-key>"
callback:^(NSError * _Nullable error) {
[X3MXMediatorAds.interstitial addDelegate:self];
// Start loading an interstitial. Subsequent loads or retries are handled by the sdk
[X3MXMediatorAds.interstitial loadWithPlacementId:@"<placement-id>"];
}];
}
- (IBAction)presentButtonTouchUpInside:(id)sender {
if (X3MXMediatorAds.interstitial.isReady) {
[X3MXMediatorAds.interstitial presentFromViewController:self];
}
}
#pragma mark - Ads Delegate
- (void)didLoadWithPlacementId:(NSString * _Nonnull)placementId result:(X3MLoadResult * _Nonnull)result {
NSLog(@"Interstitial loaded! placementId: %@", placementId);
}
- (void)didPresentWithPlacementId:(NSString * _Nonnull)placementId {
NSLog(@"Interstitial is being presented! placementId: %@", placementId);
}
- (void)failedToPresentWithPlacementId:(NSString * _Nonnull)placementId error:(NSError * _Nonnull)error {
// If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
NSLog(@"Interstitial failed to present. placementId: %@. Reason %@", placementId, error);
}
- (void)didRecordImpressionWithPlacementId:(NSString * _Nonnull)placementId data:(X3MImpressionData * _Nonnull)data {
NSLog(@"Interstitial impression, with revenue: %f. PlacementId %@", data.revenue, placementId);
}
- (void)willDismissWithPlacementId:(NSString * _Nonnull)placementId {
NSLog(@"Interstitial will be dismissed! placementId: %@", placementId);
}
- (void)didDismissWithPlacementId:(NSString * _Nonnull)placementId {
// If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
NSLog(@"Interstitial dismissed! placementId: %@", placementId);
}
- (void)didClickWithPlacementId:(NSString * _Nonnull)placementId {
NSLog(@"Interstitial clicked! placementId: %@", placementId);
}
@end