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:
- This class inherits from the Android
ViewGroup
class and displays the AFSMA ads. TheSearchAdView
makes the request for an ad with aDynamicHeightSearchAdRequest
and renders the returned ads. TheSearchAdView
should be added to any of the app's existing view groups. - The
SearchAdView
must be instantiated with the context that theSearchAdView
is running in, typically anActivity
. - Once the
SearchAdView
is instantiated, you must call thesetAdSize()
method withAdSize.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:
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
|
Summary:
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:
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:
The device ID is used to help with fraud and abuse monitoring, as well as ad performance measurement. |