Unified Platform – Android Advanced Features

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

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 addCustomParam or addCustomParams methods of IncentivizedAd before executing a fetch. The parameters will persist for all future fetches unless overwritten.

IncentivizedAd.addCustomParam("pub0", "value");

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.