此页面由 Cloud Translation API 翻译。

在 API 级别 34 中添加
也在广告服务扩展 4 中添加

摘要：方法 | 继承的方法

AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object
↳	android.adservices.adselection.AdSelectionManager

AdSelection Manager 为应用和广告 SDK 提供用于运行广告选择流程及报告展示次数的 API。

总结

公共方法
`static AdSelectionManager`	`get(Context context)` 用于创建 AdSelectionManager 实例的工厂方法。
`void`	`getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)` 从设备收集自定义受众群体数据。
`TestAdSelectionManager`	`getTestAdSelectionManager()`
`void`	`persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)` 保留来自服务器端的广告选择结果。
`void`	`reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)` 通知服务有新的广告事件要报告给由 `adSelectionId` 标识的广告选择运行所选择的广告。
`void`	`reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)` 通知服务有一次新的展示要报告给由 `adSelectionId` 标识的广告选择运行所选择的广告。
`void`	`selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)` 从之前投放的广告选择的结果中选择广告。
`void`	`selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)` 在设备上运行广告选择流程，为调用方应用选择再营销广告。
`void`	`updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)` 更新之前通过调用 `selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver)` 选择的广告的计数器直方图。

继承的方法

继承自


        
          java.lang.Object

类

`Object`	`clone()` 创建并返回此对象的副本。
`boolean`	`equals(Object obj)` 指示某个其他对象是否“等于”此对象。
`void`	`finalize()` 当垃圾回收功能确定对某个对象没有更多引用时，由垃圾回收器针对该对象调用该方法。
`final Class<?>`	`getClass()` 返回此 `Object` 的运行时类。
`int`	`hashCode()` 返回对象的哈希代码值。
`final void`	`notify()` 唤醒正在等待此对象的监控器的单个线程。
`final void`	`notifyAll()` 唤醒正在等待此对象的监控器的所有线程。
`String`	`toString()` 返回对象的字符串表示。
`final void`	`wait(long timeoutMillis, int nanos)` 导致当前线程进入等待状态，直到其被唤醒（通常在收到通知或被中断时），或者实际经过了一定的时间为止。
`final void`	`wait(long timeoutMillis)` 导致当前线程进入等待状态，直到其被唤醒（通常在收到通知或被中断时），或者实际经过了一定的时间为止。
`final void`	`wait()` 导致当前线程处于等待状态，直到其被唤醒（通常在收到通知或被中断时）。

公共方法

get

在 API 级别 34 中添加
也在广告服务扩展 6 中添加

public static AdSelectionManager get (Context context)

用于创建 AdSelectionManager 实例的工厂方法。

参数
`context`	`Context`：要使用的 `Context`。此值不能为 `null`。

返回
`AdSelectionManager`	`AdSelectionManager` 实例。此值不能为 `null`。

getAdSelectionData

在 Android UpsideDownCakePrivacySandbox 中添加的功能

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

从设备收集自定义受众群体数据。返回经过压缩和加密的 blob，以发送至竞价服务器进行广告选择。如需了解详情，请参阅出价和竞价服务说明。

自定义受众群体广告必须具有 ad_render_id，这样才能被收集。

如需了解如何使用此 API 生成的 blob 处理在服务器端运行的广告选择结果，请参阅 AdSelectionManager#persistAdSelectionResult。

输出由接收器传递，接收器会返回 GetAdSelectionDataOutcome 表示运行成功，或者 Exception 包含抛出的异常的类型和相应的错误消息。

如果抛出 IllegalArgumentException，则是由 API 为运行广告选择而收到的输入参数无效所致。

如果抛出 IllegalStateException 并给出错误消息“Failure of AdSelection services.”，则是因为广告选择服务内部故障导致的。

如果抛出 TimeoutException，则是因为在出价、评分或整体选择过程中遇到超时以找到胜出的广告。

如果抛出 LimitExceededException，则是在发起调用的软件包超出允许的速率限制并受到限制时引发的。

如果抛出 SecurityException，则是因为调用方未获授权或未请求权限而抛出。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`request`	`GetAdSelectionDataRequest`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。回调和监听器事件通过此 `Executor` 进行分派，从而提供了一种简单的方法来控制使用哪个线程。如需通过应用的主线程分派事件，您可以使用 `Context.getMainExecutor()`。否则，请提供可分派给适当线程的 `Executor`。
`receiver`	`OutcomeReceiver`：此值不能为 `null`。

getTestAdSelectionManager

在 API 级别 34 中添加
也在广告服务扩展 4 中添加

public TestAdSelectionManager getTestAdSelectionManager ()

返回
`TestAdSelectionManager`	此值不能为 `null`。

durationAdSelectionResult

在 Android UpsideDownCakePrivacySandbox 中添加的功能

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

保留服务器端的广告选择结果。如需了解详情，请参阅出价和竞价服务说明

如需了解如何生成加密的 blob，以在服务器端运行广告选择，请参阅 AdSelectionManager#getAdSelectionData。

输出由接收器传递，接收器会返回 AdSelectionOutcome 表示运行成功，或者 Exception 包含抛出的异常的类型和相应的错误消息。

如果抛出 IllegalArgumentException，则是由 API 为运行广告选择而收到的输入参数无效所致。

如果抛出 IllegalStateException 并给出错误消息“Failure of AdSelection services.”，则是因为广告选择服务内部故障导致的。

如果抛出 TimeoutException，则是因为在出价、评分或整体选择过程中遇到超时以找到胜出的广告。

如果抛出 LimitExceededException，则是在发起调用的软件包超出允许的速率限制并受到限制时引发的。

如果抛出 SecurityException，则是因为调用方未获授权或未请求权限而抛出。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`request`	`PersistAdSelectionResultRequest`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。回调和监听器事件通过此 `Executor` 进行分派，从而提供了一种简单的方法来控制使用哪个线程。如需通过应用的主线程分派事件，您可以使用 `Context.getMainExecutor()`。否则，请提供可分派给适当线程的 `Executor`。
`receiver`	`OutcomeReceiver`：此值不能为 `null`。

reportEvent

在 Android UpsideDownCakePrivacySandbox 中添加的功能

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

通知服务有新的广告事件要报告给由 adSelectionId 标识的广告选择运行所选择的广告。广告事件是指与指定 adSelectionId 关联的广告发生的任何事件。无法保证何时报告广告事件。事件报告可能会延迟，报告可能会批量处理。

使用 ReportEventRequest#getKey()，服务将提取在 registerAdBeacon 中注册的 reportingUri。如需详细了解 registerAdBeacon，请参阅 reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) 的文档。然后，服务会将 ReportEventRequest#getData() 附加到 POST 请求的请求正文并发送请求。POST 请求的正文的 content-type 为 text/plain，且数据将在 charset=UTF-8 中传输。

输出由接收器传递，接收器会返回空的 Object（如果运行成功）或者 Exception 包含抛出的异常的类型和相应的错误消息。

如果抛出 IllegalArgumentException，原因是 API 收到的用于报告广告事件的输入参数无效。

如果抛出 IllegalStateException 并给出错误消息“Failure of AdSelection services.”，则是因为广告选择服务内部故障导致的。

如果抛出 LimitExceededException，则是在发起调用的软件包超出允许的速率限制并受到限制时引发的。

如果抛出 SecurityException，则是因为调用方未获授权或未请求权限而抛出。

我们会尽最大努力报告一次事件。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`request`	`ReportEventRequest`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。
`receiver`	`OutcomeReceiver`：此值不能为 `null`。

reportImpression（报告展示次数）

在 API 级别 34 中添加
也在广告服务扩展 4 中添加

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

通知服务有一次新的展示要报告给由 adSelectionId 标识的广告选择运行所选择的广告。无法保证何时报告相应展示。展示次数报告可能会延迟，并且报告可以批量处理。

为了计算胜出的卖方报告网址，该服务会从位于 ReportImpressionRequest.getAdSelectionConfig() 的 AdSelectionConfig#getDecisionLogicUri() 中提取卖方的 JavaScript 逻辑。然后，服务会执行卖方 JS 中名为 reportResult 的其中一个函数，提供设备端信号和 ReportImpressionRequest#getAdSelectionConfig() 作为输入参数。

reportResult 的函数定义如下：

function reportResult(ad_selection_config, render_url, bid, contextual_signals) { return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url } }; }

为了计算胜出的买方报告网址，服务会提取通过买方的 CustomAudience.getBiddingLogicUri() 提取的胜出买方的 JavaScript 逻辑。然后，服务会执行在买方 JS 中找到的其中一个函数（名为 reportWin），提供设备端信号、由 reportResult 计算的 signals_for_buyer 以及 ReportImpressionRequest#getAdSelectionConfig() 中的特定字段作为输入参数。

reportWin 的函数定义如下：

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 } }; }

此外，买方和卖方都可以选择注册以接收有关特定广告事件的报告。为此，它们可以分别在 reportWin 和 reportResult 内为买方和卖方调用平台提供的 registerAdBeacon 函数。

registerBeacon 的函数定义如下：

function registerAdBeacon(beacons)，其中 beacons 是字符串到字符串对的字典

对于买方/卖方关注的每个广告事件报告，他们会向 beacons 字典添加一个“event_key: event_reporting_uri”对，其中 event_key 是该特定事件的标识符。当 SDK 调用 reportEvent(ReportEventRequest, Executor, OutcomeReceiver) 时，此 event_key 应与 ReportEventRequest#getKey() 匹配。此外，每个 event_reporting_uri 都应正确解析为 Uri。这将是 SDK 调用 reportEvent(ReportEventRequest, Executor, OutcomeReceiver) 时向其报告的 Uri。

当买方/卖方添加完他们想要接收事件的所有键值对后，他们可以调用 registerAdBeacon(beacons)，其中 beacons 是他们将键值对添加到的字典的名称。

在以下情况下，registerAdBeacon 会抛出 TypeError：

多次调用 registerAdBeacon。如果在 reportWin/reportResult 中发现此错误，将注册原始配对集。
registerAdBeacon 不是正好有 1 个字典参数。
1 个字典参数的内容并非全部 String: String 对。

输出由 receiver 传递，它会返回一个空的 Object 表示运行成功，或者 Exception 包含抛出的异常的类型和相应的错误消息。

如果抛出 IllegalArgumentException，则是因为 API 收到的用于报告展示次数的输入参数无效所致。

如果抛出 IllegalStateException 并给出错误消息“Failure of AdSelection services.”，则是因为广告选择服务内部故障导致的。

如果抛出 LimitExceededException，则是在发起调用的软件包超出允许的速率限制并受到限制时引发的。

如果抛出 SecurityException，则是因为调用方未获授权或未请求权限而抛出。

系统会尽可能报告最多一次展示。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`request`	`ReportImpressionRequest`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。
`receiver`	`OutcomeReceiver`：此值不能为 `null`。

选择广告

在 Android UpsideDownCakePrivacySandbox 中添加的功能

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

从之前投放的广告选择的结果中选择广告。

输入 adSelectionFromOutcomesConfig 由广告 SDK 提供，AdSelectionFromOutcomesConfig 对象通过 Binder 调用进行传输。因此，这些对象的总大小受 Android IPC 限制。如果未能传输 AdSelectionFromOutcomesConfig，系统将抛出 TransactionTooLargeException。

输出由接收器传递，接收器会返回 AdSelectionOutcome 表示运行成功，或者 Exception 包含抛出的异常的类型和相应的错误消息。

输入 adSelectionFromOutcomesConfig 包含：

“Seller”必须是已注册的 AdTechIdentifier。否则，系统会抛出 IllegalStateException。
List of ad selection ids 应存在，并且来自同一应用的 selectAds(AdSelectionConfig, Executor, OutcomeReceiver) 调用。否则，用于输入验证的 IllegalArgumentException 会引发违规的广告选择 ID。
Selection logic URI（可以遵循 HTTPS 或广告选择预构建架构）。
如果 URI 遵循 HTTPS 架构，则主机应与 seller 匹配。否则，系统会抛出 IllegalArgumentException。
预构建 URI 是一种将所需 JavaScript 替换成 selectOutcome 所需的常规预构建逻辑的方法。此端点的预构建 URI 应遵循：
- ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>
如果传递了不受支持的预构建 URI 或该服务停用了预构建 URI 功能，系统会抛出 IllegalArgumentException。
如需了解支持的 <name> 和必需的 <script-generation-parameters>，请参阅 AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri。

如果抛出 IllegalArgumentException，则是由 API 为运行广告选择而收到的输入参数无效所致。

如果抛出 IllegalStateException 并给出错误消息“Failure of AdSelection services.”，则是因为广告选择服务内部故障导致的。

如果抛出 TimeoutException，则是因为在出价、评分或整体选择过程中遇到超时以找到胜出的广告。

如果抛出 LimitExceededException，则是在发起调用的软件包超出允许的速率限制并受到限制时引发的。

如果抛出 SecurityException，则是因为调用方未获授权或未请求权限而抛出。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`adSelectionFromOutcomesConfig`	`AdSelectionFromOutcomesConfig`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。回调和监听器事件通过此 `Executor` 进行分派，从而提供了一种简单的方法来控制使用哪个线程。如需通过应用的主线程分派事件，您可以使用 `Context.getMainExecutor()`。否则，请提供可分派给适当线程的 `Executor`。
`receiver`	`OutcomeReceiver`：此值不能为 `null`。

选择广告

在 API 级别 34 中引入

public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

在设备上运行广告选择流程，为调用方应用选择再营销广告。

输入 adSelectionConfig 由广告 SDK 提供，AdSelectionConfig 对象通过 Binder 调用进行传输。因此，这些对象的总大小受 Android IPC 限制。如果未能传输 AdSelectionConfig，系统将抛出 TransactionTooLargeException。

输入 adSelectionConfig 包含可遵循 HTTPS 或广告选择预构建架构的 Decision Logic Uri。

如果 URI 遵循 HTTPS 架构，则主机应与 seller 匹配。否则，系统会抛出 IllegalArgumentException。

预构建 URI 是一种将所需 JavaScript 替换成 scoreAds 所需的常规预构建逻辑的方法。此端点的预构建 URI 应遵循：

ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

如果传递了不受支持的预构建 URI 或该服务停用了预构建 URI 功能，系统会抛出 IllegalArgumentException。

如需了解受支持的 <name> 和必需的 <script-generation-parameters>，请参阅 AdSelectionConfig.Builder#setDecisionLogicUri。

输出由接收器传递，接收器会返回 AdSelectionOutcome 表示运行成功，或者 Exception 包含抛出的异常的类型和相应的错误消息。

如果抛出 IllegalArgumentException，则是由 API 为运行广告选择而收到的输入参数无效所致。

如果抛出 IllegalStateException 并给出错误消息“Failure of AdSelection services.”，则是因为广告选择服务内部故障导致的。

如果抛出 TimeoutException，则是因为在出价、评分或整体选择过程中遇到超时以找到胜出的广告。

如果抛出 LimitExceededException，则是在发起调用的软件包超出允许的速率限制并受到限制时引发的。

如果抛出 SecurityException，则是因为调用方未获授权或未请求权限而抛出。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`adSelectionConfig`	`AdSelectionConfig`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。回调和监听器事件通过此 `Executor` 进行分派，从而提供了一种简单的方法来控制使用哪个线程。如需通过应用的主线程分派事件，您可以使用 `Context.getMainExecutor()`。否则，请提供可分派给适当线程的 `Executor`。
`receiver`	`OutcomeReceiver`：此值不能为 `null`。

更新广告计数器直方图

在 Android UpsideDownCakePrivacySandbox 中添加的功能

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

更新之前通过调用 selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) 选择的广告的计数器直方图。

在广告选择过程中，计数器直方图用于为候选广告提供频次上限过滤方面的信息，其中，在广告选择过程中，系统会从出价流程中移除达到或超出频次上限的广告。

对于由给定 adSelectionId 指定的广告，只能为由同一调用方应用中最近调用 FLEDGE 广告选择所返回的广告更新计数器直方图。

在以下情况下，系统会通过 outcomeReceiver 返回 SecurityException：

应用未在其清单中声明正确的权限，或
由 callerAdTechIdentifier 标识的应用或实体无权使用该 API。

如果调用不是来自具有前台 activity 的应用，系统会通过 outcomeReceiver 返回 IllegalStateException。

如果调用超出了发起调用的应用的 API 节流，系统会通过 outcomeReceiver 返回 LimitExceededException。

在所有其他失败的情况下，outcomeReceiver 将返回空的 Object。请注意，为了保护用户隐私，内部错误不会通过异常发回。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
`updateAdCounterHistogramRequest`	`UpdateAdCounterHistogramRequest`：此值不能为 `null`。
`executor`	`Executor`：此值不能为 `null`。回调和监听器事件通过此 `Executor` 进行分派，从而提供了一种简单的方法来控制使用哪个线程。如需通过应用的主线程分派事件，您可以使用 `Context.getMainExecutor()`。否则，请提供可分派给适当线程的 `Executor`。
`outcomeReceiver`	`OutcomeReceiver`：此值不能为 `null`。