Added in API level 34
Also in Ad Services Extensions 4

Summary: Methods | Inherited Methods

AdSelectionManager

---

Kotlin |Java

public class AdSelectionManager
extends Object

java.lang.Object
↳	android.adservices.adselection.AdSelectionManager

---

AdSelection Manager provides APIs for app and ad-SDKs to run ad selection processes as well as report impressions.

Summary

Public methods
static AdSelectionManager	get(Context context) Factory method for creating an instance of AdSelectionManager.
void	getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver) Collects custom audience data from device.
TestAdSelectionManager	getTestAdSelectionManager()
void	persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver) Persists the ad selection results from the server-side.
void	reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver) Notifies the service that there is a new ad event to report for the ad selected by the ad-selection run identified by adSelectionId.
void	reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver) Notifies the service that there is a new impression to report for the ad selected by the ad-selection run identified by adSelectionId.
void	selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver) Selects an ad from the results of previously ran ad selections.
void	selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver) Runs the ad selection process on device to select a remarketing ad for the caller application.
void	setAppInstallAdvertisers(SetAppInstallAdvertisersRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver) Gives the provided list of adtechs the ability to do app install filtering on the calling app.
void	updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver) Updates the counter histograms for an ad which was previously selected by a call to selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

get

Added in API level 34
Also in Ad Services Extensions 6

public static AdSelectionManager get (Context context)

Factory method for creating an instance of AdSelectionManager.

Parameters
context	Context: The Context to use This value cannot be null.

Returns
AdSelectionManager	A AdSelectionManager instance This value cannot be null.

getAdSelectionData

Added in API level 35
Also in Ad Services Extensions 10

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

Collects custom audience data from device. Returns a compressed and encrypted blob to send to auction servers for ad selection. For more details, please visit Bidding and Auction Services Explainer.

Custom audience ads must have a ad_render_id to be eligible for to be collected.

See AdSelectionManager.persistAdSelectionResult for how to process the results of the ad selection run on server-side with the blob generated by this API.

The output is passed by the receiver, which either returns an GetAdSelectionDataOutcome for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the TimeoutException is thrown, it is caused when a timeout is encountered during bidding, scoring, or overall selection process to find winning Ad.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
request	GetAdSelectionDataRequest: This value cannot be null.
executor	Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
receiver	OutcomeReceiver: This value cannot be null.

getTestAdSelectionManager

Added in API level 34
Also in Ad Services Extensions 4

public TestAdSelectionManager getTestAdSelectionManager ()

Returns
TestAdSelectionManager	This value cannot be null.

persistAdSelectionResult

Added in API level 35
Also in Ad Services Extensions 10

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Persists the ad selection results from the server-side. For more details, please visit Bidding and Auction Services Explainer

See AdSelectionManager.getAdSelectionData for how to generate an encrypted blob to run an ad selection on the server side.

The output is passed by the receiver, which either returns an AdSelectionOutcome for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message. The AdSelectionOutcome.getAdSelectionId() is not guaranteed to be the same as the PersistAdSelectionResultRequest.getAdSelectionDataId() or the deprecated PersistAdSelectionResultRequest.getAdSelectionId().

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the TimeoutException is thrown, it is caused when a timeout is encountered during bidding, scoring, or overall selection process to find winning Ad.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
request	PersistAdSelectionResultRequest: This value cannot be null.
executor	Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
receiver	OutcomeReceiver: This value cannot be null.

reportEvent

Added in API level 35
Also in Ad Services Extensions 8

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Notifies the service that there is a new ad event to report for the ad selected by the ad-selection run identified by adSelectionId. An ad event is any occurrence that happens to an ad associated with the given adSelectionId. There is no guarantee about when the ad event will be reported. The event reporting could be delayed and reports could be batched.

Using ReportEventRequest.getKey(), the service will fetch the reportingUri that was registered in registerAdBeacon. See documentation of reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) for more details regarding registerAdBeacon. Then, the service will attach ReportEventRequest.getData() to the request body of a POST request and send the request. The body of the POST request will have the content-type of text/plain, and the data will be transmitted in charset=UTF-8.

The output is passed by the receiver, which either returns an empty Object for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to report the ad event.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.

Events will be reported at most once as a best-effort attempt.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
request	ReportEventRequest: This value cannot be null.
executor	Executor: This value cannot be null.
receiver	OutcomeReceiver: This value cannot be null.

reportImpression

Added in API level 34
Also in Ad Services Extensions 4

public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Notifies the service that there is a new impression to report for the ad selected by the ad-selection run identified by adSelectionId. There is no guarantee about when the impression will be reported. The impression reporting could be delayed and reports could be batched.

To calculate the winning seller reporting URL, the service fetches the seller's JavaScript logic from the AdSelectionConfig.getDecisionLogicUri() found at ReportImpressionRequest.getAdSelectionConfig(). Then, the service executes one of the functions found in the seller JS called reportResult, providing on-device signals as well as ReportImpressionRequest.getAdSelectionConfig() as input parameters.

The function definition of reportResult is:

function reportResult(ad_selection_config, render_url, bid, contextual_signals) { return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url } }; }

To calculate the winning buyer reporting URL, the service fetches the winning buyer's JavaScript logic which is fetched via the buyer's CustomAudience.getBiddingLogicUri(). Then, the service executes one of the functions found in the buyer JS called reportWin, providing on-device signals, signals_for_buyer calculated by reportResult, and specific fields from ReportImpressionRequest.getAdSelectionConfig() as input parameters.

The function definition of reportWin is:

function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer, contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results': {'reporting_url': reporting_url } }; }

In addition, buyers and sellers have the option to register to receive reports on specific ad events. To do so, they can invoke the platform provided registerAdBeacon function inside reportWin and reportResult for buyers and sellers, respectively.

The function definition of registerBeacon is:

function registerAdBeacon(beacons), where beacons is a dict of string to string pairs

For each ad event a buyer/seller is interested in reports for, they would add an event_key: event_reporting_uri pair to the beacons dict, where event_key is an identifier for that specific event. This event_key should match ReportEventRequest.getKey() when the SDK invokes reportEvent(ReportEventRequest, Executor, OutcomeReceiver). In addition, each event_reporting_uri should parse properly into a Uri. This will be the Uri reported to when the SDK invokes reportEvent(ReportEventRequest, Executor, OutcomeReceiver).

When the buyer/seller has added all the pairings they want to receive events for, they can invoke registerAdBeacon(beacons), where beacons is the name of the dict they added the pairs to.

registerAdBeacon will throw a TypeError in these situations:

1. registerAdBeaconis called more than once. If this error is caught in reportWin/reportResult, the original set of pairings will be registered
2. registerAdBeacon doesn't have exactly 1 dict argument.
3. The contents of the 1 dict argument are not all String: String pairings.

The output is passed by the receiver, which either returns an empty Object for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to report the impression.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.

Impressions will be reported at most once as a best-effort attempt.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
request	ReportImpressionRequest: This value cannot be null.
executor	Executor: This value cannot be null.
receiver	OutcomeReceiver: This value cannot be null.

selectAds

Added in API level 35
Also in Ad Services Extensions 10

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Selects an ad from the results of previously ran ad selections.

The input adSelectionFromOutcomesConfig is provided by the Ads SDK and the AdSelectionFromOutcomesConfig object is transferred via a Binder call. For this reason, the total size of these objects is bound to the Android IPC limitations. Failures to transfer the AdSelectionFromOutcomesConfig will throws an TransactionTooLargeException.

The output is passed by the receiver, which either returns an AdSelectionOutcome for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

The input adSelectionFromOutcomesConfig contains:

• Seller is required to be a registered AdTechIdentifier. Otherwise, IllegalStateException will be thrown.
• List of ad selection ids should exist and come from selectAds(AdSelectionConfig, Executor, OutcomeReceiver) calls originated from the same application. Otherwise, IllegalArgumentException for input validation will raise listing violating ad selection ids.
• Selection logic URI that could follow either the HTTPS or Ad Selection Prebuilt schemas.

  If the URI follows HTTPS schema then the host should match the seller. Otherwise, IllegalArgumentException will be thrown.

  Prebuilt URIs are a way of substituting a generic pre-built logics for the required JavaScripts for selectOutcome. Prebuilt Uri for this endpoint should follow;

  • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

  If an unsupported prebuilt URI is passed or prebuilt URI feature is disabled by the service then IllegalArgumentException will be thrown.

  See AdSelectionFromOutcomesConfig.Builder.setSelectionLogicUri for supported <name> and required <script-generation-parameters>.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the TimeoutException is thrown, it is caused when a timeout is encountered during bidding, scoring, or overall selection process to find winning Ad.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
adSelectionFromOutcomesConfig	AdSelectionFromOutcomesConfig: This value cannot be null.
executor	Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
receiver	OutcomeReceiver: This value cannot be null.

selectAds

Added in API level 34
Also in Ad Services Extensions 10

public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Runs the ad selection process on device to select a remarketing ad for the caller application.

The input adSelectionConfig is provided by the Ads SDK and the AdSelectionConfig object is transferred via a Binder call. For this reason, the total size of these objects is bound to the Android IPC limitations. Failures to transfer the AdSelectionConfig will throws an TransactionTooLargeException.

The input adSelectionConfig contains Decision Logic Uri that could follow either the HTTPS or Ad Selection Prebuilt schemas.

If the URI follows HTTPS schema then the host should match the seller. Otherwise, IllegalArgumentException will be thrown.

Prebuilt URIs are a way of substituting a generic pre-built logics for the required JavaScripts for scoreAds. Prebuilt Uri for this endpoint should follow;

• ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

If an unsupported prebuilt URI is passed or prebuilt URI feature is disabled by the service then IllegalArgumentException will be thrown.

See AdSelectionConfig.Builder.setDecisionLogicUri for supported <name> and required <script-generation-parameters>.

The output is passed by the receiver, which either returns an AdSelectionOutcome for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the TimeoutException is thrown, it is caused when a timeout is encountered during bidding, scoring, or overall selection process to find winning Ad.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
adSelectionConfig	AdSelectionConfig: This value cannot be null.
executor	Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
receiver	OutcomeReceiver: This value cannot be null.

setAppInstallAdvertisers

Added in API level 35
Also in Ad Services Extensions 12

public void setAppInstallAdvertisers (SetAppInstallAdvertisersRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Gives the provided list of adtechs the ability to do app install filtering on the calling app.

The input request is provided by the Ads SDK and the request object is transferred via a Binder call. For this reason, the total size of these objects is bound to the Android IPC limitations. Failures to transfer the advertisers will throws an TransactionTooLargeException.

The output is passed by the receiver, which either returns an empty Object for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
request	SetAppInstallAdvertisersRequest: This value cannot be null.
executor	Executor: This value cannot be null.
receiver	OutcomeReceiver: This value cannot be null.

updateAdCounterHistogram

Added in API level 35
Also in Ad Services Extensions 8

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

Updates the counter histograms for an ad which was previously selected by a call to selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

The counter histograms are used in ad selection to inform frequency cap filtering on candidate ads, where ads whose frequency caps are met or exceeded are removed from the bidding process during ad selection.

Counter histograms can only be updated for ads specified by the given adSelectionId returned by a recent call to FLEDGE ad selection from the same caller app.

A SecurityException is returned via the outcomeReceiver if:

1. the app has not declared the correct permissions in its manifest, or
2. the app or entity identified by the callerAdTechIdentifier are not authorized to use the API.

An IllegalStateException is returned via the outcomeReceiver if the call does not come from an app with a foreground activity.

A LimitExceededException is returned via the outcomeReceiver if the call exceeds the calling app's API throttle.

In all other failure cases, the outcomeReceiver will return an empty Object. Note that to protect user privacy, internal errors will not be sent back via an exception.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE or AdServicesPermissions.ACCESS_ADSERVICES_PROTECTED_SIGNALS or AdServicesPermissions.ACCESS_ADSERVICES_AD_SELECTION

Parameters
updateAdCounterHistogramRequest	UpdateAdCounterHistogramRequest: This value cannot be null.
executor	Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
outcomeReceiver	OutcomeReceiver: This value cannot be null.