Android SDK 9

Watch a video tutorial for integrating the Android Mediation SDK.

Requirements

  • Heyzap works on Android 3.0 (API level 11) and above.

Step 1. Configure Dynamic Documentation

Select the version of the Heyzap SDK you wish to view documentation for, and then select the networks you are integrating. The documentation on this page will update with specific instructions that may apply to your selections.

Beta v9.13.2 / Non Beta v9.12.7
Our Beta SDK is less tested, but it has all our newest features. Should you have any issues with either version, please report them to support@heyzap.com.

Network Selection:

Step 2. Download the SDK

The SDK includes Heyzap, as well as wrappers for all 3rd-party networks.

SDK v9.13.2 (Beta)

Step 3. Add the Heyzap SDK to your project

Unzip the downloaded files, which contains the Heyzap jar file. Drag and drop this file into the libs folder of your Android project.

Add JAR to libs folder

Step 4. Add 3rd-party SDKs to your project

AdColony

AdMob

AppLovin

Chartboost

Domob

Facebook Audience Network

Fyber Exchange

HyprMX

InMobi

Leadbolt

MdotM

MoPub

UnityAds

Vungle

If you haven't already, use our Integration Wizard to setup the 3rd-party networks you want to use with mediation.

The Heyzap SDK will automatically detect and initialize the SDKs from 3rd-party networks. Some 3rd-party networks fail when initialized multiple times. Please do not initialize or otherwise directly interact with 3rd-party networks mediated by Heyzap.

Step 5. Modify your Android Manifest

Mandatory Permissions

Add the following permissions to your AndroidManifest.xml:



Optional Permissions

The following permissions are not required for our SDK and 3rd-party SDKs to function, but including them in your AndroidManifest.xml may result in improved eCPM and user experience:



Activities

Add the following activities to your AndroidManifest.xml:



Google Play Services

The Google Play Services SDK must be added to your project for these networks. Follow Google's documentation on integrating the Google Play Services SDK into your app. Only the Ads and Location APIs need to be included. If you are using a Gradle build system with Android Studio adding the following to build.gradle should suffice:

compile 'com.google.android.gms:play-services-ads:8.+'
compile 'com.google.android.gms:play-services-location:8.+'

Hardware Acceleration

Add an attribute to the <application> tag to enable hardware acceleration:

<application android:hardwareAccelerated="true" ...>

Step 6. Initialize the SDK

In your root Activity, start the Heyzap SDK:

import com.heyzap.sdk.ads.HeyzapAds;

Activity activity = this; // must be an Activity
// Your Publisher ID is: <PUBLISHER ID>
HeyzapAds.start("<PUBLISHER ID>", activity);

Step 7: Test your 3rd-Party Integrations (Optional)

The mediation SDK comes with a Mediation Test Suite that you can use to test each of the networks you've chosen:

The first screen lets you isolate a network to test its integration with the Heyzap SDK. Once you choose a network, you'll see if:

  1. The network is installed correctly.
  2. The network has valid credentials on your dashboard.
  3. The network is enabled on your dashboard.

To use the Mediation Test Suite, call this method after starting the SDK:

HeyzapAds.startTestActivity(activity);

At this point, you should launch the Mediation Test Suite and verify that each network you want to use has the correct credentials and shows ads correctly.

Step 8. Show Ads

Methods you call on the Heyzap SDK will automatically dispatch to your enabled 3rd-party SDKs; a call to display will iterate over ad networks in order of expected CPM until it finds one that has an ad, optimizing CPM and fill rate. Use the code below to display your preferred ad format:

Interstitial Ads

import com.heyzap.sdk.ads.InterstitialAd;

// InterstitialAds are automatically fetched from our server
InterstitialAd.display(this);

Video Ads

Unlike interstitial ads, video ads are not pre-cached automatically. They must be fetched manually. Depending on the available internet connection, it may take some time to fully download the necessary assets, so it is strongly recommended fetching at the earliest point in your application lifecycle, and following the view of any video ad.

import com.heyzap.sdk.ads.VideoAd;

// As early as possible, and after showing each video ad, call fetch
VideoAd.fetch();

Later, such as after a level is completed, you can check if the ad has fetched, and display the ad if it is available.

if (VideoAd.isAvailable()) {
    VideoAd.display(this);
}

Rewarded Video Ads

Unlike interstitial ads, video ads are not pre-cached automatically. They must be fetched manually. Depending on the available internet connection, it may take some time to fully download the necessary assets, so it is strongly recommended fetching at the earliest point in your application lifecycle, and following the view of any video ad.

import com.heyzap.sdk.ads.IncentivizedAd;

// As early as possible, and after showing a rewarded video, call fetch
IncentivizedAd.fetch();

Later, such as after a level is completed, you can check if the ad has fetched, and display the ad if it is available.

if (IncentivizedAd.isAvailable()) {
    IncentivizedAd.display(this);
}

Banner Ads

Heyzap offers banner ads through its in-house network, Heyzap Exchange. We also mediate banners from AdMob, Facebook Audience Network, Mopub, and InMobi.

Note: Most banner networks have a setting on their dashboard to automatically refresh at a given time interval. If you want to use this feature, it is strongly recommended that you use the same time interval on all of the banner networks you are using. Different refresh rates for different networks can result in confusing impression statistics.

import com.heyzap.sdk.ads.BannerAdView;

private BannerAdView bannerAdView;

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

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

    // This must be some view in your layout.
    FrameLayout bannerWrapper = (FrameLayout) findViewById(R.id.banner_wrapper);

    // Add the banner ad view to the wrapper.
    bannerWrapper.addView(bannerAdView);

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

You should also destroy the banner ad view in the onDestroy method of your Activity.

@Override
protected void onDestroy() {
  bannerAdView.destroy();
  super.onDestroy();
}

Offer Wall Ads

The Heyzap SDK provides access to the Fyber Offer Wall as of SDK version 9.12.0. The Offer Wall allows your users to complete certain activities in exchange for in-game currency.

Fetch

To fetch an Offer Wall ad:

OfferWall.fetch("default");

Show

To show an Offer Wall ad:

  OfferWall.OfferWallOptions offerWallOptions = new OfferWall.OfferWallOptions();
  offerWallOptions.closeOnRedirect = true; // auto-close after first offer interaction?
  OfferWall.display(this, "default", offerWallOptions);

See our detailed Offer Wall docs for more code examples on how to reward the user for offer wall interactions.

The Back Button

Some networks need a handler to the back button, Heyzap proxies this in with a single function which can be used like this:

@Override
public void onBackPressed(){
    if(HeyzapAds.onBackPressed()){
        return;
    }
    //put your normal onBackPressed code here 
}

All good? Head over to your mediation dashboard to view revenue, impressions, eCPM, network credentials, and more.


More Information:

To learn more about Native Ads, click here.
To view an Example App, click here.
To go to basic Android SDK setup, click here.
To view Advanced Features, click here.