AFS for Mobile Apps (AFSMA) Implementation for Android


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.


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


  • 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.


  • 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.

// 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)

// 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();

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setCssWidth(300);     // Equivalent to "width" CSA parameter

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:


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() {
    public void onAdLoaded() {
        // Called when an ad is loaded
        Toast.makeText(MainActivity.this, "Ad Loaded",
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");

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

    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        Toast.makeText(MainActivity.this, "Ad Left Application",
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");

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

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