CustomAudienceManager

open class CustomAudienceManager
kotlin.Any
   ↳ android.adservices.customaudience.CustomAudienceManager

CustomAudienceManager provides APIs for app and ad-SDKs to join / leave custom audiences.

Summary

Public methods
open Unit
fetchAndJoinCustomAudience(fetchAndJoinCustomAudienceRequest: FetchAndJoinCustomAudienceRequest, executor: Executor, receiver: OutcomeReceiver<Any!, Exception!>)

Adds the user to the CustomAudience fetched from a fetchUri.
open static CustomAudienceManager
get(context: Context)

Factory method for creating an instance of CustomAudienceManager.
open TestCustomAudienceManager

Create a service with test-enabling APIs
open Unit
joinCustomAudience(joinCustomAudienceRequest: JoinCustomAudienceRequest, executor: Executor, receiver: OutcomeReceiver<Any!, Exception!>)

Adds the user to the given CustomAudience.
open Unit
leaveCustomAudience(leaveCustomAudienceRequest: LeaveCustomAudienceRequest, executor: Executor, receiver: OutcomeReceiver<Any!, Exception!>)

Attempts to remove a user from a custom audience by deleting any existing CustomAudience data, identified by ownerPackageName, buyer, and name.

Public methods

fetchAndJoinCustomAudience

Added in API level 35
Also in Ad Services Extensions 10
open fun fetchAndJoinCustomAudience(
    fetchAndJoinCustomAudienceRequest: FetchAndJoinCustomAudienceRequest, 
    executor: Executor, 
    receiver: OutcomeReceiver<Any!, Exception!>
): Unit

Adds the user to the CustomAudience fetched from a fetchUri.

An attempt to register the user for a custom audience with the same combination of ownerPackageName, buyer, and name will cause the existing custom audience's information to be overwritten, including the list of ads data.

Note that the ads list can be completely overwritten by the daily background fetch job.

This call fails with an SecurityException if

  1. the ownerPackageName is not calling app's package name and/or
  2. the buyer is not authorized to use the API.

This call fails with an IllegalArgumentException if

  1. the storage limit has been exceeded by the calling application and/or
  2. any URI parameters in the CustomAudience given are not authenticated with the CustomAudience buyer.

This call fails with LimitExceededException if the calling package exceeds the allowed rate limits and is throttled.

This call fails with an IllegalStateException if an internal service error is encountered.
Requires android.adservices.common.AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameters
fetchAndJoinCustomAudienceRequest FetchAndJoinCustomAudienceRequest: 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<Any!, Exception!>: This value cannot be null.

get

Added in API level 34
Also in Ad Services Extensions 6
open static fun get(context: Context): CustomAudienceManager

Factory method for creating an instance of CustomAudienceManager.

Parameters
context Context: The Context to use This value cannot be null.
Return
CustomAudienceManager A CustomAudienceManager instance This value cannot be null.

getTestCustomAudienceManager

Added in API level 34
Also in Ad Services Extensions 4
open fun getTestCustomAudienceManager(): TestCustomAudienceManager

Create a service with test-enabling APIs

Return
TestCustomAudienceManager This value cannot be null.

joinCustomAudience

Added in API level 34
Also in Ad Services Extensions 4
open fun joinCustomAudience(
    joinCustomAudienceRequest: JoinCustomAudienceRequest, 
    executor: Executor, 
    receiver: OutcomeReceiver<Any!, Exception!>
): Unit

Adds the user to the given CustomAudience.

An attempt to register the user for a custom audience with the same combination of ownerPackageName, buyer, and name will cause the existing custom audience's information to be overwritten, including the list of ads data.

Note that the ads list can be completely overwritten by the daily background fetch job.

This call fails with an SecurityException if

  1. the ownerPackageName is not calling app's package name and/or
  2. the buyer is not authorized to use the API.

This call fails with an IllegalArgumentException if

  1. the storage limit has been exceeded by the calling application and/or
  2. any URI parameters in the CustomAudience given are not authenticated with the CustomAudience buyer.

This call fails with LimitExceededException if the calling package exceeds the allowed rate limits and is throttled.

This call fails with an IllegalStateException if an internal service error is encountered.
Requires android.adservices.common.AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameters
joinCustomAudienceRequest JoinCustomAudienceRequest: 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<Any!, Exception!>: This value cannot be null.

leaveCustomAudience

Added in API level 34
Also in Ad Services Extensions 4
open fun leaveCustomAudience(
    leaveCustomAudienceRequest: LeaveCustomAudienceRequest, 
    executor: Executor, 
    receiver: OutcomeReceiver<Any!, Exception!>
): Unit

Attempts to remove a user from a custom audience by deleting any existing CustomAudience data, identified by ownerPackageName, buyer, and name.

This call fails with an SecurityException if

  1. the ownerPackageName is not calling app's package name; and/or
  2. the buyer is not authorized to use the API.

This call fails with LimitExceededException if the calling package exceeds the allowed rate limits and is throttled.

This call does not inform the caller whether the custom audience specified existed in on-device storage. In other words, it will fail silently when a buyer attempts to leave a custom audience that was not joined.
Requires android.adservices.common.AdServicesPermissions#ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parameters
leaveCustomAudienceRequest LeaveCustomAudienceRequest: 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<Any!, Exception!>: This value cannot be null.