AdSelectionManager
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. |
TestAdSelectionManager
|
getTestAdSelectionManager()
|
void
|
reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
Report the given impression. |
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 |
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 |
Inherited methods | |
---|---|
Public methods
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 registeredAdTechIdentifier
. Otherwise,IllegalStateException
will be thrown.List of ad selection ids
should exist and come fromselectAds(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:
- the app has not declared the correct permissions in its manifest, or
- the app or entity identified by the
callerAdTechIdentifier
are not authorized to use the API.
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 . |