Android SDK - Native Ads

Native ads allow app developers to completely customize the appearance and placement of ads. This provides more flexibility for the developer and a better experience for the user.

The Heyzap SDK currently supports Facebook Audience Network native ads, AdMob native ads, and Heyzap's internal native ads. AdMob currently has their native ads in a limited beta, so publishers need to contact AdMob to join.

Step 1. Integrate the Heyzap SDK

If you haven't done so already, integrate the Heyzap SDK using the instructions here.

If you will be using only native ads, you can follow these instructions to disable automatic fetching of interstitial ads.

Facebook Specific Instructions

If you target newer Android devices you will need to include the RecyclerView support library in your project to display native ads properly. You can achieve this by adding the following to your build.gradle file.

  compile 'com.android.support:recyclerview-v7:24.+'

Step 2. Fetch a native ad

To show a native ad, we will create a new NativeAd object, set its listener, and load the ad. We'll create the custom views to display the native ad in the next section.

Note: To support AdMob native ads, you will need to implement an AdmobListener and follow Admob's documentation for creating and showing an ad. Read more about this here.

final NativeAd nativeAd = new NativeAd();

// Set a listener to notify us when certain actions occur.
nativeAd.setListener(new NativeListener() {

    @Override
    public void onAdLoaded(NativeAd nativeAd) {
        Log.d("The ad has been loaded");
        // This is where we will create the views to display the ad.
        // See the next section of these docs.
        setupNativeAdView(nativeAd);
    }

    @Override
    public void onAdShown(NativeAd nativeAd) {
        Log.d("The ad was shown");
    }

    @Override
    public void onAdClicked(NativeAd nativeAd) {
        Log.d("The ad was clicked");
    }

    @Override
    public void onError(NativeError nativeError) {
        Log.d("There was an error: " + nativeError.getErrorMessage());
    }
});

// Load the native ad with a custom tag (the tag parameter is optional).
nativeAd.load("end-of-level-1");

Step 3. Show a native ad

Let's create some views to show the native ad to our users. We will just use plain Android views for this example, but feel free to design views that match the look and feel of your app.

Note: It is very important to call the registerView method, as shown in the code example below. This allows the third-party SDKs to track events like impressions and clicks, and omitting it can cause undesired behavior (such as click events not working).

import com.heyzap.sdk.ads.NativeAd.Image;

// ...

public void setupNativeAdView(final NativeAd nativeAd) {
    // This is the method called inside onAdLoaded in the previous section.
    // It will fill in the views from our XML file with the native ad's data.

    // Get the relevant data from the native ad.
    String title = nativeAd.getTitle();
    String body = nativeAd.getBody();
    String callToAction = nativeAd.getCallToAction();
    Image icon = nativeAd.getIcon();
    Image coverImage = nativeAd.getCoverImage();

    // Get the ad container (these views would need to be in our XML file).
    // Let's assume the container is hidden by default (we will show it when
    // we're done setting it up).
    RelativeLayout container = findViewById(R.id.native_ad_container);

    // Fill in the title and body of the ad.
    TextView titleView = (TextView) container.findViewById(R.id.title);
    TextView bodyView = (TextView) container.findViewById(R.id.body);
    titleView.setText(title);
    bodyView.setText(body);

    // Create ImageView and download the image (we would need to
    // implement DownloadImageTask). Height and width are available
    // if you need them for your ad design.
    String iconUrl = icon.getUrl();
    int height = icon.getHeight();
    int width = icon.getWidth();
    ImageView iconImageView =
            (ImageView) container.findViewById(R.id.icon_image);
    new DownloadImageTask(iconImageView).execute(iconUrl);

    // You can do the same as above with coverImage.

    // Set up the click listener for the install button.
    Button button = (Button) container.findViewById(R.id.button);
    button.setText(callToAction);
    button.setOnClickListener(new OnClickListener() {
        @Override
        public void onClick(View v) {
            nativeAd.doClick(v);
        }
    });

    // Register our ad view with the NativeAd.
    // This is important for the third-party SDKs to track impressions,
    // clicks, etc.
    nativeAd.registerView(container);

    // Show our ad view to the user, and record an impression.
    container.setVisibility(View.VISIBLE);
    nativeAd.doImpression();
}

Step 4. Handle click event

The NativeAd object has a doClick(view) method. You should call this method in a click listener on one of your views. Two common choices would be to have the click listener on a Button or on the entire ad container view.

Button button = (Button) container.findViewById(R.id.button);
button.setText(nativeAd.getCallToAction());
button.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View v) {
        nativeAd.doClick(v);
    }
});

(In the code example in step 3, we already set a click listener on the button.)

Step 5. Record an impression

Note: When you show a native ad to a user, it's important to call doImpression() on the NativeAd object. This is crucial to statistics tracking, and conversion rate will suffer if this method is not called.

// Do this at the same time you show the ad to the user.
nativeAd.doImpression();

(In the code example in step 3, we already called this method when we made the native ad view visible to the user.)

AdMob Native Ads

Note: AdMob native ads are currently in beta, and only released to a limited group of publishers. More information is available on the AdMob native ads documentation.

AdMob native ads work differently than other native ad networks. Because of this, you will need to implement an AdmobListener and follow AdMob's documentation to create and display a native ad. The AdmobListener has two methods, one for each of the ad types that AdMob supports. Note that only one of these methods will get called for each native ad you load.

Activity activity = this;

// Let's call this variable "heyzapNativeAd" to avoid confusion between it and
// the Admob native ads we will load.
final NativeAd heyzapNativeAd = new NativeAd(activity);

// This is the listener we implemented previously, which supports all native ad
// networks other than AdMob.
heyzapNativeAd.setListener(new NativeListener() {
    // ...
}

// This is the AdmobListener, which will be called when Heyzap mediation
// chooses AdMob to display a native ad.
heyzapNativeAd.setAdmobListener(new NativeAd.AdmobListener() {
    @Override
    public void onAppInstallAdLoaded(NativeAd heyzapNativeAd, NativeAppInstallAd appInstallAd) {
        // Follow AdMob's documentation to create and show a native ad from the
        // appInstallAd object.
        // Remember to call heyzapNativeAd.doImpression() when you show the ad
        // to the user.
    }

    @Override
    public void onContentAdLoaded(NativeAd heyzapNativeAd, NativeContentAd contentAd) {
        // Follow AdMob's documentation to create and show a native ad from the
        // contentAd object.
        // Remember to call heyzapNativeAd.doImpression() when you show the ad
        // to the user.
    }
});

Inside the methods onAppInstallAdLoaded and onContentAdLoaded, you have access to the appInstallAd and contentAd objects, which come from the AdMob native ads SDK. To create and show native ads from these objects, follow the AdMob native ads documentation.

If you want to disable either of the two AdMob native ad formats, you can pass a NativeAdOptions object to the NativeAd constructor. For example:

import com.heyzap.sdk.ads.NativeAd.NativeAdOptions;
// ...

NativeAdOptions nativeAdOptions = new NativeAdOptions();

// Let's disable AdMob ContentAds:
nativeAdOptions.setAdMobContentAdsEnabled(false);

// If you wanted to disable AdMob AppInstallAds, you would do:
// nativeAdOptions.setAdMobAppInstallAds(false);

// Pass the NativeAdOptions to the constructor of your NativeAd:
NativeAd nativeAd = new NativeAd(nativeAdOptions);

Just like we did in the previous section, remember to call heyzapNativeAd.doImpression() when you show an Admob native ad to the user. This is crucial to statistics tracking.