AFS for Mobile Apps (AFSMA) Implementation for Android

Prerequisites

This implementation guide assumes you are familiar with the following:

  • AFS Custom Search Ads (CSA) implementation protocol
  • Android app development
  • Associating the Google Mobile Ads SDK for Android (now part of Google Play services) with an Android Studio project. Version 9.0.0 of Google Play services is required.

Classes

To serve AFSMA ads (also known as dynamic height search ads) in your app, implement the following classes:

SearchAdView

  • This class inherits from the Android ViewGroup class and displays the AFSMA ads. The SearchAdView makes the request for an ad with a DynamicHeightSearchAdRequest and renders the returned ads. The SearchAdView should be added 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 AFSMA ads. Other enum values will request ads not compatible with AFS for Mobile Apps.
  • Call the setAdUnitId() method on this object with your property code.

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 AFS desktop and mobile web.
  • Set parameters with the appropriate setters (in other words, call setQuery() to set the query parameter).

Example implementation

The example below demonstrates using an Activity to create a SearchAdView as a subview of a ViewGroup. To properly request AFSMA 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. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// 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. AFSMA ads are configured in the same way as AFS Custom Search Ads; see the AFS Custom Search Ads Reference for details.

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);
builder.setNumber(2);
builder.setCssWidth(300);     // Equivalent to "width" CSA parameter
builder.setIsSellerRatingsEnabled(true);
builder.setIsTitleBold(true);
builder.setIsSiteLinksEnabled(true);

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

To make an ad request, call the loadAd() method with the DynamicHeightSearchAdRequest.Builder object from the SearchAdView 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. See the AFS Custom Search Ads Reference for a complete listing of settings that can to be set with the setAdvancedOptionValue() method.

The key parameter must be prefixed with "csa_" 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_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

If you use a parameter's setter method and set it using setAdvancedOptionValue, the second call will override the value from the first call.

Investigating errors

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

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
        // (to go to the browser for example)
        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.