Interstitial Ads

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

Initialize HyprMX

To integrate and initialize HyprMX, see our Setup Guide.

Loading Interstitial Advertisements

Placements are objects that allow you to show interstitial advertisements. To show an advertisement, use the getPlacement API to retrieve a placement from HyprMX, then set a placementDelegate.

Please reach out to your account manager to configure your interstitial placements. In return, they will provide the names of the new placements.

Swift
Objective-C
Swift
let interstitialPlacement = HyprMX.getPlacement("INTERSTITIAL")
interstitialPlacement.placementDelegate = self
Objective-C
HyprMXPlacement *interstitialPlacement = [HyprMX getPlacement:@"INTERSTITIAL"];
interstitialPlacement.placementDelegate = self;

To check for availability, run the following:

Swift
Objective-C
Swift
interstitialPlacement.loadAd()
Objective-C
[interstitialPlacement loadAd];

loadAd() will call back to your placementDelegate with:

  • adAvailableForPlacement:/adAvailable(for placement:) when an ad is available.

  • adNotAvailableForPlacement:/adNotAvailable(for placement:) when there is no inventory.

To receive ad load and display status, implement the HyprMXPlacementDelegate:

Swift
Objective-C
Swift
/** Called in response to loadAd when there is an ad to show */
func adAvailable(for placement: HyprMXPlacement) {
}
/** Called in response to loadAd when there's no ad to show */
func adNotAvailable(for placement: HyprMXPlacement) {
}
/** Called when ad loaded is no longer available for this placement */
func adExpired(for placement: HyprMXPlacement) {
}
/** Called upon conclusion of any ad presentation attempt */
func adDidClose(for placement: HyprMXPlacement, didFinishAd finished: Bool) {
}
/** Called immediately before attempting to present an ad. */
func adWillStart(for placement: HyprMXPlacement) {
}
/** Called when an error occurs during ad presentation. */
func adDisplayError(_ error: Error, placement: HyprMXPlacement) {
}
Objective-C
/** Called in response to loadAd when there is an ad to show */
- (void)adAvailableForPlacement:(HyprMXPlacement *)placement {
}
/** Called in response to loadAd when there's no ad to show */
- (void)adNotAvailableForPlacement:(HyprMXPlacement *)placement {
}
/** Called when ad loaded is no longer available for this placement */
- (void)adExpiredForPlacement:(HyprMXPlacement *)placement {
}
/** Called upon conclusion of any ad presentation attempt */
- (void)adDidCloseForPlacement:(HyprMXPlacement *)placement didFinishAd:(BOOL)finished {
}
/** Called when user has earned a reward. */
- (void)adDidRewardForPlacement:(HyprMXPlacement *)placement rewardName:(NSString *)rewardName rewardValue:(NSInteger)rewardValue {
}
/** Called immediately before attempting to present an ad. */
- (void)adWillStartForPlacement:(HyprMXPlacement *)placement {
}
/** Called when an error occurs during ad presentation. */
-(void)adDisplayError:(NSError *)error placement:(HyprMXPlacement *)placement {
}

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

Displaying Interstitial Advertisements

Before calling showAdFromViewController: on a placement you should confirm the ad state is still valid:

Swift
Objective-C
Swift
interstitialPlacement.isAdAvailable()
Objective-C
[interstitialPlacement isAdAvailable]

When an ad is displaying, it is important to disable all in-game music and sounds so they do not interfere with the advertisements. You can disable them when you get the adWillStartForPlacement:/adWillStart(for placement:) callback and re-enable when you get the adDidCloseForPlacement:/adDidClose(for placement:).

You can supply your current UIViewController when calling showAdFromViewController: 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
Objective-C
Swift
if interstitialPlacement.isAdAvailable() {
interstitialPlacement.showAd(from: self)
}
Objective-C
if ([interstitialPlacement isAdAvailable]) {
[interstitialPlacement showAdFromViewController:self];
}

showAdFromViewController: will begin the presentation of an ad.

The ad will call back to your placementDelegate to provide you state on the ad display:

  • adWillStartForPlacement:/adWillStart(for placement:) is called immediately before attempting to present the ad to the UI.

  • adDidCloseForPlacement:/adDidClose(for placement:) is called when the ad is closed.

  • adDisplayErrorForPlacement:placement:/adDisplayError(_ error: Error, placement: HyprMXPlacement) is called when an error occurs presenting the ad, and will be followed by adDidCloseForPlacement:/adDidClose(for 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.