Unified Platform – Unity SDK 10

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

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.