Unity SDK 9

Requirements

  • The Heyzap Unity3D SDK supports Android 3.0 (API level 11)+ when building for Android.
  • The Heyzap Unity3D SDK supports iOS 7.0+ when building for iOS.
  • The Heyzap Unity3D SDK supports Unity 5.
    • SDK version 9.11.5 was the last stable release to support Unity 4 without manual effort.
  • The Heyzap Unity3D SDK can only build iOS projects from a Mac - you cannot build your Xcode project on Windows.

Example App

To see a working Unity app with Heyzap already integrated, check out our example Unity 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.12.1 / Non Beta v9.11.5
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:

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

Step 2. Download the SDK

Upgrading the Heyzap SDK and using Unity 5.0, 5.1, or 5.2? Delete the old Heyzap SDK from Unity first - the files are in these directories:

  • Editor/Heyzap/
  • Plugins/Heyzap/
  • Plugins/Android/Heyzap/
  • Plugins/iOS/Heyzap/

Deleting the SDK before upgrading will avoid an issue where Unity 5.0, 5.1, and 5.2 append " 1" to duplicate file names instead of replacing them like Unity 4 did. This issue is fixed in Unity 5.3.

SDK v9.12.1 (Beta)

Step 3. Add the SDK to your project

Unzip the downloaded files and add Heyzap.unitypackage to your open Unity project. You can do this by either double-clicking the file, or following the steps outlined in the below screenshot:

Add Unity Package to project.

Step 3a. Android-Specific Setup

Additionally, install the Google Mobile Ads plugin's PlayServicesResolver by downloading the linked file and double-clicking it. This Unity plugin, and the dependencies file we include with it, will include the needed Google Play Services dependencies required by Heyzap and third-party networks into your application by copying them from your local machine's Google Play Services installation.

After installing the plugin, set your Unity Editor's platform to Android, and click Resolve Client Jars in the Unity Editor menu bar, under Assets > Play Services Resolver > Android Resolver.

Step 3b. iOS-Specific Setup

If you are using Unity 4, you will have to move all of the files that are in Plugins/iOS/Heyzap/ up one folder to Plugins/iOS/, because Unity 4 does not support having subdirectories in the Plugins/iOS folder.

iOS 9 added multitasking support, and it interferes with an ad's ability to set the orientation of the app. In order for ads to show properly, you need to disable this feature. Since Unity 5.2.2p1, you can do this from the Player Settings by checking the box labeled "Requires Fullscreen":

Disable iOS Multitasking

If you do not have this feature because you're using an older version of Unity, refer to our iOS docs on how to disable this feature from within Xcode.

Step 4. Add 3rd-party SDKs to your Unity 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. Add the HZMediationImports.m file to Unity (Only required for iOS)

This file imports the frameworks required by the 3rd-party SDKs you've chosen above. Download this file and add it to the Plugins/iOS/Heyzap/ directory in Unity 5, or the Plugins/iOS/ directory in Unity 4.

Step 6. Replace your Android Manifest (Only required for Android)

Download your Android Manifest

Put this file in the Plugins/Android directory of your Unity project.

Step 7. Initialize the SDK

When your game starts, run the following code to start the Heyzap SDK:

using Heyzap; // make sure to include this line at the top of any C# file you use our SDK from

// 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.SetUserGender(HZDemographics.Gender.FEMALE); // things like location, birthday, education, and more can be set as well
 
// Your Publisher ID is: 
HeyzapAds.Start("", HeyzapAds.FLAG_NO_OPTIONS);
import Heyzap; // make sure to include this line at the top of any JS file you use our SDK from

// 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.SetUserGender(HZDemographics.Gender.FEMALE); // things like location, birthday, education, and more can be set as well

// Your Publisher ID is: 
HeyzapAds.Start("", HeyzapAds.FLAG_NO_OPTIONS);

Step 8: Post Xcode project generation (iOS Only)

Our build script typically adds libz, libsqlite3 and libxml2. Since Xcode 7 we've had some rare cases in which these libraries are not being added; you may have to add them manually in these cases. To add them in Xcode manually, go to the General tab of your Xcode project's target settings page and add them via the Linked Frameworks and Libraries section:

Add Libraries

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 9: 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 this method after you start the SDK:

HeyzapAds.ShowMediationTestSuite();

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 10. Show Ads

Methods you call on the Heyzap SDK will automatically dispatch to one of your enabled 3rd-party SDKs; a call to Show will determine which ad network to use and then show an ad.

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
HZInterstitialAd.Show();

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

HZVideoAd.Fetch();

To show a video after fetching:

// Later, such as after a level is completed
if (HZVideoAd.IsAvailable()) {
    HZVideoAd.Show();
}

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

HZIncentivizedAd.Fetch();

To show a rewarded video after fetching:

if (HZIncentivizedAd.IsAvailable()) {
    HZIncentivizedAd.Show();
}

Banner Ads

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.

To show a banner ad, you must specify a position using one of the provided constants (HZBannerShowOptions.POSITION_TOP or HZBannerShowOptions.POSITION_BOTTOM) and the HZBannerShowOptions object:

HZBannerShowOptions showOptions = new HZBannerShowOptions();
showOptions.Position = HZBannerShowOptions.POSITION_TOP;
HZBannerAd.ShowWithOptions(showOptions);
var showOptions : HZBannerShowOptions = new HZBannerShowOptions();
showOptions.Position = HZBannerShowOptions.POSITION_TOP;
HZBannerAd.ShowWithOptions(showOptions);

To hide a currently showing banner (hidden banners can be shown again later):

HZBannerAd.Hide();

You can also destroy the current banner ad, which will force a new one to be mediated and fetched on the next call to ShowWithOptions. To destroy the current banner (whether it is visible or not):

HZBannerAd.Destroy();

Offer Wall Ads

The Heyzap SDK provides access to the Fyber Offer Wall as of SDK version 9.12.0 and above. The Offer Wall allows your users to complete certain activities in exchange for in-game currency. We have another docs page specifically about Offer Wall ads.

The Back Button

Some networks need a handler for the back button on Android devices. Heyzap proxies this with a single function, which can be used like this:

public void Update() {
  if (Input.GetKeyUp(KeyCode.Escape)) {
    if (HeyzapAds.OnBackPressed())
      return;
    else
      Application.Quit(); // or whatever your normal back button code is
  }
}

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


More Information:

To view an Example App, click here.
To view Advanced Features, click here.