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");
builder.setNumber(2);

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

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(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.

Prepare for Google Play's data disclosure requirements

In May 2021, Google Play announced the new Data safety section, which is a developer-provided disclosure for an app's data collection, sharing, and security practices.

This page can help you complete the requirements for this data disclosure in regards to your usage of the AFS Native SDK (also applicable for AdSense for Shopping usage). On this page, you can find information on whether and how our SDKs handle end-user data.

We aim to be as transparent as possible in supporting you; however, as the app developer, you are solely responsible for deciding how to respond to Google Play's Data safety section form regarding your app's end-user data collection, sharing, and security practices.

How to use the information on this page

This page lists the end-user data collected by only the latest version of the SDK.

To complete your data disclosure, you can use Android's guide about data types to help you determine which data type best describes the collected data. In your data disclosure, make sure to also account for how your specific app shares and uses the collected data.

Data type SDK accesses and collects

Packages:

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

Data collected automatically

The AFS SDK collects the following data automatically. All data is transmitted off of the device to Google for the purpose of serving ads, and all data is encrypted in transit. The user’s personal information is never collected, unless sent in a user query by your app.

Data This data is collected for the following purposes...
IP address Summary:
  • Fraud prevention, security, and compliance
  • Advertising or marketing
  • Derive approximate location
Detail:
IP address is used in fraud and abuse monitoring, as well as used to derive approximate user location.

Approximate location is then used to ensure ads served can conform to local regulations, and to provide ads relevant to a user’s coarse geographical location.

App activity
  • Page views and taps in app
  • In-app search history
 Summary:
  • Analytics
  • Fraud prevention, security, and compliance
  • Advertising or marketing
  • Personalization
Detail:
Your app provides us with the user’s query in order for us to return Search Ads relevant to the keyword. We measure views and engagement (taps) with the ads that are returned.
Diagnostics Summary:
  • Analytics
Detail:
The SDK measures rendering latency for ads in order to allow for product improvements to be implemented and measured. We also send crash/error reports and occasionally add other instrumentation as needed to understand how functionality is used by publishers.
Device or other identifiers Summary:
  • Fraud prevention, security, and compliance
  • Advertising or marketing
Detail:
The device ID is used to help with fraud and abuse monitoring, as well as ad performance measurement.