AdSelectionManager

get

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.

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

Returns
TestAdSelectionManager	This value cannot be null.

reportImpression

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

Report the given impression. The ReportImpressionRequest is provided by the Ads SDK. The receiver either returns a void for a successful run, or an Exception indicates the error.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

reportInteraction

public void reportInteraction (ReportInteractionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

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

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 interaction.

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.

Interactions will be reported at most once as a best-effort attempt.
Requires AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

selectAds

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

Parameters
adSelectionFromOutcomesConfig	AdSelectionFromOutcomesConfig: This value cannot be null.
executor	Executor: This value cannot be null.
receiver	OutcomeReceiver: This value cannot be null.

selectAds

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

Parameters
adSelectionConfig	AdSelectionConfig: This value cannot be null.
executor	Executor: This value cannot be null.
receiver	OutcomeReceiver: This value cannot be null.

setAppInstallAdvertisers

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

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

updateAdCounterHistogram

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

Parameters
updateAdCounterHistogramRequest	UpdateAdCounterHistogramRequest: This value cannot be null.
executor	Executor: This value cannot be null.
outcomeReceiver	OutcomeReceiver: This value cannot be null.