Added in[API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  
Also in[Ad Services Extensions 4](https://developer.android.com/sdkExtensions)  
Summary:[Methods](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#pubmethods)\|[Inherited Methods](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#inhmethods)  

# AdSelectionManager

`
public


class
AdSelectionManager
`  
`

extends `[Object](https://developer.android.com/reference/java/lang/Object)`


``


`

|---|---------------------------------------------------|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.adservices.adselection.AdSelectionManager |

<br />

*** ** * ** ***

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

## Summary

|                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ### Public methods                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               ||
|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` static `[AdSelectionManager](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager)  | ` `[get](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#get(android.content.Context))`(`[Context](https://developer.android.com/reference/android/content/Context)` context) ` Factory method for creating an instance of AdSelectionManager.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ` void`                                                                                                                                              | ` `[getAdSelectionData](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#getAdSelectionData(android.adservices.adselection.GetAdSelectionDataRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.GetAdSelectionDataOutcome,java.lang.Exception>))`(`[GetAdSelectionDataRequest](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/GetAdSelectionDataRequest)` request, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[GetAdSelectionDataOutcome](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/GetAdSelectionDataOutcome)`, `[Exception](https://developer.android.com/reference/java/lang/Exception)`> receiver) ` Collects custom audience data from device.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ` `[TestAdSelectionManager](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/TestAdSelectionManager) | ` `[getTestAdSelectionManager](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#getTestAdSelectionManager())`() `                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ` void`                                                                                                                                              | ` `[persistAdSelectionResult](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#persistAdSelectionResult(android.adservices.adselection.PersistAdSelectionResultRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>))`(`[PersistAdSelectionResultRequest](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/PersistAdSelectionResultRequest)` request, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[AdSelectionOutcome](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionOutcome)`, `[Exception](https://developer.android.com/reference/java/lang/Exception)`> receiver) ` Persists the ad selection results from the server-side.                                                                                                                                                                                                                                                                                                                                                                                                    |
| ` void`                                                                                                                                              | ` `[reportEvent](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#reportEvent(android.adservices.adselection.ReportEventRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>))`(`[ReportEventRequest](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/ReportEventRequest)` request, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[Object](https://developer.android.com/reference/java/lang/Object)`, `[Exception](https://developer.android.com/reference/java/lang/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#reportImpression(android.adservices.adselection.ReportImpressionRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>))`(`[ReportImpressionRequest](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/ReportImpressionRequest)` request, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[Object](https://developer.android.com/reference/java/lang/Object)`, `[Exception](https://developer.android.com/reference/java/lang/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#selectAds(android.adservices.adselection.AdSelectionFromOutcomesConfig,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>))`(`[AdSelectionFromOutcomesConfig](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionFromOutcomesConfig)` adSelectionFromOutcomesConfig, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[AdSelectionOutcome](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionOutcome)`, `[Exception](https://developer.android.com/reference/java/lang/Exception)`> receiver) ` Selects an ad from the results of previously ran ad selections.                                                                                                                                                                                                                                                                                                                                                                                                          |
| ` void`                                                                                                                                              | ` `[selectAds](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#selectAds(android.adservices.adselection.AdSelectionConfig,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>))`(`[AdSelectionConfig](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionConfig)` adSelectionConfig, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[AdSelectionOutcome](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionOutcome)`, `[Exception](https://developer.android.com/reference/java/lang/Exception)`> receiver) ` Runs the ad selection process on device to select a remarketing ad for the caller application.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ` void`                                                                                                                                              | ` `[updateAdCounterHistogram](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#updateAdCounterHistogram(android.adservices.adselection.UpdateAdCounterHistogramRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>))`(`[UpdateAdCounterHistogramRequest](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/UpdateAdCounterHistogramRequest)` updateAdCounterHistogramRequest, `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, `[OutcomeReceiver](https://developer.android.com/reference/android/os/OutcomeReceiver)`<`[Object](https://developer.android.com/reference/java/lang/Object)`, `[Exception](https://developer.android.com/reference/java/lang/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)](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#selectAds(android.adservices.adselection.AdSelectionConfig,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>)). |

| ### Inherited methods |
|-----------------------|---|
| From class` `[java.lang.Object](https://developer.android.com/reference/java/lang/Object)` ` |--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` `[Object](https://developer.android.com/reference/java/lang/Object)          | ` `[clone](https://developer.android.com/reference/java/lang/Object#clone())`() ` Creates and returns a copy of this object.                                                                                                                                                      | | ` boolean`                                                                     | ` `[equals](https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object))`(`[Object](https://developer.android.com/reference/java/lang/Object)` obj) ` Indicates whether some other object is "equal to" this one.                                           | | ` void`                                                                        | ` `[finalize](https://developer.android.com/reference/java/lang/Object#finalize())`() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.                                                          | | ` final `[Class](https://developer.android.com/reference/java/lang/Class)`<?>` | ` `[getClass](https://developer.android.com/reference/java/lang/Object#getClass())`() ` Returns the runtime class of this`Object`.                                                                                                                                                | | ` int`                                                                         | ` `[hashCode](https://developer.android.com/reference/java/lang/Object#hashCode())`() ` Returns a hash code value for the object.                                                                                                                                                 | | ` final void`                                                                  | ` `[notify](https://developer.android.com/reference/java/lang/Object#notify())`() ` Wakes up a single thread that is waiting on this object's monitor.                                                                                                                            | | ` final void`                                                                  | ` `[notifyAll](https://developer.android.com/reference/java/lang/Object#notifyAll())`() ` Wakes up all threads that are waiting on this object's monitor.                                                                                                                         | | ` `[String](https://developer.android.com/reference/java/lang/String)          | ` `[toString](https://developer.android.com/reference/java/lang/Object#toString())`() ` Returns a string representation of the object.                                                                                                                                            | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long,%20int))`(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](https://developer.android.com/reference/java/lang/Object#wait(long))`(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](https://developer.android.com/reference/java/lang/Object#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](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  
Also in[Ad Services Extensions 6](https://developer.android.com/sdkExtensions)  

```
public static AdSelectionManager get (Context context)
```

Factory method for creating an instance of AdSelectionManager.

<br />

|                                                                  Parameters                                                                  ||
|-----------|-----------------------------------------------------------------------------------------------------------------------------------|
| `context` | `Context`: The[Context](https://developer.android.com/reference/android/content/Context)to use This value cannot be`null`. <br /> |

|                                                                                                                                                             Returns                                                                                                                                                              ||
|-------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [AdSelectionManager](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager) | A[AdSelectionManager](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager)instance This value cannot be`null`. <br /> |

### getAdSelectionData

[**Added in Android UpsideDownCakePrivacySandbox**](https://developer.android.com/preview)  

```
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](https://developer.android.com/design-for-safety/privacy-sandbox/protected-audience-bidding-and-auction-services).

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

See[AdSelectionManager#persistAdSelectionResult](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#persistAdSelectionResult(android.adservices.adselection.PersistAdSelectionResultRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>))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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/GetAdSelectionDataOutcome)for a successful run, or an[Exception](https://developer.android.com/reference/java/lang/Exception)includes the type of the exception thrown and the corresponding error message.

If the[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the[IllegalStateException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/java/util/concurrent/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](https://developer.android.com/reference/android/os/LimitExceededException)is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the[SecurityException](https://developer.android.com/reference/java/lang/SecurityException)is thrown, it is caused when the caller is not authorized or permission is not requested.  
Requires[AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                                                                                                                                                                                                                                                                                               Parameters                                                                                                                                                                                                                                                                                                ||
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `request`  | `GetAdSelectionDataRequest`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `executor` | `Executor`: This value cannot be`null`. Callback and listener events are dispatched through this[Executor](https://developer.android.com/reference/java/util/concurrent/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()](https://developer.android.com/reference/android/content/Context#getMainExecutor()). Otherwise, provide an[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)that dispatches to an appropriate thread. <br /> |
| `receiver` | `OutcomeReceiver`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### getTestAdSelectionManager

Added in[API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  
Also in[Ad Services Extensions 4](https://developer.android.com/sdkExtensions)  

```
public TestAdSelectionManager getTestAdSelectionManager ()
```

<br />

<br />

|                                                                                        Returns                                                                                        ||
|---------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [TestAdSelectionManager](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/TestAdSelectionManager) | This value cannot be`null`. <br /> |

### persistAdSelectionResult

[**Added in Android UpsideDownCakePrivacySandbox**](https://developer.android.com/preview)  

```
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](https://developer.android.com/design-for-safety/privacy-sandbox/protected-audience-bidding-and-auction-services)

See[AdSelectionManager#getAdSelectionData](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#getAdSelectionData(android.adservices.adselection.GetAdSelectionDataRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.GetAdSelectionDataOutcome,java.lang.Exception>))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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionOutcome)for a successful run, or an[Exception](https://developer.android.com/reference/java/lang/Exception)includes the type of the exception thrown and the corresponding error message.

If the[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the[IllegalStateException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/java/util/concurrent/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](https://developer.android.com/reference/android/os/LimitExceededException)is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the[SecurityException](https://developer.android.com/reference/java/lang/SecurityException)is thrown, it is caused when the caller is not authorized or permission is not requested.  
Requires[AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                                                                                                                                                                                                                                                                                               Parameters                                                                                                                                                                                                                                                                                                ||
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `request`  | `PersistAdSelectionResultRequest`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `executor` | `Executor`: This value cannot be`null`. Callback and listener events are dispatched through this[Executor](https://developer.android.com/reference/java/util/concurrent/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()](https://developer.android.com/reference/android/content/Context#getMainExecutor()). Otherwise, provide an[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)that dispatches to an appropriate thread. <br /> |
| `receiver` | `OutcomeReceiver`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### reportEvent

[**Added in Android UpsideDownCakePrivacySandbox**](https://developer.android.com/preview)  

```
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()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/ReportEventRequest#getKey()), the service will fetch the`reportingUri`that was registered in`registerAdBeacon`. See documentation of[reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver)](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#reportImpression(android.adservices.adselection.ReportImpressionRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>))for more details regarding`registerAdBeacon`. Then, the service will attach[ReportEventRequest#getData()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/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](https://developer.android.com/reference/java/lang/Object)for a successful run, or an[Exception](https://developer.android.com/reference/java/lang/Exception)includes the type of the exception thrown and the corresponding error message.

If the[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)is thrown, it is caused by invalid input argument the API received to report the ad event.

If the[IllegalStateException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/android/os/LimitExceededException)is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the[SecurityException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                              Parameters                              ||
|------------|----------------------------------------------------------|
| `request`  | `ReportEventRequest`: This value cannot be`null`. <br /> |
| `executor` | `Executor`: This value cannot be`null`. <br />           |
| `receiver` | `OutcomeReceiver`: This value cannot be`null`. <br />    |

### reportImpression

Added in[API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  
Also in[Ad Services Extensions 4](https://developer.android.com/sdkExtensions)  

```
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()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionConfig#getDecisionLogicUri())found at[ReportImpressionRequest.getAdSelectionConfig()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/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()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/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()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/customaudience/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()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/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()](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/ReportEventRequest#getKey())when the SDK invokes[reportEvent(ReportEventRequest, Executor, OutcomeReceiver)](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#reportEvent(android.adservices.adselection.ReportEventRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>)). In addition, each`event_reporting_uri`should parse properly into a[Uri](https://developer.android.com/reference/android/net/Uri). This will be the[Uri](https://developer.android.com/reference/android/net/Uri)reported to when the SDK invokes[reportEvent(ReportEventRequest, Executor, OutcomeReceiver)](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#reportEvent(android.adservices.adselection.ReportEventRequest,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Object,java.lang.Exception>)).

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. `registerAdBeacon`is 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](https://developer.android.com/reference/java/lang/Object)for a successful run, or an[Exception](https://developer.android.com/reference/java/lang/Exception)includes the type of the exception thrown and the corresponding error message.

If the[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)is thrown, it is caused by invalid input argument the API received to report the impression.

If the[IllegalStateException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/android/os/LimitExceededException)is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the[SecurityException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                                Parameters                                 ||
|------------|---------------------------------------------------------------|
| `request`  | `ReportImpressionRequest`: This value cannot be`null`. <br /> |
| `executor` | `Executor`: This value cannot be`null`. <br />                |
| `receiver` | `OutcomeReceiver`: This value cannot be`null`. <br />         |

### selectAds

[**Added in Android UpsideDownCakePrivacySandbox**](https://developer.android.com/preview)  

```
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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionFromOutcomesConfig)will throws an[TransactionTooLargeException](https://developer.android.com/reference/android/os/TransactionTooLargeException).

The output is passed by the receiver, which either returns an[AdSelectionOutcome](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionOutcome)for a successful run, or an[Exception](https://developer.android.com/reference/java/lang/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdTechIdentifier). Otherwise,[IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException)will be thrown.
- `List of ad selection ids`should exist and come from[selectAds(AdSelectionConfig, Executor, OutcomeReceiver)](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#selectAds(android.adservices.adselection.AdSelectionConfig,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>))calls originated from the same application. Otherwise,[IllegalArgumentException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/java/lang/IllegalArgumentException)will be thrown.

  Prebuilt URIs are a way of substituting a generic pre-built logic 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](https://developer.android.com/reference/java/lang/IllegalArgumentException)will be thrown.

  See[AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri(android.net.Uri))for supported`<name>`and required`<script-generation-parameters>`.

If the[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the[IllegalStateException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/java/util/concurrent/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](https://developer.android.com/reference/android/os/LimitExceededException)is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the[SecurityException](https://developer.android.com/reference/java/lang/SecurityException)is thrown, it is caused when the caller is not authorized or permission is not requested.  
Requires[AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                                                                                                                                                                                                                                                                                                          Parameters                                                                                                                                                                                                                                                                                                          ||
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `adSelectionFromOutcomesConfig` | `AdSelectionFromOutcomesConfig`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `executor`                      | `Executor`: This value cannot be`null`. Callback and listener events are dispatched through this[Executor](https://developer.android.com/reference/java/util/concurrent/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()](https://developer.android.com/reference/android/content/Context#getMainExecutor()). Otherwise, provide an[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)that dispatches to an appropriate thread. <br /> |
| `receiver`                      | `OutcomeReceiver`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### selectAds

Added in[API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/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](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionConfig)will throws an[TransactionTooLargeException](https://developer.android.com/reference/android/os/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](https://developer.android.com/reference/java/lang/IllegalArgumentException)will be thrown.

Prebuilt URIs are a way of substituting a generic pre-built logic 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](https://developer.android.com/reference/java/lang/IllegalArgumentException)will be thrown.

See[AdSelectionConfig.Builder#setDecisionLogicUri](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionConfig.Builder#setDecisionLogicUri(android.net.Uri))for supported`<name>`and required`<script-generation-parameters>`.

The output is passed by the receiver, which either returns an[AdSelectionOutcome](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionOutcome)for a successful run, or an[Exception](https://developer.android.com/reference/java/lang/Exception)includes the type of the exception thrown and the corresponding error message.

If the[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException)is thrown, it is caused by invalid input argument the API received to run the ad selection.

If the[IllegalStateException](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/java/util/concurrent/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](https://developer.android.com/reference/android/os/LimitExceededException)is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the[SecurityException](https://developer.android.com/reference/java/lang/SecurityException)is thrown, it is caused when the caller is not authorized or permission is not requested.  
Requires[AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                                                                                                                                                                                                                                                                                                    Parameters                                                                                                                                                                                                                                                                                                    ||
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `adSelectionConfig` | `AdSelectionConfig`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `executor`          | `Executor`: This value cannot be`null`. Callback and listener events are dispatched through this[Executor](https://developer.android.com/reference/java/util/concurrent/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()](https://developer.android.com/reference/android/content/Context#getMainExecutor()). Otherwise, provide an[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)that dispatches to an appropriate thread. <br /> |
| `receiver`          | `OutcomeReceiver`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### updateAdCounterHistogram

[**Added in Android UpsideDownCakePrivacySandbox**](https://developer.android.com/preview)  

```
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)](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/adselection/AdSelectionManager#selectAds(android.adservices.adselection.AdSelectionConfig,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<android.adservices.adselection.AdSelectionOutcome,java.lang.Exception>)).

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](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/java/lang/IllegalStateException)is returned via the`outcomeReceiver`if the call does not come from an app with a foreground activity.

A[LimitExceededException](https://developer.android.com/reference/android/os/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](https://developer.android.com/reference/java/lang/Object). Note that to protect user privacy, internal errors will not be sent back via an exception.  
Requires[AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE](https://developer.android.com/design-for-safety/privacy-sandbox/reference/adservices/common/AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE)

<br />

|                                                                                                                                                                                                                                                                                                           Parameters                                                                                                                                                                                                                                                                                                           ||
|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updateAdCounterHistogramRequest` | `UpdateAdCounterHistogramRequest`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `executor`                        | `Executor`: This value cannot be`null`. Callback and listener events are dispatched through this[Executor](https://developer.android.com/reference/java/util/concurrent/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()](https://developer.android.com/reference/android/content/Context#getMainExecutor()). Otherwise, provide an[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)that dispatches to an appropriate thread. <br /> |
| `outcomeReceiver`                 | `OutcomeReceiver`: This value cannot be`null`. <br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |