Android App

Prerequisites

This implementation guide assumes you are familiar with the following:

• AdSense for Shopping (AFSh) implementation protocol
• Android app development
• Associating the Google Mobile Ads SDK (now part of Google Play services) for Android with an Android Studio project. Version 9.0.0 or higher of Google Play services is required. See Get Started in Android Studio for instructions.

Overview

This document outlines the process to integrate AdSense for Shopping for Mobile Apps (AFShMA) ads in your Android mobile app. To request and render AFShMA ads on Android, use the following:

SearchAdView

• This class inherits from the Android ViewGroup class and displays the AFShMA ads. The SearchAdView makes the request for an ad with a DynamicHeightSearchAdRequest and renders the returned ads. Add theSearchAdView to any of the app's existing view groups.
• The SearchAdView must be instantiated with the context that the SearchAdView is running in, typically an Activity.
• Once the SearchAdView is instantiated, you must call the setAdSize() method with AdSize.SEARCH to request AFShMA ads. Other enum values request ads that are not compatible with AFShMA.
• Call the setAdUnitId() method on this object with your property code (for example, vert-pla-test1-srp).

DynamicHeightSearchAdRequest.Builder

• This class encapsulates the ad request parameters. This is analogous to setting parameters in the JavaScript ad request objects (page options, unit options) for AFSh desktop and mobile web.
• Set parameters with the appropriate setters (for example, set the query parameter by calling setQuery()).

Example implementation

The example below demonstrates using an Activity to create a SearchAdView as a subview of a ViewGroup. To properly request AFShMA ads, the SearchAdView object must call the setAdSize() method with AdSize.SEARCH.

//  MainActivity.java implementation (MainActivity is a subclass of Activity).

// Create the SearchAdView.
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads.
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. vert-pla-mobile-app-test1-srp).
searchAdView.setAdUnitId("vert-pla-mobile-app-################");

// Add searchAdView to parent view group.
...

Within the same Activity, create a DynamicHeightSearchAdRequest.Builder that dictates the parameters of the ad that will be rendered in the SearchAdView. AFShMA ads are configured in the same way as AFSh for web; details are available on the AdSense for Shopping reference.

// Create the ad request.
DynamicHeightSearchAdRequest.Builder builder = new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("running shoes");
builder.setAdTest(true);              // Remove when launching to production.

To request AFShMA ads, set adType to plas using the setAdvancedOptionValue() method. You must also specify a style ID.

// Set adType to "plas" to request for AFShMA ads.
// Key must be prefixed with "csa_".
builder.setAdvancedOptionValue("csa_adType", "plas");

// Replace with the ID of a shopping style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Optional: specify the number of ads to load. By default only 1 ad will be
// loaded.
builder.setNumber(2);

// Optional: set the width for the AFShMA ad block. By default the width of
// the SearchAdView will be used.
builder.setCssWidth(400);

Other customization options are possible by setting additional properties on the DynamicHeightSearchAdRequest.Builder object.

To make an ad request, call the loadAd() method on SearchAdView with an instance of DynamicHeightSearchAdRequest, which can be built from the DynamicHeightSearchAdRequest.Builder object:

searchAdView.loadAd(builder.build());

Advanced options

Most of the ad request parameters can be set via setter methods on the DynamicHeightSearchAdRequest.Builder object. Any parameters that don't have a setter method in DynamicHeightSearchAdRequest.Builder can be set using key-value pairs with the setAdvancedOptionValue() method. A complete listing of settings that can to be set with the setAdvancedOptionValue() method is provided in the Custom Search Ads Reference. The key parameter must be prefixed with "csa_" in order for the property to be set correctly.

  // Advanced customization options (set using key-value pair).

  // Set a parameter (parameter_name) and its value (parameter_value).
  // builder.setAdvancedOptionValue("csa_parameterName", "parameter_value");

Note: If you use a parameter's setter method and also set it using setAdvancedOptionValue(), the second call overrides the value from the first call.

Investigating errors

The SearchAdView (searchAdView here) contains a setAdListener() method within the same Activity to help you investigate errors:

searchAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Called when an ad is loaded.
        super.onAdLoaded();
        Toast.makeText(MainActivity.this, "Ad Loaded", Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen.
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened", Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application (e.g., to go to the browser).
        super.onAdLeftApplication();
        Toast.makeText(MainActivity.this, "Ad Left Application", Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed.
        super.onAdFailedToLoad(errorCode);
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode, Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " + errorCode);
    }
});

Constants used in the onAdFailedtoLoad() callback method are described in the API reference.