iOS SDK 9

Watch a video tutorial for integrating the iOS SDK.

Requirements

  • Heyzap works on iOS 7.0 and above. (SDK version 9.2.8 was the last stable release to support iOS 6.0)

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.

Beta v9.11.0 / Non Beta v9.10.1
Our Beta SDK is less tested, but it has all our newest features. Should you have any issues with either version, please report them to support@heyzap.com.

Network Selection:

Step 2. Download the SDK

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

SDK v9.11.0 (Beta)

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

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

// InterstitialAds are automatically fetched from our server
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZInterstitialAd showWithOptions:options];
// InterstitialAds are automatically fetched from our server
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, and after showing a video, call fetch
[HZVideoAd fetch];
// As early as possible, and after showing a video, 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, and after showing a rewarded video, call fetch
[HZIncentivizedAd fetch];
// As early as possible, and after showing a rewarded video, 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

To use banner ads, you must be using AdMob, Facebook Audience Network, or 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.

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.