CustomAudienceManagerFutures


abstract class CustomAudienceManagerFutures


This class provides APIs for app and ad-SDKs to join / leave custom audiences. This class can be used by Java clients.

Summary

Public companion functions

CustomAudienceManagerFutures?
from(context: Context)

Creates CustomAudienceManagerFutures.

Public functions

abstract ListenableFuture<Unit>
@ExperimentalFeatures.Ext10OptIn
@RequiresPermission(value = "android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE")
fetchAndJoinCustomAudienceAsync(
    request: FetchAndJoinCustomAudienceRequest
)

Adds the user to the CustomAudience fetched from a {@code fetchUri}.

abstract ListenableFuture<Unit>
@RequiresPermission(value = "android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE")
joinCustomAudienceAsync(request: JoinCustomAudienceRequest)

Adds the user to the given CustomAudience.

abstract ListenableFuture<Unit>
@RequiresPermission(value = "android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE")
leaveCustomAudienceAsync(request: LeaveCustomAudienceRequest)

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

Public companion functions

from

Added in 1.0.0
fun from(context: Context): CustomAudienceManagerFutures?

Creates CustomAudienceManagerFutures.

Returns
CustomAudienceManagerFutures?

CustomAudienceManagerFutures object. If the device is running an incompatible build, the value returned is null.

Public functions

fetchAndJoinCustomAudienceAsync

Added in 1.1.0-beta06
@ExperimentalFeatures.Ext10OptIn
@RequiresPermission(value = "android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE")
abstract fun fetchAndJoinCustomAudienceAsync(
    request: FetchAndJoinCustomAudienceRequest
): ListenableFuture<Unit>

Adds the user to the CustomAudience fetched from a {@code fetchUri}.

An attempt to register the user for a custom audience with the same combination of {@code ownerPackageName}, {@code buyer}, and {@code 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 {@code 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.

This call fails with an UnsupportedOperationException if the Android API level and AdServices module versions don't support this API.

Parameters
request: FetchAndJoinCustomAudienceRequest

The request to fetch and join custom audience.

joinCustomAudienceAsync

Added in 1.0.0
@RequiresPermission(value = "android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE")
abstract fun joinCustomAudienceAsync(request: JoinCustomAudienceRequest): ListenableFuture<Unit>

Adds the user to the given CustomAudience.

An attempt to register the user for a custom audience with the same combination of {@code ownerPackageName}, {@code buyer}, and {@code 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 {@code 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.

Parameters
request: JoinCustomAudienceRequest

The request to join custom audience.

leaveCustomAudienceAsync

Added in 1.0.0
@RequiresPermission(value = "android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE")
abstract fun leaveCustomAudienceAsync(request: LeaveCustomAudienceRequest): ListenableFuture<Unit>

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

This call fails with an SecurityException if

  1. the {@code 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.

Parameters
request: LeaveCustomAudienceRequest

The request to leave custom audience.