Adobe Native Extension Advanced Features - SDK 9

Manual Fetching

In some scenarios, you may wish to disable automatic fetching of the ad from the ad server. Reasons for manual fetching could be if you are putting Heyzap into a waterfall with other ad networks, using a mediation network, or are worried about the performance or bandwidth impact of Heyzap ads.

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

HeyzapAds.getInstance().start("<PUBLISHER ID>", HeyzapAds.FLAG_DISABLE_AUTOMATIC_FETCH);

Then when fetching an ad, do the following:

InterstitialAd.fetch();

After succesfully fetching an ad, you will receive an HeyzapEvent.IS_AVAILABLE callback (see below), whereby it is safe to show an ad:

if (InterstitialAd.getInstance().isAvailable()) {
     InterstitialAd.getInstance().show();
}

Important: It is highly recommended to 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 has been shown.

Tags

Tags are a powerful tool which enable you to monitor the performance of ads in a particular location or logical section of your app. 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 app 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 app's dashboard.

Before you can show an ad with a tag, you must fetch the ad at the earliest point to when you know you will need to show that ad.

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

import com.heyzap.sdk.ads.InterstitialAd;
InterstitialAd.getInstance().fetch("post-level");

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

InterstitialAd.getInstance().show("post-level");

If you want to find out if an ad with a particular tag is ready to display, you can use the HeyzapEvent.IS_AVAILABLE method and pass your tag as the first parameter:

if (InterstitialAd.getInstance().isAvailable("post-level")) {
    InterstitialAd.getInstance().show("post-level");
}

You can use tags with VideoAd and IncentivizedAd in the same manner as shown with InterstitialAd above. For BannerAd, you can pass a tag after the banner position when calling show:

BannerAd.getInstance().show(BannerAd.POSITION_BOTTOM, "post-level");

Interstitial Callbacks

There are eight different events that can be fired in the lifecycle of an interstitial ad. These events are part of the HeyzapEvent class found in the ANE. The following events are fired.

// Did Show: When an interestitial ad is shown.
HeyzapEvent.DID_SHOW

// Did Click: When an interstitial ad is clicked
HeyzapEvent.DID_CLICK

// Did Hide: When an interestitial ad is hidden (also called after a click)
HeyzapEvent.DID_HIDE

// Did Fail: When an ad cannot be shown (usually because of no internet connection)
HeyzapEvent.DID_FAIL

// Is Available: Ad has successfully pre-fetched and can be shown
HeyzapEvent.IS_AVAILABLE

// Fetch Failed: When a pre-fetch was attempted but no ad was returned.
HeyzapEvent.FETCH_FAILED

// Audio Started: When the ad being shown will be using audio. Any background music should be muted.
HeyzapEvent.ON_AUDIO_STARTED

// Audio Finished: When the ad being shown no longer requires audio. Any background music can be resumed.
HeyzapEvent.ON_AUDIO_FINISHED

An example is shown below on how one might listen in for a particular event:

import com.heyzap.sdk.ads.HeyzapAds;
import com.heyzap.sdk.ads.InterstitialAd;
import com.heyzap.sdk.HeyzapEvent;

InterstitialAd.getInstance().addEventListener(HeyzapEvent.DID_SHOW, function(event:Event=null){
  // Do something here
  return null;
});

You may also listen for the same events on VideoAd and IncentivizedAd.

Incentivized Callbacks

For incentivized ads, you will receive the following OnStatusListener callbacks. There are six different events that can be fired in the lifecycle of an incentivized ad. These events are part of the HeyzapEvent class found in the ANE.

// Incentivized ad is completed
HeyzapEvent.IS_COMPLETED

// Incentivized ad was not completed
HeyzapEvent.IS_INCOMPLETE

// Did Show: When an Incentivized ad is shown.
HeyzapEvent.DID_SHOW

// Did Click: When an Incentivized ad is clicked
HeyzapEvent.DID_CLICK

// Did Hide: When an Incentivized ad is hidden (also called after a click)
HeyzapEvent.DID_HIDE

// Did Fail: When an ad cannot be shown (usually because of no internet connection)
HeyzapEvent.DID_FAIL

// Is Available: Ad has successfully pre-fetched and can be shown
HeyzapEvent.IS_AVAILABLE

// Fetch Failed: When a pre-fetch was attempted but no ad was returned.
HeyzapEvent.FETCH_FAILED

An example is shown below on how one might listen in for a particular event:

import com.heyzap.sdk.ads.HeyzapAds;
import com.heyzap.sdk.ads.IncentivizedAd;
import com.heyzap.sdk.HeyzapEvent;

IncentivizedAd.getInstance().addEventListener(HeyzapEvent.IS_COMPLETED, 
    function(event:Event=null){
       // Give the user their reward!
       return null;
    });

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 second string parameter to whatever you need passed to your server:

// The first parameter can be `null` if you don’t use ad tags
IncentivizedAd.getInstance().show(“tag”, "enter in your string here, it will be passed to your server”);

Banner Ad Callbacks

For banner ads, you will receive the following OnStatusListener callbacks. There are three different events that can be fired in the lifecycle of an banner ad. These events are part of the HeyzapEvent class found in the ANE.

// Did Click: When a Banner ad is clicked
HeyzapEvent.DID_CLICK

// On Loaded: When an Banner ad is loaded and ready to be shown
HeyzapEvent.ON_LOADED

// On Error: When a banner ad cannot be shown (usually because of no internet connection)
HeyzapEvent.ON_ERROR

An example is shown below on how one might listen in for a particular event:

import com.heyzap.sdk.ads.HeyzapAds;
import com.heyzap.sdk.ads.BannerAd;
import com.heyzap.sdk.HeyzapEvent;

BannerAd.getInstance().addEventListener(HeyzapEvent.ON_ERROR, 
    function(event:Event=null) {
       // Do something here
       return null;
    });

Banner Ad Dimensions

The dimensions method can be used to get a Rectangle object which will contain the size and position of the currently displayed banner ad. The object will contain empty values if a banner ad is not displayed.

import com.heyzap.sdk.ads.HeyzapAds;
import com.heyzap.sdk.ads.BannerAd;
import flash.geom.Rectangle;

var bannerDimensions:Rectangle = BannerAd.getInstance().dimensions();
trace("Banner Ad Dimensions: width=" + bannerDimensions.width + " height=" + bannerDimensions.height);

Install Tracking Only

If you are integrating the ads-only SDK to provide install attribution, follow up to the second second step, replacing the first parameter with HeyzapAds.FLAG_INSTALL_TRACKING_ONLY, as shown in the following example:

HeyzapAds.getInstance().start("<PUBLISHER ID>", 
                              HeyzapAds.FLAG_INSTALL_TRACKING_ONLY);

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 Ad Revenue page for your app, on the developer dashboard.


More Information:

To go to basic ANE SDK setup, click here.
To set up Mediation, click here.