Interstitial Ads

This guide shows how to display Interstitial Ads in your application.

What are Interstitial Ads?

Interstitial Ad Units are full-screen, interactive ads designed to be placed between content at a natural transition point.

How to Display Interstitial Ads

Integrate & Initialize HyprMX

Before you start, make sure you have correctly integrated and initialized the HyprMX SDK. To integrate and initialize HyprMX, see our Setup Guide.

Loading Interstitial Ads

HyprMX utilizes placements to load and display an ad. Placements are used to represent a point in your application's workflow where you'd like to show an ad. To load an ad to a placement, follow the steps below.

If you don't have your placement information, please reach out to your account manager to configure your interstitial placements. In return, they will provide the names of the new placements.

1. Use the getPlacement API to retrieve a placement from HyprMX.

Swift

let interstitialPlacement = HyprMX.getPlacement("INTERSTITIAL")

Objective-C

HyprMXPlacement *interstitialPlacement = [HyprMX getPlacement:@"INTERSTITIAL"];

2. To check for availability, run the following.

Swift

if await interstitialPlacement.loadAd() {
    print("Ad Available")
}

Objective-C

[interstitialPlacement loadAdWithCompletion:^(BOOL success) {
    if (success) {
        NSLog(@"Ad Available")
    }
}];

3. To receive notification that the loaded ad has expired, implement the placement HyprMXPlacementExpiredDelegate

Swift

/** Called when ad loaded is no longer available for this placement */
func adExpired(placement: HyprMXPlacement) {
}

Objective-C

/** Called when ad loaded is no longer available for this placement */
- (void)adExpiredForPlacement:(HyprMXPlacement *)placement {
}

Set the delegate to your placement:

Swift

placement.expiredDelegate = myPlacementExpiredDelegateInstance

Objective-C

placement.expiredDelegate = myPlacementExpiredDelegateInstance;

HyprMX holds a weak reference to the placement expired delegate, so you must be sure to retain the delegate.

Displaying Interstitial Ads

1. Before calling showAdFromViewController: on a placement you should confirm the ad state is still valid by running the following.

Swift

interstitialPlacement.isAdAvailable

Objective-C

[interstitialPlacement isAdAvailable]

Once an ad network has an available video, you will be ready to show the video to your users.

2. You can supply your current UIViewController when calling showAdFromViewController:delegate: for HyprMX to present from, or pass nil and HyprMX will present from the keyWindow. If your App supports multi-window, it is recommended to always provide a View Controller to present from.

Swift

if interstitialPlacement.isAdAvailable {
  interstitialPlacement.showAd(from: self, delegate: self)
}

Objective-C

if ([interstitialPlacement isAdAvailable]) {
  [interstitialPlacement showAdFromViewController:self delegate:self];
}

showAdFromViewController:delegate: will begin the presentation of an ad.

3. For the best user experience, implement a delegate.

Before you display the ad, make sure to pause any game action, including audio, to ensure the best experience for your users. You can disable them when you get the adWillStartForPlacement:/adWillStart(placement:) callback and re-enable when you get adDidCloseForPlacement:/adDidClose(placement:).

Swift

/** Called immediately before attempting to present an ad. */
func adWillStart(placement: HyprMXPlacement) {
}

/** Called upon conclusion of any ad presentation attempt */
func adDidClose(placement: HyprMXPlacement, didFinishAd finished: Bool) {
}

/** Called when an error occurs during ad presentation. */
func adDisplayError(_ error: Error, placement: HyprMXPlacement) {
}

/** Called when an ad has become visible on screen */
func adImpression(placement: HyprMXPlacement) {
}

Objective-C

/** Called immediately before attempting to present an ad. */
- (void)adWillStartForPlacement:(HyprMXPlacement *)placement {
}

/** Called upon conclusion of any ad presentation attempt */
- (void)adDidCloseForPlacement:(HyprMXPlacement *)placement didFinishAd:(BOOL)finished {
}

/** Called when an error occurs during ad presentation. */
-(void)adDisplayError:(NSError *)error placement:(HyprMXPlacement *)placement {
}

/** Called when an ad has become visible on screen */
- (void)adImpression:(HyprMXPlacement *)placement {
}

If you'd like, we can send server-to-server calls when ads are completed. Contact your account manager at HyprMX for more details.