Unified Platform – iOS Advanced Features

Manual Fetching

In some scenarios, you may wish to disable our automatic fetching of ads. You might do this if you are putting Heyzap into a waterfall with other ad networks, using another mediation tool, or are worried about the performance or bandwidth impact of fetching at critical times in your app.

To put the Heyzap SDK into manual fetching mode, start the SDK with the following options flag:

[HeyzapAds startWithPublisherID: @"" andOptions: HZAdOptionsDisableAutoPrefetching];
HeyzapAds.startWithPublisherID("", andOptions: HZAdOptions.DisableAutoPrefetching)

Then, to fetch an ad, do the following:

[HZInterstitialAd fetch];
HZInterstitialAd.fetch()

After succesfully fetching an ad, your delegate will receive the didReceiveAdWithTag: callback (described below, whereby it is safe to show an ad:

if ([HZInterstitialAd isAvailable]) {
    [HZInterstitialAd show]; 
}
if HZInterstitialAd.isAvailable() {
    HZInterstitialAd.show()
}

Our autofetching logic, when left enabled, will automatically fetch in the following scenarios:

  • When the SDK is started, an HZInterstitialAd will be fetched with the default tag.
  • Whenever an ad is closed, of any type, another ad will be fetched with the same tag and type as the ad just shown.

Delegate methods will always be called, whether ads are autofetched or fetched manually.

Important: It is highly recommended to fetch as far in advance of showing an ad as possible. For example, you may want to fetch when a level starts, or after a previous ad has been shown. To do the latter, you can call fetch in the didHideAdWithTag: callback (described below).

Callbacks

Heyzap supports three forms of callbacks. You can receive block-based callbacks when showing and fetching a specific ad, delegate callbacks that are called for all ads for each ad unit, or NSNotification-based callbacks.

Block-based callbacks

You can receive block-based callbacks for individual calls to our various fetch and show methods. Here's an example of how to do so with HZInterstitialAd when showing an ad:

[HZInterstitialAd showForTag: @"post-level" completion:^(BOOL result, NSError *error) {
    if (result) {
        NSLog(@"Success showing ad!");
    } else {
        NSLog(@"Failure showing an ad; error = %@",error);
    }
}];
HZInterstitialAd.showForTag("post-level", completion: { (success, error) -> Void in
    if success {
        print("success showing an ad")
    } else {
        print("error showing an ad; error was %@",error)
    }
})

The completion block can also be set on the HZShowOptions object that is passed as a parameter to showWithOptions:, if you need to use that method instead.

HZAdsDelegate and NSNotification callbacks

You can receive callbacks when certain ad events occur on each ad unit by implementing the HZAdsDelegate protocol. Alternatively, you can receive callbacks for all of the HZAdsDelegate events via NSNotifications instead, which allows you to have multiple listeners for these events at the same time.

To designate a class as the HZAdsDelegate for an ad unit, set the delegate on the ad unit class:

[HZInterstitialAd setDelegate: delegate];
[HZIncentivizedAd setDelegate: delegate];
HZInterstitialAd.setDelegate(delegate)
HZIncentivizedAd.setDelegate(delegate)

To listen for the NSNotifications for each delegate method instead, subscribe to any/all of the corresponding notifications:

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didShowAdNotificationHandler:) name:HZMediationDidShowAdNotification object:nil];
// Note: If the observer does not inherit from an Objective-C object, you must prefix the method specified in the `selector:` argument with `@objc` in order to use it as a selector.
NSNotificationCenter.defaultCenter().addObserver(self, selector:"didShowAdNotificationHandler:" name:HZMediationDidShowAdNotification object:nil)

See the table below for the method signature, NSNotification name and info, and description of each delegate callback.

HZAdsDelegate NSNotification NSNotification userInfo Keys Description
didReceiveAdWithTag: HZMediationDidReceiveAdNotification
  • HZAdTagUserInfoKey
Sent when an ad has been loaded and is ready to be displayed, either because we autofetched an ad or because you called fetch yourself.
didFailToReceiveAdWithTag: HZMediationDidFailToReceiveAdNotification
  • HZAdTagUserInfoKey
Sent when an ad has failed to load. This is sent with when we try to autofetch an ad and fail, and also in response to calls you make to fetch ads that fail. Some of the possible reasons for fetch failures:
  • Incentivized ad rate limiting (see your app's Publisher Settings dashboard)
  • None of the available ad networks had any fill
  • Network connectivity
  • The given ad tag is disabled (see your app's Publisher Settings dashboard)
  • One or more of the segments the user falls into are preventingan ad from being fetched (see your Segmentation Settings dashboard)
didShowAdWithTag: HZMediationDidShowAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Sent when an ad has been displayed. This is a good place to pause your app, if applicable.
didFailToShowAdWithTag:andError: HZMediationDidFailToShowAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey (if available)
  • NSUnderlyingErrorKey (if available)
Sent when you call show, but there isn't an ad to be shown. Includes an NSError object describing the reason why. Some of the possible reasons for show errors:
  • No qualifying ads were fetched before attempting to show an ad
  • [HeyzapAds pauseExpensiveWork] was called, which pauses expensive operations like SDK initializations and ad fetches, and [HeyzapAds resumeExpensiveWork] has not yet been called
  • The given ad tag is disabled (see your app's Publisher Settings dashboard)
  • An ad is already showing
  • A recent IAP is blocking ads from being shown (see your app's Publisher Settings dashboard)
  • One or more of the segments the user falls into are preventing an ad from being shown (see your Segmentation Settings dashboard)
  • Incentivized ad rate limiting (see your app's Publisher Settings dashboard)
  • One of the mediated SDKs reported it had an ad to show but did not display one when asked (a rare case)
  • The SDK is waiting for a network request to return before an ad can show
didClickAdWithTag: HZMediationDidClickAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Sent when an ad has been clicked.
didHideAdWithTag: HZMediationDidHideAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Sent when an ad has been removed from view. This is a good time to fetch another ad, if autofetching is disabled.
willStartAudio: HZMediationWillStartAdAudioNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
The ad about to be shown will need audio. Mute any background music.
didFinishAudio: HZMediationDidFinishAdAudioNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
The ad being shown no longer needs audio. Any background music can be resumed.

Incentivized Callbacks

As with interstitial and video ads, you can receive the HZAdsDelegate callbacks for when an ad is shown, hidden, clicked, and so on from HZIncentivizedAd. In addition to those callbacks, you can receive additional callbacks for when a rewarded ad is completed or left incomplete by implementing the HZIncentivizedAdDelegate protocol in your delegate class, or by observing the NSNotifications sent for each method in the protocol. See the table below for the method signature, NSNotification name and info, and description of each delegate callback.

HZIncentivizedAdDelegate NSNotification NSNotification userInfo Keys Description
didCompleteAdWithTag: HZMediationDidCompleteIncentivizedAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Sent when a user watches an incentivized ad all the way through. This can be sent before or after the didHideAdWithTag event - the ad may or may not still be showing when this is sent.
didFailToCompleteAdWithTag: HZMediationDidFailToCompleteIncentivizedAdNotification
  • HZAdTagUserInfoKey
  • HZNetworkNameUserInfoKey
Sent when a user fails to watch an incentivized ad all the way through. This can be sent before or after the didHideAdWithTag event - the ad may or may not still be showing when this is sent.

Incentivized Server-Side Callback Parameters

Starting with SDK 10.4.0, if you are hosting your own currency service, you can pass custom parameters through the Fyber platform when requesting incentivized ads. The custom parameters will be passed back to your server in the server-to-server callback when the incentivized ad is completed.

You can pass along up to 10 custom parameters (keys between [pub0, pub1, …, pub9]) with the request by calling the addCustomParameters: method of HZIncentivizedAd before executing a fetch. The parameters will persist for all future fetches unless overwritten.

[HZIncentivizedAd addCustomParameters:@{ @"pub0": @"value" }];