Android Advanced Features

SDK v9.8.0
SDK 9 supports the full range of Heyzap tools & features. SDK 10 (beta) provides access to the Fyber platform. Questions? Reach us at support@heyzap.com.

Manual Fetching

In some scenarios, you may wish to disable automatic fetching of the ad from the ad server.

To put the Heyzap SDK into manual mode, start the SDK with the following flag:

HeyzapAds.start("<PUBLISHER ID>", activity, HeyzapAds.DISABLE_AUTOMATIC_FETCH);

Then to fetch an ad manually, do the following:

InterstitialAd.fetch();

After successfully fetching an ad, you will receive an onAvailable callback (see below), whereby it is safe to show an ad:

if (InterstitialAd.isAvailable()) {
     InterstitialAd.display(activity);
}

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 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:

InterstitialAd.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.display(activity, "post-level");

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

String postLevelTagName = "post-level";
if (InterstitialAd.isAvailable(postLevelTagName)) {
    InterstitialAd.display(activity, postLevelTagName);
}

Callbacks

You may need to know when an ad has shown, has been hidden, or the user clicked on an ad (and is about to leave your app). You can attach a listener to the class to receive callbacks for when these events occur.

import com.heyzap.sdk.ads.HeyzapAds.OnStatusListener;

InterstitialAd.setOnStatusListener(new OnStatusListener() {
    @Override
    public void onShow(String tag) {
        // Ad is now showing
    }

    @Override
    public void onClick(String tag) {
        // Ad was clicked on. You can expect the user to leave your application temporarily.
    }

    @Override
    public void onHide(String tag) {
        // Ad was closed. The user has returned to your application.
    }

    @Override
    public void onFailedToShow(String tag) {
        // Display was called but there was no ad to show
    }

    @Override
    public void onAvailable(String tag) {
        // An ad has been successfully fetched
    }

    @Override
    public void onFailedToFetch(String tag) {
        // No ad was able to be fetched
    }

    @Override
    public void onAudioStarted() {
        // The ad about to be shown will require audio. Any background audio should be muted.
    }

    @Override
    public void onAudioFinished() {
        // The ad being shown no longer requires audio. Any background audio can be resumed.
    }
});

You can set this listener at any point in the ads lifecycle, but it is recommended to set the listener at the earliest possible point in your application's lifecycle to receive all events.

To receive callbacks from VideoAd or IncentivizedAd, you can set the same or a different listener on each respective ad unit, as shown below:

HeyzapAds.OnStatusListener listener;

// Video Ad listener
VideoAd.setOnStatusListener(listener);

// IncentivizedAd listener
IncentivizedAd.setOnStatusListener(listener);

Incentivized Callbacks

As with interstitial ads, you will receive the normal OnStatusListener callbacks for when an incentivized ad is shown, hidden, clicked, and so on. In addition, you can request callbacks for when an incentivized ad was completed or left incomplete using the OnIncentiveResultListener callback.

An example of setting this callback is shown below:

import com.heyzap.sdk.ads.HeyzapAds.OnIncentiveResultListener;

IncentivizedAd.setOnIncentiveResultListener(new OnIncentiveResultListener() {
    @Override
    public void onComplete(String tag) {
        // Give the player their reward
    }

    @Override
    public void onIncomplete(String tag) {
        // Don't give the player their reward, and tell them why
    }
});

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 param customInfo to whatever you need passed to your server:

IncentivizedAd.display("enter in your string here, it will be passed to your server", activity);
// IncentivizedAd.display(activity, "tag", "enter in your string here, it will be passed to your server"); // use this version instead to show for a tag if desired

Banner Callbacks

You can use a BannerListener to get notified when an ad is loaded, clicked, or has an error.

import com.heyzap.sdk.ads.BannerAdView;
import com.heyzap.sdk.ads.HeyzapAds.BannerListener;
import com.heyzap.sdk.ads.HeyzapAds.BannerError;

private BannerAdView bannerAdView;

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...

    Activity activity = this; // Must be an Activity
    bannerAdView = new BannerAdView(activity);
    FrameLayout bannerWrapper = (FrameLayout) findViewById(R.id.banner_wrapper);
    bannerWrapper.addView(bannerAdView);

    // Add a listener.
    bannerAdView.setBannerListener(new BannerListener() {
        @Override
        public void onAdClicked(BannerAdView b) {
            // The ad has been clicked by the user.
        }

        @Override
        public void onAdLoaded(BannerAdView b) {
            // The ad has been loaded.
        }

        @Override
        public void onAdError(BannerAdView b, BannerError bannerError) {
            // There was an error loading the ad.
        }
    });

    // Load the banner ad.
    bannerAdView.load();
}

Network Callbacks

For background tasks like analytics we provide a callback which catches all events from all networks. A listener can be attached with:

HeyzapAds.setNetworkCallbackListener(new NetworkCallbackListener() {
    @Override
    public void onNetworkCallback(String network, String event) {
        System.out.println(network + " " + event);
    }
});

The possibilities for the network string are: "heyzap", "facebook", "unityads", "applovin", "vungle", "chartboost", "adcolony", "admob", "hyprmx"

The possibilities for the event string are: "initialized", "show", "available", "hide", "fetch_failed", "click", "dismiss", "incentivized_result_complete", "incentivized_result_incomplete", "audio_starting", "audio_finished", "banner-loaded", "banner-click", "banner-hide", "banner-dismiss", "banner-fetch_failed", "leave_application", "display_failed"

If the network is chartboost the following events are also possible: "moreapps-fetch_failed", "moreapps-hide", "moreapps-dismiss", "moreapps-click", "moreapps-show", "moreapps-available", "moreapps-click_failed";

If the network is facebook "logging_impression" is also a possible event.

Banner Sizes

By default, our banners will be sized appropriately for an Android phone or non-tablet device. If you want to customize the banner size for each banner network, you can use the BannerOptions object on the BannerAdView.

import com.heyzap.sdk.ads.BannerAdView;
import com.heyzap.sdk.ads.HeyzapAds.BannerOptions;

private BannerAdView bannerAdView;

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...

    Activity activity = this; // Must be an Activity.
    bannerAdView = new BannerAdView(activity);
    BannerOptions bannerOptions = bannerAdView.getBannerOptions();

    // Let's use a larger banner format, which is appropriate for Android tablets.
    bannerOptions.setFacebookBannerSize(CreativeSize.BANNER_HEIGHT_90);
    bannerOptions.setAdmobBannerSize(CreativeSize.BANNER_HEIGHT_90);

    // Load the banner ad.
    bannerAdView.load()
}

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.

import org.json.JSONObject;

JSONObject remoteData = HeyzapAds.getRemoteData();

// Tip: Always set a default value, as data may not have been fetched yet.
String someKeyValue = remoteData.optString("some_key", "default_value");

Example use case: Variable rewards for rewarded 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 rewarded video ad, you can just set up this Remote Data object with something like this:

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

And in your app:

import org.json.JSONObject;

JSONObject remoteData = HeyzapAds.getRemoteData();

// Tip: Always set a default value, as data may not have been fetched yet.
String currency = remoteData.optString("currency", "Gems");
String amount = remoteData.optInt("amount", 0);

In-App Purchase Tracking

(Note: This data will be used by an upcoming feature that will help you control ad placements after a user has made an in-app purchase.)

You can report to Heyzap when a user completes an in-app purchase by calling this method:

HeyzapAds.onPurchaseComplete("Example Product Name", "example_product_id", 199); // the last parameter is the price in US cents - in this example, the IAP was $1.99

Calling 3rd-party networks directly

You can interact with 3rd party SDKs directly, but you'll need to check if they're initialized first:

String chartboost = HeyzapAds.Network.CHARTBOOST;

if (HeyzapAds.isNetworkInitialized(chartboost)) {
    Chartboost.cacheInterstitial("myLocation");
}

Currently Heyzap loads networks lazily (networks are not initialized until we need to fetch an ad from them to optimize disk/bandwidth/CPU/memory usage). We don't currently have a way for developers to initialize a certain network at the start of the app; please contact support@heyzap.com and we'll handle this manually for now.

Chartboost Cross-Promo

You can call Chartboost directly to use cross-promo. See "Calling 3rd-party networks directly" above.

ProGuard

If you are using ProGuard, add the following line to your proguard.cfg in the root of your Android project directory.

-keep public class com.heyzap.** { *; } 
-libraryjars libs/heyzap-ads-sdk.jar 
-dontwarn com.heyzap.**

Note: If you are integrating other ad networks, you may need to add separate rules for Heyzap to work correctly.

Install Tracking Only

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

HeyzapAds.start("<PUBLISHER ID>", activity, HeyzapAds.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 Revenue dashboard for your app.


More Information:

To view an Example App, click here.
To go back to basic Android SDK setup, click here.
To set up Mediation, click here.

Unified Platform – Android SDK 10 Advanced Features

SDK v10.3.1
SDK 9 supports the full range of Heyzap tools & features. SDK 10 (beta) provides access to the Fyber platform. Questions? Reach us at support@heyzap.com.

Manual Fetching

In some scenarios, you may wish to disable automatic fetching of the ad from the ad server.

To put the Heyzap SDK into manual mode, start the SDK with the following flag:

HeyzapAds.start("<PUBLISHER ID>", activity, HeyzapAds.DISABLE_AUTOMATIC_FETCH);

Then to fetch an ad manually, do the following:

InterstitialAd.fetch();

After successfully fetching an ad, you will receive an onAvailable callback (see below), whereby it is safe to show an ad:

if (InterstitialAd.isAvailable()) {
     InterstitialAd.display(activity);
}

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.

Callbacks

You may need to know when an ad has shown, has been hidden, or the user clicked on an ad (and is about to leave your app). You can attach a listener to the class to receive callbacks for when these events occur.

import com.heyzap.sdk.ads.HeyzapAds.OnStatusListener;

InterstitialAd.setOnStatusListener(new OnStatusListener() {
    @Override
    public void onShow(String tag) {
        // Ad is now showing
    }

    @Override
    public void onClick(String tag) {
        // Ad was clicked on. You can expect the user to leave your application temporarily.
    }

    @Override
    public void onHide(String tag) {
        // Ad was closed. The user has returned to your application.
    }

    @Override
    public void onFailedToShow(String tag) {
        // Display was called but there was no ad to show
    }

    @Override
    public void onAvailable(String tag) {
        // An ad has been successfully fetched
    }

    @Override
    public void onFailedToFetch(String tag) {
        // No ad was able to be fetched
    }

    @Override
    public void onAudioStarted() {
        // The ad about to be shown will require audio. Any background audio should be muted.
    }

    @Override
    public void onAudioFinished() {
        // The ad being shown no longer requires audio. Any background audio can be resumed.
    }
});

You can set this listener at any point in the ads lifecycle, but it is recommended to set the listener at the earliest possible point in your application's lifecycle to receive all events.

To receive callbacks from IncentivizedAd, you can set the same or a different listener on each respective ad unit, as shown below:

HeyzapAds.OnStatusListener listener;

// IncentivizedAd listener
IncentivizedAd.setOnStatusListener(listener);

Incentivized Callbacks

As with interstitial ads, you will receive the normal OnStatusListener callbacks for when an incentivized ad is shown, hidden, clicked, and so on. In addition, you can request callbacks for when an incentivized ad was completed or left incomplete using the OnIncentiveResultListener callback.

An example of setting this callback is shown below:

import com.heyzap.sdk.ads.HeyzapAds.OnIncentiveResultListener;

IncentivizedAd.setOnIncentiveResultListener(new OnIncentiveResultListener() {
    @Override
    public void onComplete(String tag) {
        // Give the player their reward
    }

    @Override
    public void onIncomplete(String tag) {
        // Don't give the player their reward, and tell them why
    }
});

Banner Callbacks

You can use a BannerListener to get notified when an ad is loaded, clicked, or has an error.

import com.heyzap.sdk.ads.BannerAdView;
import com.heyzap.sdk.ads.HeyzapAds.BannerListener;
import com.heyzap.sdk.ads.HeyzapAds.BannerError;

private BannerAdView bannerAdView;

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...

    Activity activity = this; // Must be an Activity
    bannerAdView = new BannerAdView(activity);
    FrameLayout bannerWrapper = (FrameLayout) findViewById(R.id.banner_wrapper);
    bannerWrapper.addView(bannerAdView);

    // Add a listener.
    bannerAdView.setBannerListener(new BannerListener() {
        @Override
        public void onAdClicked(BannerAdView b) {
            // The ad has been clicked by the user.
        }

        @Override
        public void onAdLoaded(BannerAdView b) {
            // The ad has been loaded.
        }

        @Override
        public void onAdError(BannerAdView b, BannerError bannerError) {
            // There was an error loading the ad.
        }
    });

    // Load the banner ad.
    bannerAdView.load();
}

Banner Sizes
------------

By default, our banners will be sized appropriately for an Android phone or non-tablet device. If you want to customize the banner size for each banner network, you can use the BannerOptions object on the BannerAdView.

import com.heyzap.sdk.ads.BannerAdView; import com.heyzap.sdk.ads.HeyzapAds.BannerOptions;

private BannerAdView bannerAdView;

@Override public void onCreate(Bundle savedInstanceState) { // ...

Activity activity = this; // Must be an Activity.
bannerAdView = new BannerAdView(activity);
BannerOptions bannerOptions = bannerAdView.getBannerOptions();

// Let's use a larger banner format, which is appropriate for Android tablets.
bannerOptions.setFacebookBannerSize(CreativeSize.BANNER_HEIGHT_90);
bannerOptions.setAdmobBannerSize(CreativeSize.BANNER_HEIGHT_90);

// Load the banner ad.
bannerAdView.load()

}

ProGuard

If you are using ProGuard, add the following line to your proguard.cfg in the root of your Android project directory.

-keep public class com.heyzap.** { *; } 
-keep public class com.fyber.** { *; }
-dontwarn com.heyzap.**
-dontwarn com.fyber.**

# Google Advertising Id
-keep class com.google.android.gms.ads.identifier.** { *; }

Note: If you are integrating other ad networks, you may need to add separate rules for Heyzap to work correctly.


More Information:

To go back to basic Android SDK setup, click here.