iOS SDK 9

Watch a video tutorial for integrating the iOS SDK.

Requirements

  • Heyzap works on iOS 8 / Xcode 8 and above. (SDK version 9.12.7 was the last stable release to support iOS 7/Xcode 7)
    • No update currently required for iOS 11 support

Example App

To see a working iOS app that has each of the networks we support already integrated, check out our example iOS app on GitHub.

Step 1. Configure Dynamic Documentation

Select the version of the Heyzap SDK you wish to view documentation for, and then select the networks you are integrating. The documentation on this page will update with specific instructions that may apply to your selections.

Network Selection:

Step 2. Download the SDK

The SDK includes Heyzap, as well as wrappers for all 3rd-party networks.

SDK v9.15.3

Using Xcode 6? Use this Heyzap SDK and these third party SDKs.

Step 3. Add the SDK to your project

Unzip the downloaded file to get our iOS framework. Select this framework and any additional files and add them to your project. Make sure to have 'Copy Items' checked.

Add Framework to Xcode

Step 4. Add 3rd-party SDKs to your project

AdColony

AdMob

Apple iAd

AppLovin

Chartboost

Domob

Facebook Audience Network

Fyber Exchange

HyprMX

InMobi

Leadbolt

MdotM

MoPub

UnityAds

Vungle

If you haven't already, use our Integration Wizard to setup the 3rd-party networks you want to use with mediation.

The Heyzap SDK will automatically detect and initialize the SDKs from 3rd-party networks. Some 3rd-party networks fail when initialized multiple times. Please do not initialize or otherwise directly interact with 3rd-party networks mediated by Heyzap.

Step 5. Configure your Xcode project

Import the following frameworks by pasting this code into your AppDelegate (you may need to enable modules in your Build Settings). (If you can't enable modules because you're e.g. using [Objective]-C++, add these frameworks to the Linked Frameworks and Libraries section in Xcode).

No additional configuration is needed for Heyzap's SDK, but you may need to enable modules in your Build Settings. (If you can't enable modules because you're e.g. using [Objective]-C++, add these frameworks to the Linked Frameworks and Libraries section in Xcode).

From the General tab of your Xcode project's target settings page, link against these libraries:

Add Libraries

Also from the General tab of your Xcode project's target settings page, check the box labeled "Requires full screen" (this disables multitasking support, which needs to be disabled for ads to be able to set the orientation of their views):

Disable Multitasking

From the Build Settings tab of your Xcode project's target settings page, add the following to "Other Linker Flags":

Add Linker Flags

App Transport Security

iOS 9 added App Transport Security (ATS), which requires apps to use HTTPS for all networking. Starting in 2017, Apple will require that all apps use ATS unless they state a reason they can't.

All of the networks you have selected so far in the dynamic documentation (see the top of the page) fully support ATS, and do not require any additional configuration. Please ensure you've selected each network above that you will be integrating so this documentation can change if necessary.

Disable App Transport Security

iOS 9 added App Transport Security (ATS), which requires apps to use HTTPS for all networking. Starting in 2017, Apple will require that all apps use ATS unless they state a reason they can't.

Not all of your selected networks are ready for this requirement yet, so you'll need to add some exceptions. The following networks are requiring these exceptions:

Using an advertising SDK that needs to be excluded is considered a valid reason for needing this exception - in Apple's ATS docs, one acceptable reason is that your app must connect to a server managed by another entity that does not support secure connections. When your app is reviewed, you can provide this reason for needing the exceptions.

To add the necessary exceptions for the networks you chose, add the following entries to your app's Info.plist file:



Disable ATS

Register Custom URL Schemes

Starting in iOS 9, apps must register what URL schemes they can pass to [UIApplication canOpenURL:]. Add these URL schemes to your Info.plist:



Application URL Queries

Step 5. Initialize the SDK

In your application delegate's application:didFinishLaunchingWithOptions: method, start the Heyzap SDK:

#import <HeyzapAds/HeyzapAds.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //    Demographic information about your app's current user can optionally be used to increase CPMs. If you have it, provide it at any time (but also as early as possible) like so:
    //    HZDemographics *demographics = [HeyzapAds demographicInformation];
    //    demographics.location = foo; // things like birthday, education, gender, and more can be set as well
    
    // Your Publisher ID is: 
    [HeyzapAds startWithPublisherID: @""];
    return YES;
}

Swift users need to import Heyzap into the Bridging Header file. If you don't already have one, create a new Objective-C file in your project and Xcode will offer to generate one for you. Import Heyzap into this file:

#import <HeyzapAds/HeyzapAds.h>

then start Heyzap:

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  
    //    Demographic information about your app's current user can optionally be used to increase CPMs. If you have it, provide it at any time (but also as early as possible) like so:
    //    let demographics = HeyzapAds.demographicInformation()
    //    demographics.location = foo // things like birthday, education, gender, and more can be set as well
    
    // Your Publisher ID is: 
    HeyzapAds.startWithPublisherID("")

    return true
}

Step 7: Test your 3rd-Party Integrations (Optional)

The mediation SDK comes with a Mediation Test Suite that you can use to test each of the networks you've chosen:

The first screen lets you pick a network. Once you choose a network, you'll see if:

  1. The network is installed correctly.
  2. The network has valid credentials on your dashboard.
  3. The network is enabled on your dashboard.

From here, you can select a type of ad (Interstitial, Video, Incentivized, or Banner), fetch that ad, and then display it.

To use the Mediation Test Suite, simply call presentMediationDebugViewController after you start the SDK and have setup a root view controller:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [HeyzapAds startWithPublisherID: @""];

    // Create UIWindow
    // Set rootViewController

    [HeyzapAds presentMediationDebugViewController];
}
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    HeyzapAds.startWithPublisherID("")

    // Create UIWindow
    // Set rootViewController

    HeyzapAds.presentMediationDebugViewController()
    return true
}

At this point, you should launch the Mediation Test Suite and verify that each network you want to use has the correct credentials and shows ads correctly.

Step 8. Show Ads

Methods you call on the Heyzap SDK will automatically dispatch to your enabled 3rd-party SDKs; a call to showAd will iterate over ad networks in order of expected CPM until it finds one that has an ad, optimizing CPM and fill rate. Use the code below to display your preferred ad format:

Interstitial Ads

While you can call fetch for interstitial ads manually without causing any harm, our SDK will automatically try to fetch for the default tag when the SDK starts, and also after every ad shows, by default.

// Interstitial Ads are automatically fetched from our server by default on SDK start and after an ad shows
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZInterstitialAd showWithOptions:options];
// Interstitial Ads are automatically fetched from our server by default on SDK start and after an ad shows
let options = HZShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
HZInterstitialAd.showWithOptions(options)

Video Ads

As early as possible after starting the SDK, call fetch to fetch a video ad if your app will use them. You must do this because videos are not fetched automatically when the SDK is started, unlike our interstitial ads. However, video ads will autofetch after being shown the first time as long as autofetching is left enabled (see our Advanced docs for more about autofetching).

// As early as possible after starting the SDK, call fetch
[HZVideoAd fetch];
// As early as possible after starting the SDK, call fetch
HZVideoAd.fetch()
// Later, such as after a level is completed
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZVideoAd showWithOptions:options];
// Later, such as after a level is completed
let options = HZShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
HZVideoAd.showWithOptions(options)

Rewarded Video Ads

As early as possible after starting the SDK, call fetch to fetch a rewarded video ad if your app will use them. You must do this because rewarded videos are not fetched automatically when the SDK is started, unlike our interstitial ads. However, rewarded video ads will autofetch after being shown the first time as long as autofetching is left enabled (see our Advanced docs for more about autofetching).

// As early as possible after starting the SDK, call fetch
[HZIncentivizedAd fetch];
// As early as possible after starting the SDK, call fetch
HZIncentivizedAd.fetch()
// Later, such as after a level is completed
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZIncentivizedAd showWithOptions:options];
// Later, such as after a level is completed
let options = HZShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
HZIncentivizedAd.showWithOptions(options)

Banner Ads

Heyzap offers banner ads through its in-house network, Heyzap Exchange. We also mediate banners from AdMob, Facebook Audience Network, Mopub, and InMobi.

Note: Most banner networks have a setting on their dashboard to automatically refresh at a given time interval. If you want to use this feature, it is strongly recommended that you use the same time interval on all of the banner networks you are using. Different refresh rates for different networks can result in confusing impression statistics.

HZBannerAdOptions *options = [[HZBannerAdOptions alloc] init];
[HZBannerAd placeBannerInView:self.view
            position:HZBannerPositionBottom
            options:options
            success:^(HZBannerAd *banner) {
            
            }
            failure:^(NSError *error) {
              NSLog(@"Error = %@",error);
            }
];
let options = HZBannerAdOptions()
HZBannerAd.placeBannerInView(self.view, position: HZBannerPosition.Bottom, options:options, success: {
      (banner) in
    }, failure: {
      (error) in println("Error is \(error)")
    }
)

For details on configuring the sizes of banners, more customizable placement of banners, callbacks, and more, please see our Banners Guide. Our Objective-C API documentation also covers this information.

Offer Wall Ads

The Heyzap SDK provides access to the Fyber Offer Wall as of SDK version 9.12.0. The Offer Wall allows your users to complete certain activities in exchange for in-game currency.

Fetch

To fetch an Offer Wall ad:

[HZOfferWallAd fetch];
HZOfferWallAd.fetch()

Show

To show an Offer Wall ad:

HZOfferWallShowOptions *options = [HZOfferWallShowOptions new];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
options.shouldCloseAfterFirstClick = YES; // auto-close after first offer interaction?
options.animatePresentation = YES;

[HZOfferWallAd showWithOptions:options];
let options = HZOfferWallShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
options.shouldCloseAfterFirstClick = YES // auto-close after first offer interaction?
options.animatePresentation = YES

HZOfferWallAd.showWithOptions(options)

See our detailed Offer Wall docs for more code examples on how to reward the user for offer wall interactions.

All good? Head over to your mediation dashboard to view revenue, impressions, eCPM, network credentials, and more.


More Information:

To learn more about Native Ads, click here.
To view an Example App, click here.
To go to basic iOS SDK setup, click here.
To view Advanced Features, click here.