Unified Platform – Unity 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.

Callbacks

The following code will let you know when various state changes occur during ad fetches, and shows. You can set a separate listener on both HZInterstitialAd 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("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.
  }
});

Incentivized Server-Side Callback Parameters

Starting with SDK 10.4.0, if you are hosting your own currency service, you can pass custom parameters through the Fyber platform when requesting incentivized ads. The custom parameters will be passed back to your server in the server-to-server callback when the incentivized ad is completed.

You can pass along up to 10 custom parameters (keys between [pub0, pub1, …, pub9]) with the request by calling the AddCustomParameter method of HZIncentivizedAd before executing a fetch. The parameters will persist for all future fetches unless overwritten.

HZIncentivizedAd.AddCustomParameter("pub0", "value");

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

More Information:

To go back to the basic Unity3D SDK setup, click here.