AdSelectionManager

public class AdSelectionManager
extends Object

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

AdSelection Manager 提供 API，供应用和广告 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) 选择的广告的计数器直方图。

继承的方法

公开方法

get

public static AdSelectionManager get (Context context)

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

参数
context Context: 要使用的 Context。此值不能为 null。
返回
AdSelectionManager AdSelectionManager 实例。此值不能为 null。

getAdSelectionData

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

从设备收集自定义受众数据。返回一个压缩和加密的 Blob，用于发送到竞价服务器进行广告选择。有关更多详细信息，请参阅竞价和竞拍服务说明。

自定义受众广告必须具有 ad_render_id 才能符合收集条件。

有关如何使用此 API 生成的 Blob 在服务器端处理广告选择运行结果的更多信息，请参见 AdSelectionManager#persistAdSelectionResult。

输出通过接收器传递，接收器在成功运行时返回一个 GetAdSelectionDataOutcome，或者在失败时返回一个 Exception，其中包含抛出的异常类型和相应的错误消息。

如果抛出 IllegalArgumentException，则表明 API 收到的输入参数无效，导致广告选择无法运行。

如果抛出带有错误消息 "Failure of AdSelection services." 的 IllegalStateException，则表明广告选择服务内部出现故障。

如果抛出 TimeoutException，则表明在竞价、评分或整个选择过程中查找获胜广告时发生超时。

如果抛出 LimitExceededException，则表明调用软件包超出允许的速率限制并被限流。

如果抛出 SecurityException，则表明调用方未获得授权或未请求权限。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
request GetAdSelectionDataRequest: 此值不能为 null。
executor Executor: 此值不能为 null。回调和监听器事件通过此 Executor 分派，提供一种轻松控制使用哪个线程的方法。要通过应用的主线程分派事件，可以使用 Context.getMainExecutor()。否则，提供一个分派到适当线程的 Executor。
receiver OutcomeReceiver: 此值不能为 null。

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

返回
TestAdSelectionManager 此值不能为 null。

persistAdSelectionResult

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

持久化服务器端的广告选择结果。有关更多详细信息，请参阅竞价和竞拍服务说明

有关如何生成加密的 Blob 以在服务器端运行广告选择的更多信息，请参见 AdSelectionManager#getAdSelectionData。

输出通过接收器传递，接收器在成功运行时返回一个 AdSelectionOutcome，或者在失败时返回一个 Exception，其中包含抛出的异常类型和相应的错误消息。

如果抛出 IllegalArgumentException，则表明 API 收到的输入参数无效，导致广告选择无法运行。

如果抛出带有错误消息 "Failure of AdSelection services." 的 IllegalStateException，则表明广告选择服务内部出现故障。

如果抛出 TimeoutException，则表明在竞价、评分或整个选择过程中查找获胜广告时发生超时。

如果抛出 LimitExceededException，则表明调用软件包超出允许的速率限制并被限流。

如果抛出 SecurityException，则表明调用方未获得授权或未请求权限。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
request PersistAdSelectionResultRequest: 此值不能为 null。
executor Executor: 此值不能为 null。回调和监听器事件通过此 Executor 分派，提供一种轻松控制使用哪个线程的方法。要通过应用的主线程分派事件，可以使用 Context.getMainExecutor()。否则，提供一个分派到适当线程的 Executor。
receiver OutcomeReceiver: 此值不能为 null。

reportEvent

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 收到的输入参数无效，导致广告事件无法报告。

如果抛出带有错误消息 "Failure of AdSelection services." 的 IllegalStateException，则表明广告选择服务内部出现故障。

如果抛出 LimitExceededException，则表明调用软件包超出允许的速率限制并被限流。

如果抛出 SecurityException，则表明调用方未获得授权或未请求权限。

事件将尽力而为地报告最多一次。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

reportImpression

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

通知服务，与由 adSelectionId 标识的广告选择运行所选中的广告相关联的新展示需要报告。不保证展示何时报告。展示报告可能会延迟，且报告可能会批量处理。

为了计算获胜卖家的报告 URL，服务会从 AdSelectionConfig#getDecisionLogicUri() 获取卖家的 JavaScript 逻辑，该逻辑位于 ReportImpressionRequest.getAdSelectionConfig() 中。然后，服务会执行卖家 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 } }; }

为了计算获胜买家的报告 URL，服务会获取获胜买家的 JavaScript 逻辑，该逻辑通过买家的 CustomAudience.getBiddingLogicUri() 获取。然后，服务会执行买家 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：

  1. 多次调用 registerAdBeacon。如果在 reportWin/reportResult 中捕获此错误，则将注册原始的配对集合。
  2. registerAdBeacon 没有精确的 1 个字典参数。
  3. 1 个字典参数的内容并非全部是 String: String 配对。

输出通过 receiver 传递，接收器在成功运行时返回一个空的 Object，或者在失败时返回一个 Exception，其中包含抛出的异常类型和相应的错误消息。

如果抛出 IllegalArgumentException，则表明 API 收到的输入参数无效，导致展示无法报告。

如果抛出带有错误消息 "Failure of AdSelection services." 的 IllegalStateException，则表明广告选择服务内部出现故障。

如果抛出 LimitExceededException，则表明调用软件包超出允许的速率限制并被限流。

如果抛出 SecurityException，则表明调用方未获得授权或未请求权限。

展示将尽力而为地报告最多一次。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

selectAds

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

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

输入 adSelectionFromOutcomesConfig 由广告 SDK 提供，并且 AdSelectionFromOutcomesConfig 对象通过 Binder 调用传输。因此，这些对象的总大小受到 Android IPC 限制的约束。传输 AdSelectionFromOutcomesConfig 失败将抛出 TransactionTooLargeException。

输出通过接收器传递，接收器在成功运行时返回一个 AdSelectionOutcome，或者在失败时返回一个 Exception，其中包含抛出的异常类型和相应的错误消息。

输入 adSelectionFromOutcomesConfig 包含：

如果抛出 IllegalArgumentException，则表明 API 收到的输入参数无效，导致广告选择无法运行。

如果抛出带有错误消息 "Failure of AdSelection services." 的 IllegalStateException，则表明广告选择服务内部出现故障。

如果抛出 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 由广告 SDK 提供，并且 AdSelectionConfig 对象通过 Binder 调用传输。因此，这些对象的总大小受到 Android IPC 限制的约束。传输 AdSelectionConfig 失败将抛出 TransactionTooLargeException。

输入 adSelectionConfig 包含 Decision Logic Uri，可以遵循 HTTPS 或 Ad Selection Prebuilt 架构。

如果 URI 遵循 HTTPS 架构，则主机必须与 seller 匹配。否则，将抛出 IllegalArgumentException。

Prebuilt URI 是一种替代 scoreAds 所需的 JavaScript 的通用预构建逻辑的方法。此端点的 Prebuilt URI 应遵循以下格式：

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

如果传递了不支持的 Prebuilt URI 或服务禁用了 Prebuilt URI 功能，则将抛出 IllegalArgumentException。

有关支持的 <name> 和所需的 <script-generation-parameters>，请参阅 AdSelectionConfig.Builder#setDecisionLogicUri。

输出通过接收器传递，接收器在成功运行时返回一个 AdSelectionOutcome，或者在失败时返回一个 Exception，其中包含抛出的异常类型和相应的错误消息。

如果抛出 IllegalArgumentException，则表明 API 收到的输入参数无效，导致广告选择无法运行。

如果抛出带有错误消息 "Failure of AdSelection services." 的 IllegalStateException，则表明广告选择服务内部出现故障。

如果抛出 TimeoutException，则表明在竞价、评分或整个选择过程中查找获胜广告时发生超时。

如果抛出 LimitExceededException，则表明调用软件包超出允许的速率限制并被限流。

如果抛出 SecurityException，则表明调用方未获得授权或未请求权限。
需要 AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

参数
adSelectionConfig AdSelectionConfig: 此值不能为 null。
executor Executor: 此值不能为 null。回调和监听器事件通过此 Executor 分派，提供一种轻松控制使用哪个线程的方法。要通过应用的主线程分派事件，可以使用 Context.getMainExecutor()。否则，提供一个分派到适当线程的 Executor。
receiver OutcomeReceiver: 此值不能为 null。

updateAdCounterHistogram

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。
如果调用不是来自具有前台 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。