SDK 9 - Unity3D SDK Advanced Features

Manual Fetching

In some scenarios, you may wish to disable automatic fetching of ads from the ad server. You may want to do this, for instance, if you are putting Heyzap into a waterfall with other ad networks yourself, using another mediation network, or are worried about the performance or bandwidth impact of Heyzap's SDK.

To put the Heyzap SDK into manual mode, start the SDK (as shown in Step 7 here with the following flag:

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

Then, when you want to fetch an ad, do the following:

HZInterstitialAd.Fetch();

After successfully fetching an ad, you will receive an available callback (see below), which alerts you that an ad is ready to show. Or, instead of listening for this callback, you can always wrap your calls to Show with an IsAvailable check:

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

Important: It is highly recommended to call Fetch as far in advance of showing an ad as possible. For example, you may want to fetch an ad when a level starts, or after a previous ad is shown. This will allow time for the ad to be downloaded.

Tags

Tags are a powerful tool which enable you to monitor the performance of ads in a particular location or logical section of your game. If an ad with a particular tag underperforms or you later find is too annoying to your users, you can turn it off from the dashboard, saving you the hastle of resubmitting your game to the App or Play Store. In addition, you do not need to set up tag names on your dashboard prior to writing code: as soon as we see a new tag, we will show you the stats in your game's dashboard.

Before you can show an ad with a tag, you must fetch an ad at the earliest point possible before you will need to show one.

In the following example, we fetch an ad that will be shown after the game's level is complete:

HZInterstitialAd.Fetch("post-level");

Then, when you want to display the post-level ad, we do so by passing the same "post-level" string to Show via the HZShowOptions object:

HZShowOptions showOptions = new HZShowOptions();
showOptions.Tag = "post-level";
HZInterstitialAd.ShowWithOptions(showOptions);
var showOptions : HZShowOptions = new HZShowOptions();
showOptions.Tag = "post-level";
HZInterstitialAd.ShowWithOptions(showOptions);

If you want to find out if an ad with a particular tag is ready to show, you can use the IsAvailable method and pass your tag as the only parameter:

if (HZInterstitialAd.IsAvailable("post-level")) {
     HZShowOptions showOptions = new HZShowOptions();
     showOptions.Tag = "post-level";
     HZInterstitialAd.ShowWithOptions(showOptions);
}
if (HZInterstitialAd.IsAvailable("post-level")) {
    var showOptions : HZShowOptions = new HZShowOptions();
    showOptions.Tag = "post-level";
    HZInterstitialAd.ShowWithOptions(showOptions);
}

Callbacks

You may need to know when an ad is clicked or when an ad has hidden so you can unpause your game. If this is the case, the following code will let you know when various changes in the ad state occur. You can set a listener on HZInterstitialAd, HZVideoAd, and HZIncentivizedAd.

HZInterstitialAd.AdDisplayListener listener = delegate(string adState, string adTag){
  if ( adState.Equals("show") ) {
        // Sent when an ad has been displayed.
        // This is a good place to pause your app, if applicable.
    }
    if ( adState.Equals("hide") ) {
        // Sent when an ad has been removed from view.
        // This is a good place to unpause your app, if applicable.
    }
    if ( adState.Equals("click") ) {
        // Sent when an ad has been clicked by the user.
    }
    if ( adState.Equals("failed") ) {
        // Sent when you call `show`, but there isn't an ad to be shown.
        // Some of the possible reasons for show errors:
        //    - `HeyzapAds.PauseExpensiveWork()` was called, which pauses 
        //      expensive operations like SDK initializations and ad
        //      fetches, andand `HeyzapAds.ResumeExpensiveWork()` has not
        //      yet been called
        //    - The given ad tag is disabled (see your app's Publisher
        //      Settings dashboard)
        //    - An ad is already showing
        //    - A recent IAP is blocking ads from being shown (see your
        //      app's Publisher Settings dashboard)
        //    - One or more of the segments the user falls into are
        //      preventing an ad from being shown (see your Segmentation
        //      Settings dashboard)
        //    - Incentivized ad rate limiting (see your app's Publisher
        //      Settings dashboard)
        //    - One of the mediated SDKs reported it had an ad to show
        //      but did not display one when asked (a rare case)
        //    - The SDK is waiting for a network request to return before an
        //      ad can show
    }
    if ( adState.Equals("available") ) {
        // Sent when an ad has been loaded and is ready to be displayed,
        //   either because we autofetched an ad or because you called
        //   `Fetch`.
    }
    if ( adState.Equals("fetch_failed") ) {
        // Sent when an ad has failed to load.
        // This is sent with when we try to autofetch an ad and fail, and also
        //    as a response to calls you make to `Fetch` that fail.
        // Some of the possible reasons for fetch failures:
        //    - Incentivized ad rate limiting (see your app's Publisher
        //      Settings dashboard)
        //    - None of the available ad networks had any fill
        //    - Network connectivity
        //    - The given ad tag is disabled (see your app's Publisher
        //      Settings dashboard)
        //    - One or more of the segments the user falls into are
        //      preventing an ad from being fetched (see your
        //      Segmentation Settings dashboard)
    }
    if ( adState.Equals("audio_starting") ) {
        // The ad about to be shown will need audio.
        // Mute any background music.
    }
    if ( adState.Equals("audio_finished") ) {
        // The ad being shown no longer needs audio.
        // Any background music can be resumed.
    }
};
        
HZInterstitialAd.SetDisplayListener(listener);
HZInterstitialAd.SetDisplayListener(function(adState, adTag){
    if (adState == "show") {
        // Sent when an ad has been displayed.
        // This is a good place to pause your app, if applicable.
    }
    if (adState == "hide") {
        // Sent when an ad has been removed from view.
        // This is a good place to unpause your app, if applicable.
    }
    if (adState == "click") {
        // Sent when an ad has been clicked by the user.
    }
    if (adState == "failed") {
        // Sent when you call `show`, but there isn't an ad to be shown.
        // Some of the possible reasons for show errors:
        //    - `HeyzapAds.PauseExpensiveWork()` was called, which pauses 
        //      expensive operations like SDK initializations and ad
        //      fetches, andand `HeyzapAds.ResumeExpensiveWork()` has not
        //      yet been called
        //    - The given ad tag is disabled (see your app's Publisher
        //      Settings dashboard)
        //    - An ad is already showing
        //    - A recent IAP is blocking ads from being shown (see your
        //      app's Publisher Settings dashboard)
        //    - One or more of the segments the user falls into are
        //      preventing an ad from being shown (see your Segmentation
        //      Settings dashboard)
        //    - Incentivized ad rate limiting (see your app's Publisher
        //      Settings dashboard)
        //    - One of the mediated SDKs reported it had an ad to show
        //      but did not display one when asked (a rare case)
        //    - The SDK is waiting for a network request to return before an
        //      ad can show
    }
    if (adState == "available") {
        // Sent when an ad has been loaded and is ready to be displayed,
        //   either because we autofetched an ad or because you called `Fetch`.
    }
    if (adState == "fetch_failed") {
        // Sent when an ad has failed to load.
        // This is sent with when we try to autofetch an ad and fail, and also
        //    as a response to calls you make to `Fetch` that fail.
        // Some of the possible reasons for fetch failures:
        //    - Incentivized ad rate limiting (see your app's Publisher
        //      Settings dashboard)
        //    - None of the available ad networks had any fill
        //    - Network connectivity
        //    - The given ad tag is disabled (see your app's Publisher
        //      Settings dashboard)
        //    - One or more of the segments the user falls into are
        //      preventing an ad from being fetched (see your
        //      Segmentation Settings dashboard)
    }
    if (adState == "audio_starting") {
        // The ad about to be shown will need audio.
        // Mute any background music.
    }
    if (adState == "audio_finished") {
        // The ad being shown no longer needs audio. 
        // Any background music can be resumed.
    }
});
    

Incentivized Callbacks

There are two additional callbacks that can be listened for when using HZIncentivizedAd (on top of the callbacks described above:

HZIncentivizedAd.AdDisplayListener listener = delegate(string adState, string adTag){
  if ( adState.Equals("incentivized_result_complete") ) {
      // The user has watched the entire video and should be given a reward.
  }
  if ( adState.Equals("incentivized_result_incomplete") ) {
      // The user did not watch the entire video and should not be given a   reward.
  }
};

HZIncentivizedAd.SetDisplayListener(listener);
HZIncentivizedAd.SetDisplayListener(function(adState, adTag){
  if (adState == "incentivized_result_complete") {
      // The user has watched the entire video and should be given a reward.
  }
  if (adState == "incentivized_result_incomplete") {
      // The user did not watch the entire video and should not be given a reward.
  }
});

Server-side Incentivized Callbacks

Heyzap can send you a secure, server-side confirmation every time a user completes a rewarded video. More information on this option can be found here.

If you are using these server-side callbacks for rewarded video, you can also send an arbitrary string of data through our SDK that will be passed along to your server as a param in the callback URL. To set this string of data, use this method to show incentivized videos and set the property IncentivizedInfo to whatever you need passed to your server:

HZIncentivizedShowOptions incentivizedShowOptions = new HZIncentivizedShowOptions();
//incentivizedShowOptions.Tag = "tag"; // use this property to show for a tag if desired
incentivizedShowOptions.IncentivizedInfo = "enter in your string here, it will be passed to your server";
HZInterstitialAd.ShowWithOptions(incentivizedShowOptions);
var incentivizedShowOptions : HZIncentivizedShowOptions = new HZIncentivizedShowOptions();
//incentivizedShowOptions.Tag = "tag"; // use this property to show for a tag if desired
incentivizedShowOptions.IncentivizedInfo = "enter in your string here, it will be passed to your server";
HZInterstitialAd.ShowWithOptions(incentivizedShowOptions);

Banner Callbacks

You may need to know when a banner ad is clicked, is loaded, or fails to load. If this is the case, use the following code to be alerted when any of these things occur for your banner ads.

HZBannerAd.AdDisplayListener listener = delegate(string adState, string adTag){
  if (adState == "loaded") {
      // Do something when the banner ad is loaded
  }
  if (adState == "error") {
      // Do something when the banner ad fails to load (they can fail when refreshing after successfully loading)
  }
  if (adState == "click") {
      // Do something when the banner ad is clicked, like pause your game
  }
};

HZBannerAd.SetDisplayListener(listener);
  
HZBannerAd.SetDisplayListener(function(adState, adTag){
  if (adState == "loaded") {
      // Do something when the banner ad is loaded
  }
  if (adState == "error") {
      // Do something when the banner ad fails to load (they can fail when refreshing after successfully loading)
  }
  if (adState == "click") {
      // Do something when the banner ad is clicked, like pause your game
  }
});
    

Remote Data

To configure data to send to your app via our SDK, go to your Dashboard, select a game, and then choose "Publisher Settings" from the navigation menu on the left. By setting up your own JSON blob under the setting "Remote Data JSON", you can send any data you need to your app through our SDK. The code below shows how to access this custom data via the SDK.

string remoteDataJSON = HeyzapAds.GetRemoteData();
var remoteDataJSON : String = HeyzapAds.GetRemoteData();

Example use case: Variable rewards for incentivized ads

If you'd like to be able to change the in-app currency type and/or amount that you will give users after they successfully complete an incentivized video ad, you can just set up this Remote Data object with something like this:

{
    "incentivized_reward":
    {
        "currency":"Gems",
        "amount":10
    }
}

The string you can access with the code examples above would, in this example, represent one dictionary with one key: incentivized_reward. The value at that key would be another dictionary with keys currency and amount. Once you retrieve this string, you can use your favorite JSON parsing library to parse the string and retrieve the objects you've created.

Note: The top-level object of whatever JSON blob you choose to save on your Dashboard should be a JSON object ({}) and not a JSON array ([]).

3rd-Party Network Callbacks

3rd-party networks will frequently only send callbacks to a single object. In these cases, using 3rd-party network callbacks yourself prevents the Heyzap SDK from receiving the callbacks, which will prevent the SDK from functioning properly.

In order to work around this, Heyzap will forward callbacks from 3rd-party networks to you, which you can receive using the NetworkCallbackListener. The listener function provides the network name and callback type as strings (HeyzapAds.cs provides constants for the network names (e.g. Network.CHARTBOOST) and callback types (e.g. NetworkCallback.SHOW)).

HeyzapAds.NetworkCallbackListener networkCallbackListner = delegate(string network, string callback)
{
    if (callback.Equals(HeyzapAds.NetworkCallback.SHOW)) {
        Debug.Log("The network: " + network + " showed an ad");
    }
};
HeyzapAds.SetNetworkCallbackListener(networkCallbackListner);
HeyzapAds.SetNetworkCallbackListener(function(network : String, callback : String){
    if (callback == HeyzapAds.NetworkCallback.SHOW) {
        Debug.Log("The network: " + network + " showed an ad.");
    }
});

Chartboost Interstitials

Any interaction with Chartboost's Unity C# code will cause Chartboost to be initialized from Unity. This will cause incorrect credentials to be used, and potentially cause Heyzap not to receive delegate callbacks from Chartboost correctly. We're working with Chartboost to improve this situation.

As a workaround, we've added 3 functions to show Chartboost interstitials using our SDK:

HZInterstitialAd.ChartboostFetchForLocation("Default");
HZInterstitialAd.ChartboostIsAvailableForLocation("Default")
HZInterstitialAd.ChartboostShowForLocation("Default");

Please contact Heyzap if you need additional functionality provided.

Test Devices

Advertisers are able to target certain countries on Heyzap's network. Depending on which country you live in, there may be a limited number of advertisers targetting you, and video ads may not be available at all in your country.

For testing purposes, you can set your own device to receive ads from all advertisers on your App Settings page, which can be found on the Revenue dashboard for your app.


More Information:

To view an Example App, click here.
To go back to the basic Unity3D SDK setup, click here.