Unity SDK 9

SDK v9.8.0
SDK 9 supports the full range of Heyzap tools & features. SDK 10 (beta) provides access to the Fyber platform. Questions? Reach us at support@heyzap.com.

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. (SDK version 9.2.8 was the last stable release to support iOS 6.0)
  • The Heyzap Unity3D SDK supports both Unity 4 and Unity 5.
  • The Heyzap Unity3D SDK can only build iOS projects from a Mac - you cannot build the 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.

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

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 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 Jars in the Unity Editor menu bar, under Assets > Google Play Services.

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

HyprMX

InMobi

Leadbolt

MdotM

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 (SDK v9.1.7 and above)

// 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 (SDK v9.1.7 and above)

// 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

// Interstitial ads are automatically fetched
HZInterstitialAd.Show();

Video Ads

Videos must be fetched before they can be shown. As early as possible or after showing a video, call Fetch. Videos are not fetched automatically.

HZVideoAd.Fetch();

To show a video after fetching:

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

Rewarded Video Ads

Rewarded videos must be fetched before they can be shown. As early as possible or after showing a rewarded video, call Fetch. Rewarded videos are not fetched automatically.

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();

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.

Unified Platform – Unity SDK 10

SDK v10.3.1
SDK 9 supports the full range of Heyzap tools & features. SDK 10 (beta) provides access to the Fyber platform. Questions? Reach us at support@heyzap.com.

SDK 10 is the launch of our unified platform with Fyber and unifies the core features of Heyzap and Fyber into a single stack. With the unified platform, you’ll be able to use our newest features while also gaining access to both dashboards.

From an integration perspective, the only major change is the replacement of network SDKs with adapter bundles.

Requirements

  • The Unified Platform Unity3D SDK supports Android 2.3.3 (API level 10)+ when building for Android.
  • The Unified Platform Unity3D SDK supports iOS 6.0+ when building for iOS
  • The Unified Platform Unity3D SDK supports Unity 4 and Unity 5.
  • The Unified Platform Unity3D SDK supports IL2CPP as a scripting backend on iOS; Mono is not supported.
  • The Heyzap Unity3D SDK can only build iOS projects from a Mac - you cannot build the Xcode project on Windows.

Step 1. Configure Dynamic Documentation

Select the networks and app 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

SDK v10.3.1

Using Xcode 6? Download our Xcode 6 compatible SDK and adapters here, then follow the instructions in Unity-README.md.

Step 3. Add the SDK to your project

Upgrading from SDK 9? Start fresh by deleting your old Heyzap SDK, and all 3rd-party ads SDKs. The Heyzap SDK files can be found at these locations:

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

Third-party SDKs may be harder to locate, but should be removed as well.

Unzip the downloaded files and double click the .unitypackage to import it.

Step 3a. Android-Specific Setup - Google Play Services

Additionally, install the Google Mobile Ads plugin's PlayServicesResolver by downloading the linked file and double-clicking it. This Unity plugin 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 > Google Play Services.

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

Facebook Audience Network

HyprMX

InMobi

MoPub

Tapjoy

UnityAds

Vungle

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

Step 5. Initialize the SDK

Import the SDK like so:

using Heyzap;

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

HeyzapAds.Start("<PUBLISHER ID>", HeyzapAds.FLAG_NO_OPTIONS);

Step 6: Post Xcode project generation (iOS Only)

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

Bitcode

Bitcode is a new feature added in Xcode 7 to compile apps to LLVM Bitcode instead of directly to CPU code (armv7, armv7s, arm64). Using Bitcode will give you smaller app binary sizes and is required for tvOS and watchOS apps. Unfortunately, these networks you've selected don't support Bitcode yet, so you'll have to disable it:

To disable it, find the "Enable Bitcode" setting in your Xcode target's Build Settings, then set it to "No".

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. From the secondary screen, you can select a type of ad (Interstitial, 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 8. 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

// Interstitial ads are automatically fetched
HZInterstitialAd.Show();

Video Ads

Version 9 of the Heyzap SDK included an API that could be used to display only interstitial video ads. The unified platform's server-side configuration options have made this API redundant, and it has been removed. If you would like to display only video ads, please use the HZInterstitialAd API, and set your game's "Blended Video" option to "Enabled: show ONLY video". This option can be found under "Publisher Settings" for your game.

Rewarded Video Ads

Rewarded videos must be fetched before they can be shown. As early as possible or after showing a rewarded video, call Fetch. Rewarded videos are not fetched automatically.

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;
showOptions.SelectedAdMobSize = HZBannerShowOptions.AdMobSize.BANNER; // optional, android only
showOptions.SelectedFacebookSize = HZBannerShowOptions.FacebookSize.BANNER_HEIGHT_50; // optional, android only
HZBannerAd.ShowWithOptions(showOptions);
var showOptions : HZBannerShowOptions = new HZBannerShowOptions();
showOptions.Position = HZBannerShowOptions.POSITION_TOP;
showOptions.SelectedAdMobSize = HZBannerShowOptions.AdMobSize.BANNER; // optional, android only
showOptions.SelectedFacebookSize = HZBannerShowOptions.FacebookSize.BANNER_HEIGHT_50; // optional, android only
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

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

First, you must declare a variable to keep track of fetched ads & subscribe to a few events:

// Import statement
using FyberPlugin;

// Private variable to keep track of an available Offer Wall ad
private FyberPlugin.Ad offerWall;

// Subscribe to Fyber Ad Availability callbacks
void OnEnable() {
    FyberCallback.AdAvailable += OnAdAvailable;
    FyberCallback.AdNotAvailable += OnAdNotAvailable;
    FyberCallback.RequestFail += OnRequestFail;
}

void OnDisable() {
    FyberCallback.AdAvailable -= OnAdAvailable;
    FyberCallback.AdNotAvailable -= OnAdNotAvailable;
    FyberCallback.RequestFail -= OnRequestFail;
}

Here are example handlers for those events:

// Ad Availability callback handlers
private void OnAdAvailable(FyberPlugin.Ad ad) {
    switch(ad.AdFormat) {
        case AdFormat.OFFER_WALL:
            // ad available, save a reference
            this.offerWall = ad;
            break;
    }
}

private void OnAdNotAvailable(FyberPlugin.AdFormat adFormat) {
    switch(adFormat) {
        case AdFormat.OFFER_WALL:
            // ad no longer available, clear our reference if we had one
            this.offerWall = null;
            break;
    }
}

private void OnRequestFail(FyberPlugin.RequestError error) {
    // check `error.Description` to see why the request failed
}

To fetch an Offer Wall ad:

void FetchOfferWall() {
   // Request an Offer Wall ad
   OfferWallRequester.Create()
       // Optional method chaining for configuring the Offer Wall
       //.CloseOnRedirect(true) // use this if you want the Offer Wall to close itself after the user interacts with one offer
       // Finish the request
       .Request();
}

To show an Offer Wall ad after fetching it:

void ShowOfferWall() {
   // Show an Offer Wall ad, if you have one fetched
   if (this.offerWall != null) {
       this.offerWall.Start();
       this.offerWall = null; // clear reference so we don't try to show this twice
   } else {
       // need to fetch first!
   }
}

Offer Wall - Rewards

Fyber has two ways you can get data about rewarding a user after they show an offer. You can either use their Server-to-Server callbacks (if you track your user's currency on your own server), or you can use their hosted Virtual Currency System (VCS). The docs for the Server-side callbacks can be found here. Below are integration steps for Fyber's SDK side VCS system (full docs here).

First, add these two events to your OnEnable and OnDisable handlers (you'll have others, from above, as well):

void OnEnable() {
    FyberCallback.VirtualCurrencySuccess += OnCurrencyResponse;
    FyberCallback.VirtualCurrencyError += OnCurrencyErrorResponse;
}

void OnDisable() {
    FyberCallback.VirtualCurrencySuccess -= OnCurrencyResponse;
    FyberCallback.VirtualCurrencyError -= OnCurrencyErrorResponse;
}

Then, implement the event handlers named above. You will use response.DeltaOfCoins to determine how much of a reward the user has earned.

private void OnCurrencyResponse(VirtualCurrencyResponse response) {
    // response.DeltaOfCoins will contain the amount of your in-game currency the user has earned
    UnityEngine.Debug.Log("Delta of coins: " + response.DeltaOfCoins.ToString() +
                          ". Transaction ID: " + response.LatestTransactionId +
                          ".\nCurreny ID: " + response.CurrencyId +
                          ". Currency Name: " + response.CurrencyName);
}

private void OnCurrencyErrorResponse(VirtualCurrencyErrorResponse vcsError) {
    UnityEngine.Debug.Log(String.Format("Delta of coins request failed.\n" +
                          "Error Type: {0}\nError Code: {1}\nError Message: {2}",
                          vcsError.Type, vcsError.Code, vcsError.Message));
}

Because Offer Wall offers are validated asynchronously, you'll need to call this method periodically, which will trigger a network request to Fyber's VCS servers to check if a reward has been earned. Your callbacks (above) will be notified when the request completes.

private void CheckForVirtualCurrencyReward() {
    VirtualCurrencyRequester.Create()
        // Overrideing currency Id (when you have more than one currency - this is configured on the Fyber dashboard)
        //.ForCurrencyId(currencyId)
        .Request();
}

Fyber's docs have more advanced information on configuring the Offer Wall if you are interested.

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