已在 API 级别 34 中引入
也已在广告服务扩展 4 中引入

摘要： 方法 | 继承的方法

AdSelectionManager

public class AdSelectionManager
extends Object

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

---

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

摘要

公共方法
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 才能被收集。

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

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

如果抛出 IllegalArgumentException，则是由无效的输入参数引起的 收到的 API 来运行广告选择

如果抛出 IllegalStateException 并显示错误消息“Failure of AdSelection” 则是由于广告选择服务发生内部故障而导致的。

如果抛出 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。

持久化广告选择结果

在 Android UpsideDownCakePrivacySandbox 中引入

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

保留服务器端的广告选择结果。有关详情，请访问出价解决方案页面 和竞价服务解说

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

输出由接收器传递，接收器会返回 AdSelectionOutcome 或者 Exception 包含抛出的异常的类型以及 相应的错误消息。

如果抛出 IllegalArgumentException，则是由无效的输入参数引起的 收到的 API 来运行广告选择

如果抛出 IllegalStateException 并显示错误消息“Failure of AdSelection” 则是由于广告选择服务发生内部故障而导致的。

如果抛出 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()，该服务将提取 reportingUri 是在registerAdBeacon中注册的。如需详细了解 registerAdBeacon，请参阅 reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) 的文档。然后，该服务 会将 ReportEventRequest#getData() 附加到 POST 请求的请求正文中， 发送请求。POST 请求的正文将具有 text/plain 的 content-type，并且数据将在 charset=UTF-8 中传输。

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

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

如果抛出 IllegalStateException 并显示错误消息“Failure of AdSelection” 则是由于广告选择服务发生内部故障而导致的。

如果抛出了 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 标识的广告选择运行。我们无法保证 展示次数。展示次数报告可能会延迟， 批量创建。

为了计算胜出的卖方报告网址，服务会提取卖方的 JavaScript 来自于 ReportImpressionRequest.getAdSelectionConfig() 处的 AdSelectionConfig#getDecisionLogicUri() 的逻辑。然后，该服务会执行 函数中名为 reportResult 的 Seller JS，提供设备端信号作为 以及使用 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 的函数，并提供 设备端信号、signals_for_buyer（按 reportResult 计算得出）以及具体 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 } }; }

此外，买方和卖方可以选择进行注册，以接收有关特定 广告事件。为此，他们可以调用平台提供的 registerAdBeacon 函数 reportWin 和 reportResult 内（分别对应买方和卖方）。

registerBeacon 的函数定义如下：

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

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

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

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

1. 多次调用 registerAdBeacon。如果 reportWin/reportResult，将注册原始的配对集
2. registerAdBeacon 不恰好有 1 个字典参数。
3. 1 个 dict 参数的内容并非全部 String: String 对。

输出由 receiver 传递，后者会返回空的 Object 或者 Exception 包含抛出的异常的类型和 相应的错误消息。

如果抛出 IllegalArgumentException，则是由无效的输入参数引起的 来报告展示次数

如果抛出 IllegalStateException 并显示错误消息“Failure of AdSelection” 则是由于广告选择服务发生内部故障而导致的。

如果抛出了 LimitExceededException，则会在发起调用的软件包时引发此错误 超出了允许的速率限制，因此已被限制。

如果抛出 SecurityException，则是在调用方未获得授权时导致的 或权限。

我们会尽力而为，最多只会报告一次展示。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

selectAds

在 Android UpsideDownCakePrivacySandbox 中引入

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

从之前运行的广告选择的结果中选择广告。

输入 adSelectionFromOutcomesConfig 由 Ads 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 是一种用通用的预构建逻辑替换所需的 selectOutcome 的 JavaScript。此端点的预构建 URI 应紧随其后：

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

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

  请访问 AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri 了解支持情况 <name>，且必须提供 <script-generation-parameters>。

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

如果抛出 IllegalStateException 并显示错误消息“Failure of AdSelection” 则是由于广告选择服务发生内部故障而导致的。

如果抛出 TimeoutException，则会在遇到超时时触发 在出价、评分或整个选择流程中发现胜出的广告。

如果抛出了 LimitExceededException，则会在发起调用的软件包时引发此错误 超出了允许的速率限制，因此已被限制。

如果抛出了 SecurityException，则是在调用方未获得授权时导致的 或权限。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
adSelectionFromOutcomesConfig	AdSelectionFromOutcomesConfig：此值不能为 null。
executor	Executor：此值不能为 null。 回调和监听器事件通过此 Executor，可让您轻松控制要 。要通过 可以使用 Context.getMainExecutor()。 否则，请提供分派给相应线程的 Executor。
receiver	OutcomeReceiver：此值不能为 null。

selectAds

在 API 级别 34 中引入

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

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

输入 adSelectionConfig 由 Ads SDK 提供，AdSelectionConfig 对象通过 Binder 调用进行传输。因此，总的 受 Android IPC 限制的约束。如果未能传输 AdSelectionConfig，系统会抛出 TransactionTooLargeException。

输入 adSelectionConfig 包含 Decision Logic Uri， HTTPS 或广告选择预构建架构

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

预构建的 URI 是一种用通用的预构建逻辑替换所需的 scoreAds 的 JavaScript。此端点的预构建 URI 应紧随其后：

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

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

请参阅AdSelectionConfig.Builder#setDecisionLogicUri支持的<name>和 必须提供<script-generation-parameters>。

输出由接收器传递，接收器会返回 AdSelectionOutcome 或者 Exception 包含抛出的异常的类型以及 相应的错误消息。

如果抛出 IllegalArgumentException，则是由无效的输入参数引起的 收到的 API 来运行广告选择

如果抛出 IllegalStateException 并显示错误消息“Failure of AdSelection” 则是由于广告选择服务发生内部故障而导致的。

如果抛出 TimeoutException，则会在遇到超时时触发 在出价、评分或整个选择流程中发现胜出的广告。

如果抛出了 LimitExceededException，则会在发起调用的软件包时引发此错误 超出了允许的速率限制，因此已被限制。

如果抛出 SecurityException，则是在调用方未获得授权时导致的 或权限。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
adSelectionConfig	AdSelectionConfig：此值不能为 null。
executor	Executor：此值不能为 null。 回调和监听器事件通过此 Executor，可让您轻松控制要 。要通过 可以使用 Context.getMainExecutor()。 否则，请提供分派给相应线程的 Executor。
receiver	OutcomeReceiver：此值不能为 null。

updateAdCounterHistogram

在 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) 选择的广告的计数器直方图。

广告选择过程中会使用计数器直方图 候选广告，其中达到或超过频次上限的广告将从 广告选择流程中的出价流程。

仅当最近从同一调用方应用中调用 FLEDGE 广告选择后，给定 adSelectionId 所返回的广告指定的广告计数器直方图才会更新。

如果出现以下情况，系统会通过 outcomeReceiver 返回 SecurityException：

1. 应用未在清单中声明正确的权限；或者
2. callerAdTechIdentifier标识的应用或实体未获授权 使用 API。

。 如果调用执行了此调用，系统会通过 outcomeReceiver 返回 IllegalStateException 并非来自具有前台 activity 的应用。

如果调用LimitExceededExceptionoutcomeReceiver 超出了发起调用的应用的 API 限制。

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

参数
updateAdCounterHistogramRequest	UpdateAdCounterHistogramRequest：此值不能为 null。
executor	Executor：此值不能为 null。 回调和监听器事件通过此 Executor，可让您轻松控制要 。要通过 可以使用 Context.getMainExecutor()。 否则，请提供分派给相应线程的 Executor。
outcomeReceiver	OutcomeReceiver：此值不能为 null。