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

Tags

Tags are a powerful tool which enable you to monitor the performance of ads in a particular location or logical section of your app. If an ad with a particular tag underperforms or you later find is too annoying to your users, you can turn it off from the dashboard, saving you the hastle of resubmitting your app to the App Store. In addition, you do not need to set up tag names on your dashboard prior to writing code: as soon as we see a new tag, we will show you the stats in your app's dashboard.

Before you can show an ad with a tag, you must fetch the ad at the earliest point to when you know you will need to show that ad.

In the following example, we fetch an ad that will be shown after the game's level is complete:

[HZInterstitialAd fetchForTag:@"post-level"];
HZInterstitialAd.fetchForTag("post-level")

Then, when you want to display the post-level ad, do so by passing the same "post-level" string to display:

[HZInterstitialAd showForTag:@"post-level"];
HZInterstitialAd.showForTag("post-level")

If you want to find out if an ad with a particular tag is ready to display, you can use the isAvailable method and pass your tag as the first parameter:

NSString *postLevelTagName = @"post-level";
if ([HZInterstitialAd isAvailableForTag:postLevelTagName]) {
    [HZInterstitialAd showForTag:postLevelTagName];
}
let postLevelTagName = "post-level"
if HZInterstitialAd.isAvailableForTag(postLevelTagName) {
    HZInterstitialAd.showForTag(postLevelTagName)
}

As of iOS SDK version 9.1.0, there is also a convenience method to fetch for multiple tags at once. A separate callback to one of the delegate methods relevant to fetching (didReceiveAdWithTag: or didFailToReceiveAdWithTag:) will still be made for each tag.

[HZInterstitialAd fetchForTags:@[@"post-level", @"main menu", @"game over"]];
HZInterstitialAd.fetchForTags(["post-level", "main menu", "game over"])

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];
[HZVideoAd setDelegate:delegate];
[HZIncentivizedAd setDelegate:delegate];
[HZOfferWallAd setDelegate:delegate];
HZInterstitialAd.setDelegate(delegate)
HZVideoAd.setDelegate(delegate)
HZIncentivizedAd.setDelegate(delegate)
HZOfferWallAd.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)

Note that the object the NSNotifications are sent from is the Class of the respective ad unit that the notification is about. An example use case of this feature: you can only listen for events about video ads shown via HZVideoAd by setting the object in your addObserver call as follows:

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didShowAdNotificationHandler:) name:HZMediationDidShowAdNotification object:[HZVideoAd class];

NSNotificationCenter.defaultCenter().addObserver(self, selector:"didShowAdNotificationHandler:" name:HZMediationDidShowAdNotification object:HZVideoAd.self)

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.

Server-side Incentivized Callbacks

Heyzap can send you a secure, server-side confirmation every time a user completes a rewarded video. More information on this option can be found here.

If you are using these server-side callbacks for rewarded video, you can also send an arbitrary string of data through our SDK that will be passed along to your server as a param in the callback URL. To set this string of data, use this method to show incentivized videos and set the property incentivizedInfo to whatever you need passed to your server:

HZShowOptions *options = [HZShowOptions new];
//options.tag = @"tag"; // use this property to show for a tag if you were using `[HZIncentivizedAd showForTag:]` before
options.incentivizedInfo = @"enter in your string here, it will be passed to your server";
[HZIncentivizedAd showWithOptions:options];
let options:HZShowOptions = HZShowOptions()
//options.tag = "tag"; // use this property to show for a tag if you were using `HZIncentivizedAd.showForTag()` before
options.incentivizedInfo = "enter in your string here, it will be passed to your server"
HZInterstitialAd.showWithOptions(options)

Remote Data

To configure data to send to your app via our SDK, go to your Dashboard, select a game, and then choose "Publisher Settings" from the navigation menu on the left. By setting up your own JSON blob under the setting "Remote Data JSON", you can send any data you need to your app through our SDK. The code below shows how to access this custom data via the SDK.

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(remoteDataRefreshed:) name:HZRemoteDataRefreshedNotification object:nil];

...

// Called when the data has been refreshed (it's cached from previous app
//   loads, so listen for this notification to know the data is fresh. We
//    will attempt to refresh it soon after you start the SDK.)
- (void) remoteDataRefreshed: (NSNotification *)notification {
    NSDictionary *remoteData = notification.userInfo;
}

...

// Only use this after receiving the above notification, unless you don't
//    care how old the data might be (since we cache it)
NSDictionary *remoteData = [HeyzapAds remoteData];
NSNotificationCenter.defaultCenter().addObserver(self, selector:"remoteDataRefreshed:" , name:HZRemoteDataRefreshedNotification, object:nil);

...

// Called when the data has been refreshed (it's cached from previous app loads, so listen for this notification to know the data is fresh. We will attempt to refresh it soon after you start the SDK.)
func remoteDataRefreshed(notification:NSNotification) {
    let remoteData = notification.userInfo;
}

...

// Only use this after receiving the above notification, unless you don't care how old the data might be (since we cache it)
let remoteData = HeyzapAds.remoteData();

Example use case: Variable rewards for incentivized ads

If you'd like to be able to change the in-app currency type and/or amount that you will give users after they successfully complete an incentivized video ad, you can just set up this Remote Data object with something like this:

{
    "incentivized_reward":
    {
        "currency":"Gems",
        "amount":10
    }
}

The NSDictionary you can access with the code examples above would, in this example, contain one key: incentivized_reward. The value at that key would be another NSDictionary with keys currency and amount.

Note: The top-level object of whatever JSON blob you choose to save on your Dashboard should be a JSON object ({}) and not a JSON array ([]).

In-App Purchase Tracking

(Note: This data will be used by an upcoming feature that will help you control ad placements after a user has made an in-app purchase.)

Automatic Tracking

By default, the SDK adds a PaymentTransactionObserver to the app's payment queue to track in-app purchases.

Manual Tracking

To disable automatic in-app purchase tracking, start the SDK with the HZAdOptionsDisableAutomaticIAPRecording:

[HeyzapAds startWithPublisherID:@"" andOptions:HZAdOptionsDisableAutomaticIAPRecording];
HeyzapAds.startWithPublisherID("", andOptions:HZAdOptions.DisableAutomaticIAPRecording)

The onIAPPurchaseComplete method can then be called to track specific in-app purchases:

[HeyzapAds onIAPPurchaseComplete:@"com.example.productId" 
           productName:@"Example Product" 
           price:[NSDecimalNumber decimalNumberWithString:@"12.34"]];
HeyzapAds.onIAPPurchaseComplete("com.example.productId" 
                                productName:"Example Product" 
                                price:NSDecimalNumber(string:"12.34"))

Note: This method only needs to be called if automatic in-app purchase tracking is disabled.

Calling 3rd-party networks directly

You can interact with 3rd party SDKs directly, but you'll need to check if they're initialized first:

if ([HeyzapAds isNetworkInitialized:HZNetworkChartboost]) {
    [Chartboost cacheInterstitial:@"myLocation"];
}
if HeyzapAds.isNetworkInitialized(HZNetworkChartboost) {
    Chartboost.cacheInterstitial("myLocation")
}

Currently Heyzap loads networks lazily (networks are not initialized until we need to fetch an ad from them to optimize disk/bandwidth/CPU/memory usage). We don't currently have a way for developers to initialize a certain network at the start of the app; please contact support@heyzap.com and we'll handle this manually for now.

3rd-party network delegate callbacks

Warning: When interacting with 3rd-party networks, if the network has a single, global delegate you cannot set that delegate property to your own object. Heyzap Mediation relies on receiving those delegate callbacks in order to function correctly. In order to work around this, there are 3 options:

  1. [Recommended] Use the [HeyzapAds setDelegate:forNetwork:] method. The object you set as the delegate will have all callbacks for that network forwarded to it. If you use this approach, you can use the same delegate methods that the network uses.
  2. [Recommended] Alternatively, don't use 3rd party callbacks; instead use non-delegate approaches. For example, using methods like [Chartboost hasInterstitial] instead of delegate callbacks like didCacheInterstitial:.
  3. Use the [HeyzapAds networkCallbackWithBlock:] method. This method allows you to set a block that will be called for each callback. The block provides the network name and the type of callback that was triggered (String constants for possible network names (e.g. HZNetworkChartboost) and callbacks (e.g. HZNetworkCallbackShow) are available in HeyzapAds.h). This approach is primarily for developers who want a string-based interface, which allows easier interaction with frameworks like Unity and Adobe Native Extension.
  4. Use the HZMediationNetworkCallbackNotification, which will be sent every time the block sent to [HeyzapAds networkCallbackWithBlock:] (see above) is called. This allows you to have multiple listeners for these events, instead of just one block. The object of the notification will be the network name string constant (e.g. HZNetworkChartboost), which will also be provided in the userInfo dictionary with the key HZNetworkNameUserInfoKey. The callback string (e.g. HZNetworkCallbackShow) will be provided in the userInfo dictionary with the key HZNetworkCallbackNameUserInfoKey.

Chartboost Cross-Promo

You can call Chartboost directly to use cross-promo. See "Calling 3rd-party networks directly" above.

API Documentation

You can view our full API documentation.

Install-Tracking Only

If you are integrating the Heyzap SDK only to provide install attribution, your setup is simple. Just use this code to start the Heyzap SDK:

[HeyzapAds startWithPublisherID:@"" 
                     andOptions:HZAdOptionsInstallTrackingOnly];
HeyzapAds.startWithPublisherID("", andOptions:HZAdOptions.InstallTrackingOnly)

Starting the Heyzap SDK with this option will disable all of Heyzap's advertising functionalities while reporting new installations of your app. (Note: previous versions of the Heyzap SDK had a now-deprecated option called HZAdOptionsAdvertiserOnly, which did the same thing as HZAdOptionsInstallTrackingOnly.)

Test Devices

Advertisers are able to target certain countries on Heyzap's network. Depending on which country you live in, there may be a limited number of advertisers targetting you, and video ads may not be available at all in your country.

For testing purposes, you can set your own device to receive ads from all advertisers on your App Settings page, which can be found on the Revenue dashboard for your app.


More Information:

To view an Example App, click here.
To go back to basic iOS SDK setup, click here.
To set up Mediation, click here.