SearchAdController

public final class SearchAdController extends Object

Entry point for the API for AdSense for Search (AFS) native Custom Search Ads (CSA).

Each ad context should have a separate SearchAdController. For example, if you have a page which shows ads alongside a list of search results, and other page which shows ads alongside details for a specific product, you should use two separate SearchAdControllers.

The SearchAdController should be used with the following flow:

Create the SearchAdController using the constructor, providing a listener to be notified when ads are loaded.
Call createAdView() to create an empty view to hold ads. Do not place the view into your view hierarchy yet.
When the user makes a search query, call loadAds(SearchAdRequest).
When your listener's onAdLoaded method is called, call populateAdView(View, String) to place ads into the view previously created with createAdView. Place the view into your view hierarchy. You can populate up to numAdsLoaded() views with ads.
When the user makes a new search query, call loadAds and repeat the above.

Nested Class Summary

interface SearchAdController.AdViewCompletionHandler Runs onAdViewLoaded after the ad rendering is complete.

Constant Summary

int	IS_EXPERIMENT_CONTROL
int	IS_EXPERIMENT_VARIANT
int	NOT_SELECTED_FOR_EXPERIMENT

Public Constructor Summary

SearchAdController(Context context, String partnerId, String styleId, SearchAdOptions options, AdListener adListener)

Creates a new SearchAdController.

Public Method Summary

View	createAdView() Creates an empty ad view that can be populated with a single ad with `populateAdView(View, String)`.
int	experimentVariantStatus() Returns whether the most recently served style is an experiment variant `IS_EXPERIMENT_VARIANT`, an experiment control `IS_EXPERIMENT_CONTROL`, or was not selected for an experiment `NOT_SELECTED_FOR_EXPERIMENT`.
void	loadAds(SearchAdRequest searchAdRequest) Loads ads into the cache and discards any previously loaded ads, indicating a new user search.
void	loadMoreAds() Loads more ads using the `SearchAdRequest` from the most recent call to `loadAds(SearchAdRequest)`.
int	numAdsLoaded() Returns the total number of ads loaded from the most recent call to `loadAds(SearchAdRequest)`.
void	populateAdView(View adView, String adKey) Populates an ad view with ad data previously loaded with `loadAds(SearchAdRequest)`.
void	populateAdView(View adView, String adKey, SearchAdController.AdViewCompletionHandler adViewCompletionHandler) Populates an ad view with ad data and calls `SearchAdController.AdViewCompletionHandler.onAdViewLoaded()`.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Constants

public static final int IS_EXPERIMENT_CONTROL

Constant Value: 2

public static final int IS_EXPERIMENT_VARIANT

Constant Value: 1

public static final int NOT_SELECTED_FOR_EXPERIMENT

Constant Value: 0

Public Constructors

public SearchAdController (Context context, String partnerId, String styleId, SearchAdOptions options, AdListener adListener)

Creates a new SearchAdController.

Parameters

context	The context the `SearchAdController` is running in, typically an `Activity`
partnerId	The publisher id, e.g. "ms-app-pub-9616389000213823"
styleId	The style id for the template that will be used to render native ads
options	Configuration options, such as whether to prefetch ads
adListener	Listener for receiving notifications when ads are loaded and other events

Public Methods

public View createAdView ()

Creates an empty ad view that can be populated with a single ad with populateAdView(View, String).

This same view can be recycled to display multiple ads over time with subsequent calls to populateAdView.

public int experimentVariantStatus ()

Returns whether the most recently served style is an experiment variant IS_EXPERIMENT_VARIANT, an experiment control IS_EXPERIMENT_CONTROL, or was not selected for an experiment NOT_SELECTED_FOR_EXPERIMENT.

public void loadAds (SearchAdRequest searchAdRequest)

Loads ads into the cache and discards any previously loaded ads, indicating a new user search.

Notifies the AdListener.onAdLoaded() callback when ads have successfully loaded, or the AdListener.onAdFailedToLoad(int) callback if ads fail to load.

Parameters

searchAdRequest	The ad request containing the user query and other options.

public void loadMoreAds ()

Loads more ads using the SearchAdRequest from the most recent call to loadAds(SearchAdRequest).

Notifies the AdListener.onAdLoaded() callback when ads have successfully loaded, or the AdListener.onAdFailedToLoad(int) callback if ads fail to load.

public int numAdsLoaded ()

Returns the total number of ads loaded from the most recent call to loadAds(SearchAdRequest).

public void populateAdView (View adView, String adKey)

Populates an ad view with ad data previously loaded with loadAds(SearchAdRequest).

Parameters

adView	A View previously created with a call to `createAdView()`.
adKey	An arbitrary identifier for this ad. Subsequent calls to `populateAdView` with the same identifier will return the same ad.

public void populateAdView (View adView, String adKey, SearchAdController.AdViewCompletionHandler adViewCompletionHandler)

Populates an ad view with ad data and calls SearchAdController.AdViewCompletionHandler.onAdViewLoaded().

Parameters

adView	A View previously created with a call to `createAdView()`.
adKey	An arbitrary identifier for this ad. Subsequent calls to `populateAdView` with the same identifier will return the same ad.
adViewCompletionHandler	Runs `SearchAdController.AdViewCompletionHandler.onAdViewLoaded()` once the ads have rendered.