Unified Platform – Unity

Our Unified Platform with Fyber, also called SDK 10 or the Fyber Wrapper, brings together the core features of Heyzap and Fyber into a single SDK. Things like Offer Wall and Fyber's different selection of ad networks are offered via this wrapper SDK.

Native ads, Heyzap Cross Promotion, and some of our dashboard's more powerful features & settings (e.g.: Segmentation, most uses of Tags, and some of the Publisher Settings) are not supported via this wrapper SDK, so consider what features you will be using when deciding which SDK to use.

From an integration perspective, the only major change when switching to the Unified Platform is the replacement of "raw" third-party network SDKs with Fyber's adapter bundles. Each of Fyber's adapter bundles contains its own code along with the third-party SDK, so you must use these instead.

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.
  • In order to download and use SDK 10, you must first have a payout method selected & filled out here.

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

By use of the Heyzap SDK you agree to our Heyzap SDK Agreement

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

Switching 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, 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

Facebook Audience Network

HyprMX

InMobi

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

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

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

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