使用 Protected Audience API 支持自定义受众群体定位

提供反馈

近期更新

Protected Audience 目前处于 Beta 版阶段，可供在公开设备上测试！

借助 Protected Audience，您可以：

  • 根据之前的用户操作，管理自定义受众群体。
  • 通过单卖家或广告瀑布流中介支持，在设备端启动竞价。
  • 在广告选择完成后，进行展示次数报告。

如需开始操作，请阅读 Protected Audience 开发者指南。感谢您在我们不断开发 Protected Audience 的过程中向我们提供反馈。

时间轴

我们将在未来几个月内发布新功能。具体发布日期因功能而异，一旦有可用的文档链接，此表便会进行更新。

功能 推出开发者预览版 推出 Beta 版
事件级报告 2023 年第 1 季度 2023 年第 3 季度
广告瀑布流中介 2023 年第 1 季度 2023 年第 4 季度
应用安装广告过滤 2023 年第 2 季度 2023 年第 3 季度
频次上限过滤 2023 年第 2 季度 2023 年第 3 季度
将内容相关广告传递到广告选择工作流程以进行过滤 2023 年第 2 季度 2023 年第 3 季度
互动报告 2023 年第 2 季度 2023 年第 3 季度
加入自定义受众群体委托 2023 年第 3 季度 2023 年第 4 季度
非 CPM 结算 2023 年第 3 季度 2023 年第 4 季度
出价和竞价服务集成 2023 年第 3 季度 2023 年第 4 季度
调试报告 2023 年第 3 季度 2023 年第 4 季度
Attribution Reporting 集成 不适用 2023 年第 4 季度
公开出价中介 2023 年第 4 季度 2023 年第 4 季度
货币管理 2024 年第 1 季度 2024 年第 2 季度
K 匿名性集成 不适用 2024 年第 2 季度
汇总报告集成 2024 年第 3 季度 2024 年第 4 季度

概览

在移动广告中，广告主通常需要根据用户之前与广告主的应用进行互动的方式，向可能感兴趣的用户投放广告。例如，SportingGoodsApp 的开发者可能想要向购物车内留有商品的用户投放广告（通过展示广告来提醒用户完成购买）。业界通常使用“再营销”和“自定义受众群体定位”等术语来描述这种笼统的概念。

目前，这些用例的典型实现方式是与广告技术平台共享广告展示方式的相关上下文信息（例如应用名称），以及受众群体名单等私密信息。利用这些信息，广告主可以在其服务器上选择具有相关性的广告。

Protected Audience API on Android（以前称为 FLEDGE）包含面向广告技术平台和广告主的以下 API，可支持常见的基于互动的用例，以限制跨应用共享这两种标识符的方式以及用户与第三方之间的应用互动信息：

  1. Custom Audience API：此 API 以“自定义受众群体”的抽象概念为核心，该抽象概念表示广告主指定的具有共同意图的受众群体。受众群体信息存储在设备上，可与受众群体的相关候选广告和任意元数据（例如出价信号）相关联。这些信息可用于为广告主出价、过滤广告和呈现提供依据。
  2. Ad Selection API：此 API 提供了一个框架，用于编排广告技术平台的工作流程，以根据设备端信号确定“胜出”的广告（方法是考虑本地存储的候选广告，并对广告技术平台向设备返回的候选广告执行额外的处理）。
展示 Privacy Sandbox on Android 中的自定义受众群体管理和广告选择工作流程的流程图。
。

大体上讲，相关集成的运作方式如下：

  1. 如果用户的购物车内留有商品且未在 2 天内完成购买，SportingGoodsApp 想要提醒用户购买这些商品。SportingGoodsApp 使用 Custom Audience API 将用户添加到“购物车中有商品”受众群体名单中。平台管理此受众群体名单并将其存储在设备上，以限制与第三方共享相关信息的行为。SportingGoodsApp 与广告技术平台合作，以向其受众群体名单中的用户展示广告。广告技术平台管理受众群体名单的元数据并提供候选广告，从而将候选广告提供给广告选择工作流程以备考虑。平台可配置为在后台定期获取经过更新的基于受众群体的广告。这有助于确保基于受众群体的候选广告列表保持最新状态，并且与在广告机会期间向第三方广告服务器发送的请求（即内容相关广告请求）无关。

  2. 当用户在同一设备上玩 FrisbeeGame 时，他们可能会看到一个广告，提醒他们购买留在 SportingGoodsApp 购物车中的商品。这可通过以下方式实现：FrisbeeGame（具有集成的广告 SDK）调用 Ad Selection API，以根据包含相应用户的任何受众群体名单（在此示例中，则为 SportingGoodsApp 创建的“购物车中有商品”自定义受众群体）为其选择胜出的广告。广告选择工作流程可设置为考虑从广告技术平台的服务器检索到的广告，而不仅仅是考虑与自定义受众群体和其他设备端信号相关联的设备端广告。广告技术平台和广告 SDK 还可借助自定义出价和评分逻辑自定义此工作流程，以实现相应的广告目标。通过此方法，即可使用用户的兴趣或应用互动数据作为广告选择的依据，同时限制与第三方共享这些数据的行为。

  3. 广告投放应用或广告技术平台的 SDK 会呈现所选广告。

  4. 平台有助于生成展示次数和广告选择结果报告。此报告功能是对 Attribution Reporting API 的补充。广告技术平台可根据其报告需求进行自定义。

获取 Protected Audience on Android API 访问权限

广告技术平台需要注册才能访问 Protected Audience API。如需了解详情，请参阅注册 Privacy Sandbox 账号。

自定义受众群体管理

自定义受众群体

自定义受众群体表示由广告主确定的一组具有共同意图或兴趣的用户。应用或 SDK 可使用自定义受众群体来表示特定受众群体，例如“购物车中留有商品”的用户，或在某个游戏中“打通新手关卡”的玩家。平台会在设备本地维护和存储受众群体信息，并且不会公开用户所属的自定义受众群体。自定义受众群体不同于 Chrome 的 Protected Audience 兴趣群体，且无法在网站和应用之间共享。这有助于限制共享用户信息的行为。

广告主应用或集成的 SDK 可根据条件加入或退出自定义受众群体，例如根据用户在应用中的互动情况。

自定义受众群体元数据

每个自定义受众群体都包含以下元数据：

  • 所有者：所有者应用的软件包名称。该变量会隐式设置为调用方应用的软件包名称。
  • 买方：管理面向此自定义受众群体的广告的买方广告网络。买方还代表可访问自定义受众群体并获取相关广告信息的各方。可以按照 eTLD+1 格式指定买方。
  • 名称：自定义受众群体的任意名称或标识符，例如可以将用户标识为“购物车放弃者”。 例如，此属性可在广告主的广告系列中用作定位条件之一，或在网址中用作查询字符串以提取出价代码。
  • 激活时间和到期时间：这些字段定义了此自定义受众群体生效的时间期限。平台会使用这些信息来撤销自定义受众群体的成员资格。到期时间不能超过时长期限上限，以限制自定义受众群体的生命周期。
  • 每日更新网址：平台用于提取“用户出价信号”和“可信出价信号”字段中定义的候选广告和其他元数据的网址。如需了解详情，请参阅有关如何为自定义受众群体提取候选广告的部分。
  • 用户出价信号：广告技术平台专有信号，用于对再营销广告进行出价。此类信号的示例包括：用户的粗略位置信息、首选语言区域等。
  • 可信出价数据：广告技术平台依赖实时数据为广告检索和评分提供依据。例如，广告可能会用尽预算，并且需要立即停止投放。广告技术平台可定义一个网址端点（可从此位置提取相关实时数据），以及需要执行实时查询的一组键。处理此请求的服务器将是由广告技术平台管理的可信服务器。
  • 出价逻辑网址：平台用于从需求方平台提取出价代码的网址。平台会在广告竞价发起后执行此步骤。
  • 广告：针对自定义受众群体的候选广告列表。其中包含广告技术平台专有的广告元数据和用于呈现广告的网址。针对自定义受众群体发起竞价后，系统会考虑此广告元数据列表。在可行的情况下，系统会使用每日更新网址端点刷新此广告列表。由于移动设备的资源有限，因此自定义受众群体中可存储的广告有数量限制。

自定义受众群体委托

传统的自定义受众群体定义和配置通常依赖于广告技术技术与服务器端以及广告主客户和合作伙伴驱动的服务器端技术和集成。Protected Audience API 支持自定义受众群体定义和配置，同时保护用户隐私。若要加入自定义受众群体，应用中不存在 SDK 的买方广告技术平台需要与设备端存在 SDK 的广告技术平台合作，例如移动衡量合作伙伴 (MMP) 需与供应方平台 (SSP) 携手合作。Protected Audience API 旨在通过让设备端调用方能够代表买方调用自定义受众群体创建流程，从而提供适用于管理自定义受众群体的灵活解决方案，支持这类 SDK。此过程称为“自定义受众群体委托”。请按照以下步骤配置自定义受众群体委托：

加入自定义受众群体

可以通过以下两种方式加入自定义受众群体：

joinCustomAudience()

应用可以先使用预期参数实例化 CustomAudience 对象，然后调用 joinCustomAudience() 来请求加入自定义受众群体。说明代码段示例如下：

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

应用或 SDK 可以代表设备端不存在应用或 SDK 的广告技术平台请求加入自定义受众群体，方法是使用预期参数调用 fetchAndJoinCustomAudience()，如以下示例所示：

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

买方拥有的网址端点会在响应正文中返回 CustomAudience JSON 对象作为响应。自定义受众群体的买方和所有者字段将被忽略（并由 API 自动填充）。该 API 还会强制让每日更新网址也与买方的 eTLD+1 一致。

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

fetchAndJoinCustomAudience() API 根据 fetchUri 的 eTLD+1 确定买方的身份。CustomAudience 买方的身份信息用于执行与 joinCustomAudience() 执行的注册和应用授权检查相同的操作，并且不能通过提取响应而更改。CustomAudience 所有者是调用方应用的软件包名称。除了 eTLD+1 检查之外，对 fetchUri 没有其他验证，特别是没有 k-匿名性检查。fetchAndJoinCustomAudience() API 会向 fetchUri 发出 HTTP GET 请求，并预期获取表示自定义受众群体的 JSON 对象。自定义受众群体对象字段的相同强制性可选约束条件和默认值将应用于该响应。如需了解当前要求和限制，请参阅我们的开发者指南。

买方发送的任何 HTTP 错误响应都会导致 fetchAndJoinCustomAudience 失败。尤其是 HTTP 状态响应码 429（请求过多）会在定义的时间段内屏蔽来自当前应用的请求。如果来自买方的响应格式错误，API 调用也会失败。失败情况会报告给负责在出现临时失败（例如服务器未响应）时重试的 API 调用方，或报告以便处理持续失败（例如数据验证失败或任何在与服务器通信期间出现的其他非临时错误）。

CustomAudienceFetchRequest 对象允许 API 调用方使用上述示例中显示的可选属性为自定义受众群体定义一些信息。如果在请求中设置了这些值，则这些值不能被平台收到的买方响应覆盖；Protected Audience API 会忽略响应中的字段。如果未在请求中设置这些字段，则必须在响应中设置这些字段，因为创建自定义受众群体时需要用到这些字段。由 API 调用方部分定义的 CustomAudience 内容的 JSON 表示法包含在特殊头文件 X-CUSTOM-AUDIENCE-DATA 中对 fetchUri 的 GET 请求内。为自定义受众群体指定的、序列化形式的数据大小上限为 8 KB。如果超出大小上限，fetchAndJoinCustomAudience API 调用会失败。

由于缺少 k-匿名性检查，您可使用 fetchUri 进行买方验证，还可支持在买方和 SDK 之间共享信息。为方便自定义受众群体验证，买方可以提供验证令牌。设备端 SDK 应在 fetchUri 中包含此令牌，以便买方托管的端点可以提取自定义受众群体的内容并使用验证令牌来验证 fetchAndJoinCustomAudience() 操作对应于买方且来自可信的设备端合作伙伴。如需共享信息，买方可以同意设备端调用方将用于创建自定义受众群体的部分信息作为查询参数添加到 fetchUri 中。这样，买方就可以审核调用，并检测是否有恶意广告技术平台使用了验证令牌来创建多个不同的自定义受众群体。

关于验证令牌定义和存储的说明

  • 验证令牌不供 Protected Audience API 用于任何用途，且是可选的。

    • 买方可以使用验证令牌验证所创建的受众群体是否是以买方自己的名义所创建。
    • Protected Audience API 提案既不会指定验证令牌的格式，也不会指定买方如何将验证令牌传递给调用方。例如，验证令牌可以在所有者的 SDK 或后端中预加载，也可以由买方的 SDK 从买方的服务器中实时检索。

退出自定义受众群体

自定义受众群体的所有者可通过调用 leaveCustomAudience() 来选择退出相应受众群体，如以下说明代码段所示：

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

为帮助减少存储空间和其他设备资源的使用量，自定义受众群体会在预先确定的时间期限过后过期，并从设备端存储空间中移除。默认值有待确定。所有者可替换此默认值。

用户控制

  • 此方案旨在让用户能够以列表形式查看哪些已安装的应用创建了至少一个自定义受众群体。
  • 用户可从此列表中移除应用。此移除操作会移除与应用相关联的所有自定义受众群体，并阻止应用加入新的自定义受众群体。
  • 用户能够完全重置 Protected Audience API。在这种情况下，系统会清除设备上的所有现有自定义受众群体。
  • 用户还可选择完全停用 Privacy Sandbox on Android（包括 Protected Audience API）。如果用户选择停用 Privacy Sandbox，Protected Audience API 会静默失败。

此功能正处于设计阶段，细节信息将包含在后续更新中。

定时更新

之前介绍的解决方案要求应用或广告技术 SDK 调用 API 并提供 自定义受众群体。不过，有时 广告客户和广告技术提供商可以界定用户 在使用应用时获得实时信息

为此，广告技术平台可以调用 scheduleCustomAudienceUpdate() API。此 API 允许调用方指定 从而延长 API 调用时间， 让做出响应的广告技术平台处理应用级事件，并确定 用户应加入或移出的 Protected Audiences。

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

ScheduleCustomAudienceUpdateRequest包含 注册一个延迟作业以在平台中运行。待指定的延迟时间过后 系统会定期运行后台作业并发送请求。通过 ScheduleCustomAudienceUpdateRequest 可包含以下信息：

  • UpdateUri：将发送 GET 调用以提取更新的 URI 端点。买方身份本身是根据 eTLD+1 推断出来的，无需 且不能被更新响应更改。GET 请求预期返回一个 JSON 对象，其中包含 customAudience 对象列表。
  • DelayTime：表示从发出 scheduleCustomAudienceUpdate() API 调用到安排更新的时间延迟。
。

  • PartialCustomAudience：该 API 还允许设备端 SDK 发送列表 部分构建的自定义受众群体。这样，应用内 SDK 就能 在自定义受众群体管理方面具有双重角色（从完全控制到部分控制） 基于他们与需求方平台之间的合作伙伴关系

    • 这也使得此 API 与 fetchAndJoinCustomAudience() 兼容 用于实现类似信息的共享 API。

  • ShouldReplacePendingUpdates：用于确定是否有待处理 应取消定期更新，并替换为 当前的 ScheduleCustomAudienceUpdateRequest。如果设为 false 且 在 使用以下代码对 scheduleCustomAudienceUpdate 的调用 ScheduleCustomAudienceUpdateRequest 将失败。默认值为 false。

应用权限和控制

此提案旨在为应用提供控制其自定义受众群体的权限：

  • 应用可管理与自定义受众群体的关联。
  • 应用可向第三方广告技术平台授予代表其管理自定义受众群体的权限。

此功能正处于设计阶段，细节信息将包含在后续更新中。

广告技术平台控制

此提案概述了广告技术平台控制其自定义受众群体的方法：

  • 广告技术平台注册 Privacy Sandbox，并提供与自定义受众群体的所有网址匹配的 eTLD+1 域名。
  • 广告技术平台可与应用或 SDK 合作，提供用于验证自定义受众群体创建信息的验证令牌。当此过程委托给合作伙伴时，可以将自定义受众群体创建配置为需要广告技术平台确认。
  • 广告技术平台可以选择代表其自身停用 joinCustomAudience 调用，并仅允许 fetchAndJoinCustomAudience API 启用所有调用自定义受众群体。注册 Privacy Sandbox 期间可以更新控制设置。请注意，此控制允许所有广告技术平台，或全都不允许。由于平台限制，无法针对每个广告技术平台授予委托权限。

候选广告和元数据响应

从买方平台返回的候选广告和元数据应包含以下字段：

  • 元数据：买方广告技术专有广告元数据。例如，这可能包含广告系列的相关信息以及定位条件（例如位置和语言）。
  • 呈现网址：用于呈现广告素材的端点。
  • 过滤：Protected Audience API 根据设备上的数据过滤广告所需的可选信息。如需了解详情，请阅读买方过滤逻辑部分。

广告选择工作流程

此方案旨在引入 Ad Selection API，用于为广告技术平台编排竞价执行，从而更好地保护隐私。

如今，广告技术平台通常只在其服务器上执行出价和广告选择。在此方案中，自定义受众群体和其他敏感的用户信号（例如可用的已安装软件包信息）只可通过 Ad Selection API 获取。此外，对于再营销用例，候选广告将从带外进行提取（即在将要展示广告的上下文范围外进行提取）。广告技术平台将需要做好准备，以便在设备上部署和执行当前竞价和广告选择逻辑的部分流程。广告技术平台可以考虑对其广告选择工作流程进行以下更改：

  • 如果服务器上没有已安装的软件包信息，广告技术平台可能需要将多个内容相关广告发送回设备，并调用广告选择工作流程以启用基于应用安装的过滤功能，从而尽可能提高展示相关广告的机会。
  • 由于再营销广告是从带外提取的，因此可能需要更新当前的出价模型。广告技术平台可能需要创建出价子模型 （该实现可能基于一个名为 双塔模型） 可以单独处理广告功能和情境信号，并将 子模型在设备上输出结果以预测出价。无论是服务器端竞价还是针对任何给定广告机会的竞价，这种方式均可从中受益。

通过此方法，即可使用用户的应用互动数据作为广告选择的依据，同时限制与第三方共享这些数据的行为。

显示广告选择工作流程启动流程的流程图。

此广告选择工作流程会按以下顺序编排由广告技术平台提供的 JavaScript 代码在设备上的执行：

  1. 买方出价逻辑执行
  2. 买方广告过滤和处理
  3. 卖方决策逻辑执行

对于涉及自定义受众群体的广告选择，平台会根据自定义受众群体的“出价逻辑网址”元数据所定义的公共网址端点，提取买方提供的 JavaScript 代码。卖方决策代码的网址端点也将作为输入传递，用于启动广告选择工作流程。

不涉及自定义受众群体的广告选择正在积极设计中。

启动广告选择工作流程

当应用需要展示广告时，广告技术平台 SDK 可以先使用预期参数实例化 AdSelectionConfig 对象，然后调用 selectAds() 方法来启动广告选择工作流程：

  • 卖方：卖方广告平台的标识符，采用 eTLD+1 格式
  • 决策逻辑网址：发起广告竞价后，平台会使用此网址从卖方平台获取 JavaScript 代码，以便通过评分选出胜出的广告。
  • 自定义受众群体买方：对相应竞价具有基于自定义受众群体的需求的买方平台列表，采用 eTLD+1 格式。
  • 广告选择信号：竞价的相关信息（广告尺寸、广告格式等）。
  • 卖方信号：供应方平台专有信号。
  • 可信评分信号网址：卖方可信信号的网址端点，可从其中提取广告素材专有的实时信息。
  • 每个买方的信号：参与竞价的需求方可使用此参数为竞价提供输入。例如，此参数可能包含有助于确定出价的全面上下文信息。

以下说明代码段展示了广告技术平台 SDK 启动广告选择工作流程的过程（首先定义 AdSelectionConfig，然后调用 selectAds 以获取胜出的广告）：

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

买方出价逻辑

出价逻辑通常由买方平台提供。此代码旨在确定候选广告的出价。它可能会应用其他业务逻辑来确定结果。

平台会使用自定义受众群体的“出价逻辑网址”元数据来提取 JavaScript 代码，此代码应包含以下函数签名：

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

generateBid() 方法会返回计算得出的出价金额。平台将依序为所有广告（内容相关广告或再营销广告）调用此函数。如果有多个出价逻辑提供程序，系统无法保证这些提供程序之间的执行顺序。

此函数需要以下参数：

  • 广告：买方出价代码所考虑的广告。这是来自符合条件的自定义受众群体的广告
  • 竞价信号：卖方平台专有信号。
  • 每个买方的信号：参与竞价的需求方可使用此参数为竞价提供输入。例如，此参数可能包含有助于确定出价的全面上下文信息。
  • 可信出价信号：广告技术平台依赖实时数据为广告检索和评分提供依据。例如，广告系列可能会用尽预算，并且需要立即停止投放。广告技术平台可定义一个网址端点（可从此位置提取相关实时数据），以及需要执行实时查询的一组键。处理此请求的广告技术平台的托管服务器将是由广告技术平台管理的可信服务器。
  • 情境信号：这可能包含粗略的时间戳或大致位置信息，或广告的每次点击费用。
  • 用户信号：这可能包含可用的已安装软件包信息等信息。

广告费用

除了出价之外，买方平台还在 generateBid() 中包含了用于返还每次点击费用的选项。例如：

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

如果该广告是胜出者，为保护隐私，adCost 会随机舍入为 8 位。然后，在展示次数报告生成期间，系统会将 adCost 的舍入值传递给 reportWin 中的 contextual_signals 参数。

买方过滤逻辑

买方平台将能够根据广告选择阶段可用的其他设备端信号来过滤广告。例如，广告技术平台可在这里实现频次上限功能。如果有多个过滤提供程序，系统无法保证这些提供程序之间的执行顺序。

买方过滤逻辑可以作为出价逻辑的一部分来实现，方法是针对指定广告返回出价值 0。

除此之外，买方平台还将能够发出信号，指示应根据 Protected Audience 可用的额外设备端信号来过滤特定广告，并指示不应离开设备。我们将不断强化更多过滤逻辑的设计，与此同时，买方平台将遵循这一相同结构来发出关于过滤逻辑的信号。

卖方评分逻辑

评分逻辑通常由卖方平台提供。此代码旨在根据出价逻辑输出来确定胜出的广告。它可能会应用其他业务逻辑来确定结果。如果有多个决策逻辑提供程序，系统无法保证这些提供程序之间的执行顺序。平台会使用 selectAds() API 的“决策逻辑网址”输入参数来提取 JavaScript 代码，此代码应包含以下函数签名：

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

此函数需要以下参数：

  • 广告：接受评估的广告；generateBid() 函数的输出。
  • 出价：generateBid() 函数输出的出价金额。
  • 竞价配置：selectAds() 方法的输入参数。
  • 可信评分信号：广告技术平台依赖实时数据为广告过滤和评分提供依据。例如，应用发布商可阻止某个广告系列在应用中展示广告。系统会从竞价配置的可信评分信号网址参数中提取相应数据。处理此请求的服务器应该是由广告技术平台管理的可信服务器。
  • 上下文信号：这可能包含粗略的时间戳或大致位置信息。
  • 用户信号：这可能包含启动应用安装的应用商店等信息。
  • 自定义受众群体信号：如果要评分的广告来自设备端的自定义受众群体，这将包含自定义受众群体的读取方和名称等信息。

广告选择代码运行时

在此方案中，系统将从可配置的网址端点中提取广告技术平台提供的竞价代码，并在设备上执行。鉴于移动设备上的资源有限，竞价代码应遵循以下准则：

  • 代码应在预定义的时间段内执行完毕。此约束条件将统一应用于所有买方广告网络。此约束条件的详细信息将在后续更新中分享。
  • 代码必须保持独立，不得包含任何外部依赖项。

由于竞价代码（例如出价逻辑）可能需要访问应用安装来源等用户私人数据，因此运行时将不提供网络或存储空间访问权限。

编程语言

广告技术平台提供的竞价代码应使用 JavaScript 编写。 这样一来，广告技术平台便可执行诸多操作，例如在支持 Privacy Sandbox 的平台上共享出价代码。

赢得广告呈现机会

得分最高的广告将被视为竞价胜出方。在此初始提案中，胜出的广告将传递到 SDK 中进行呈现。

我们的计划是要改进此解决方案，确保应用或 SDK 无法通过与胜出的广告相关的信息来确定与用户的自定义受众群体成员资格或应用互动记录相关的信息（类似于 Chrome 的围栏框架提案）。

展示和事件报告

广告呈现后，系统即可将胜出的展示次数报告回参与竞价的买方和卖方平台。这样一来，买方和卖方便可以在胜出的展示次数报告中添加来自竞价的信息，例如出价或自定义受众群体名称。此外，卖方和胜出的买方平台都有资格收到有关胜出广告的额外事件级报告。这样，您就可以包含有关竞价（出价、自定义受众群体名称等）以及点击、观看和其他广告事件的信息。平台会按以下顺序调用报告逻辑：

  1. 卖方报告。
  2. 买方报告。

这样一来，买方和卖方平台就能够将重要的设备端信息发回给服务器，以启用实时预算、出价模型更新和准确的结算工作流程等功能。此展示次数报告支持是对 Attribution Reporting API 的补充。

如需支持事件报告，需要完成两个步骤：卖方和买方 JavaScript 需要注册其应接收哪个事件的事件报告，而卖方负责报告事件级信息。

Protected Audience 提供了一种机制，用于通过注册信标来订阅与胜出的竞价相关的未来事件。在卖方的 reportResult() JavaScript 函数中，卖方平台可以使用平台的 registerAdBeacon() 函数注册信标。同样，买方平台也可以从其 reportWin() JavaScript 函数调用 registerAdBeacon() 方法。

registerAdBeacon(beacons)

输入：

  • event_key：一个字符串，表示要注册哪种互动类型。这可用作键来查询平台对哪些端点执行 ping 操作，同时报告竞价结果。
  • reporting_url：广告技术平台拥有的网址，用于处理事件。

事件键是负责报告竞价结果的卖方 SDK 拥有的字符串标识符。为实现回调，广告技术平台会使用与卖方在报告事件时所用键相匹配的键来注册信标。这些键不需要 k-匿名化，但对于给定的自定义受众群体，可以注册的键的数量和长度存在限制。如果调用了 reportEvent()，进行竞价的卖方平台始终有资格接收这些事件报告。只有胜出的买方平台才有资格接收这些报告。

卖方报告

平台会调用供应方提供的代码（从卖方在 selectAds() API 中的决策逻辑网址参数中提供的网址下载）中的 reportResult() JavaScript 函数：

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

输出： 包含以下内容的 JSON 对象

  • 状态：0 表示成功，任何其他值都表示失败。
  • 报告网址：平台会调用相应函数返回的这一网址。
  • 面向买方的信号：要传递给买方 reportWin 函数的 JSON 对象。

供应方可对报告网址中的相关信号进行编码，以帮助其更深入地分析竞价和胜出的广告。例如，此网址可能包含以下信号：

  • 广告呈现网址
  • 胜出的出价金额
  • 应用名称
  • 查询标识符
  • 买方信号：为支持在供应方和需求方之间共享数据，平台会将此返回值作为输入参数传递给需求方报告代码。

买方报告

平台会调用需求方提供的代码（从与竞价相关联的自定义受众群体的出价逻辑网址元数据中提供的网址下载）中的 reportWin() JavaScript 函数。

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

输入：

  • auction_signals 和 per_buyer_signals 是从 AuctionConfig 中提取的。买方平台需要传递到报告网址的所有信息都可能来自这些数据。
  • signals_for_buyer 是卖方 reportResult 的输出。这样一来，卖方平台就有机会与买方平台共享数据以生成报告。
  • contextual_signals 包含应用名称等信息，custom_audience_signals 包含自定义受众群体信息。未来可能会添加其他信息。

输出结果如下：

  • 状态：0 表示成功，任何其他值都表示失败。
  • 报告网址：平台会调用相应函数返回的这一网址。

报告事件

只有在完成对竞价的展示次数报告后，才可以报告事件。卖方 SDK 负责报告所有事件。平台会公开一个 API，该 API 接受 ReportEventRequest 来指定最近进行的竞价、报告的事件键、与该键关联的数据，以及是否应将报告发送给买方和/或卖方，以及针对广告事件的可选输入事件。客户端定义要报告的事件键和数据集合。

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

输入：

  • ad_selection_id 必须是从 AdSelectionOutcome 中检索到的最近进行的竞价的 AdSelectionId。
  • event_key 是卖方定义的字符串，用于描述互动事件。
  • event_data 是一个字符串，表示与 event_key 关联的数据
  • reporting_destinations 是一个位掩码集，使用平台提供的标志。它可以是 FLAG_REPORTING_DESTINATION_SELLER 和/或 FLAG_REPORTING_DESTINATION_BUYER。
  • input_event（可选）用于与 Attribution Reporting API 集成。如果是点击事件，则为 InputEvent 对象；如果是观看事件，则为 null。如需详细了解此参数，请参阅 Attribution Reporting API 集成。

卖方 SDK 在调用 reportEvent 后，平台会根据 reporting_destinations 标志，尝试将 event_key 与买方和卖方在其 reportWin 和 reportResult JavaScript 函数中注册的键进行匹配。如果有匹配项，平台会将 event_data POST 到关联的 reporting_url。请求的内容类型为纯文本，正文为 event_data。系统会尽最大努力处理此请求，如果发生网络连接错误、出现服务器错误响应或未找到匹配的键，该请求将静默失败。

Attribution Reporting API 集成

为支持参与 Protected Audience 竞价的买方，我们将跨 Protected Audience API 和 Attribution Reporting API (ARA) 提供跨 API 功能。借助此功能，广告技术平台可以评估其在各种再营销策略中的归因效果，以便了解哪些类型的受众群体可以带来最高的投资回报率。

通过这种跨 API 集成，广告技术平台可以：

  • 创建要同时用于 1) 广告互动报告和 2) 来源注册的 URI 的键值对映射。
  • 将 Protected Audience 竞价的竞价数据添加到其来源端键映射中，以生成汇总摘要报告（使用 Attribution Reporting API）。如需了解详情，请参阅 ARA 设计提案。

当用户查看或点击广告时：

  • 使用 Protected Audience 报告这些事件互动时所使用的网址会向买方提供必要的数据，以便买方通过 Attribution Reporting API 将观看或点击注册为符合条件的来源。
  • 广告技术平台可以选择使用该网址传递 CustomAudience（或其他有关广告的相关上下文信息，例如广告展示位置或观看时长），以便在广告技术平台正在查看广告系列的整体效果时，能够将此元数据向下传播到汇总报告中。

启用来源注册

reportEvent() 将接受新的可选参数 InputEvent。已注册广告信标的胜出买方可以选择通过 Attribution Reporting API 将哪些 reportEvent 报告注册为注册来源。请求标头 Attribution-Reporting-Eligible 将被添加到从 reportEvent() 发送的所有事件报告请求中。具有适当 ARA 标头的任何响应的解析方式与其他常规 ARA 来源注册响应的解析方式相同。如需了解如何注册来源网址，请参阅 Attribution Reporting API 说明文档。

由于 Android 上的 ARA 支持观看事件和点击事件，因此 InputEvents 用于区分这两种类型。与在 ARA 来源注册中一样，reportEvent() API 会将通过平台验证的 InputEvent 解释为点击事件。如果 InputEvent 缺失、为 null 或无效，来源注册将被视为观看事件。

请注意，竞价后的 eventData 可能包含敏感信息，因此平台会在重定向的来源注册请求中删除 eventData。

互动和转化报告示例

在此示例中，我们将从买方的角度来分析，买方有意将竞价数据、呈现的广告和转化应用中的数据关联起来。

在此工作流程中，买方与卖方协调，将唯一 ID 发送到竞价中。在竞价过程中，买方会将此唯一 ID 与竞价数据一起发送。在呈现和转化期间，所呈现广告中的数据也会以相同的唯一 ID 发送出去。之后，您可以使用唯一 ID 将这些报告关联起来。

工作流程：在竞价开始之前，买方在程序化实时出价（“RTB”）出价响应中向卖方发送唯一 ID。该 ID 可以设置为变量，如 auctionId。此 ID 会在 auctionConfig 中以 perBuyerSignals 的形式传入，并在买方的出价逻辑中提供。

  1. 在执行 reportWin 期间，买方可以注册要在广告呈现期间触发的广告信标，并且可针对特定互动事件 (registerAdBeacon()) 进行注册。若要为广告事件关联竞价信号，请将 auctionId 设置为信标网址的查询参数。
  2. 在广告呈现期间，您可以使用事件级数据触发您在竞价期间注册的信标，也可以使用事件级数据对其进行增强。卖方必须触发 reportEvent() 并传入事件级数据。平台将对与触发的 reportEvent() 相关联的买方已注册广告信标网址执行 ping 操作。
  3. 买方将使用 Attribution-Reporting-Register-Source 标头响应广告信标请求，从而通过 Attribution Reporting API 注册广告。若要为转化事件关联竞价信号，请在“注册来源”网址中设置 auctionId。

完成上述流程后，买方将获得竞价报告、互动报告和转化报告，它们可以使用可用于相互关联的唯一 ID 来关联。

类似的工作流程适用于需要访问归因数据的卖方，卖方也可以使用唯一 ID 通过 registerAdBeacon() 发送。reportEvent() 调用包含一个目标属性，可用于将报告同时发送给买方和卖方。

由广告技术平台管理的可信服务器

目前的广告选择逻辑需要预算消耗状态等实时信息，才能确定是否应该选择候选广告以进行竞价。买方和卖方平台均可从其运行的服务器获取这些信息。为尽量减少通过这些服务器泄露任何敏感信息，此提案要求进行以下限制：

  • 这些服务器的行为（本部分的后续内容将会介绍）不会泄露用户信息。
  • 服务器不会根据其看到的数据创建假名化个人资料，也就是说，服务器必须是“可信”的。

买方：买方启动买方出价逻辑后，平台会从可信服务器对可信出价数据进行 HTTP 提取。此网址的构成方式如下：附加所处理的自定义受众群体的“可信出价信号”元数据中的网址和键。只有在处理来自设备端自定义受众群体的广告时，系统才会进行此类提取。在此阶段，买方可强制执行预算、检查广告系列暂停/取消暂停状态、执行定位，还可执行更多其他操作。

以下是一个示例网址，用于根据来自自定义受众群体的“可信出价信号”元数据提取可信出价数据：

https://www.kv-server.example/getvalues?keys=key1,key2

服务器的响应应该是一个 JSON 对象，其键为 key1、key2 等，其值将可供买方的出价函数使用。

卖方：与上述买方流程类似，卖方可能需要提取竞价中所考虑的广告素材的相关信息。例如，发布商可能会出于品牌保障方面的考虑，强制要求特定广告素材不得在其应用中展示。此信息可供提取，并可供卖方竞价逻辑使用。与买方可信服务器查询类似，卖方可信服务器查询也是通过 HTTP 提取进行的。此网址的构成方式如下：为可信评分信号网址附加需要提取数据的广告素材的呈现网址。

以下是一个示例网址，用于根据广告素材呈现网址来提取竞价中所考虑的广告素材的相关信息：

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

服务器的响应应该是一个 JSON 对象，其键为请求中所发送的呈现网址。

这些服务器会以可信方式运行，在安全和隐私保护方面具有诸多优势：

  • 可以信任服务器为每个键返回的值均仅基于相应的键。
  • 服务器不会执行事件级日志记录。
  • 服务器不会根据这些请求产生其他副作用。

作为一种临时机制，买方和卖方可从任何服务器（包括他们自己运营的服务器）提取这些出价信号。不过，在发布版本中，请求将仅发送到可信的键值对类型服务器。

买方和卖方可针对兼容 Privacy Sandbox on Android 的平台和网页使用通用的可信键值对类型服务器。