注册广告选择 API

项目
11/06/2024

广告选择 API 在不使用第三方 Cookie 的情况下在网站上提供与用户相关的广告。请参阅存储库中的privacy-preserving-ads广告选择概述。

广告选择 API 可用于：

运行供应方平台的卖家 (SSP) ，他们可以使用 API 为发布者提供更高质量的广告。
运行需求方平台的买家 (DSP) ，他们可以使用 API 来提高广告活动的有效性。

若要开始使用广告选择 API 并测试端到端流，请注册广告选择 API 的有限预览版。

对于经营供应方平台的卖方或运营需求方平台的买家，请使用本指南来：

通过注册原始试用版来注册广告选择 API 有限预览版。
通过发布证明 JSON 文件来完成 API 证明。
使用受支持的云提供商设置评估环境。
查看广告选择 API 文档。
准备 User-Defined 函数 (UDF) 。
将服务部署到 Azure。
测试网站上的广告选择 API。

预览版何时何地可用？

Microsoft Edge 版本从 130.0.2808.0 开始，在欧洲经济区 (欧洲经济区) 和英国 (英国) 之外，在有限的开发人员选择加入预览版中支持广告选择 API。

用于测试的标志

若要更改开发人员计算机上的广告选择 API 平台功能，请使用中的edge://flags#edge-ad-selection-api广告选择 API 测试标志：

“广告选择 API”标志

广告选择 API 标志启用广告选择 API 和关联的功能，例如：

归因报告。
围栏框架。
共享存储。
专用聚合。

对 alpha 测试感兴趣的开发人员可以加入广告选择 API 的源试用版。此源试用版支持对广告选择 API 功能的端到端测试，涵盖 API 使用情况和安全容器映像的部署。

对于要用于广告选择 API 的每个顶级域，请填写该域的 “源试用注册 ”表单，然后提交表单。

若要注册域 的广告选择 API 源试用版，请执行以下操作：

在新窗口或选项卡中，在 Microsoft Edge 中打开“广告选择 API 源试用版注册 ”。
单击“ 立即开始” 按钮。
阅读并同意使用条款，然后单击“ 下一步 ”按钮。此时会打开 “广告选择 API 源试用版注册 ”窗体：
在 “域 ”文本框中，输入单个顶级域：

可以将源试用版配置为支持以下任何一项：
- 单个域（例如 https://example.com），不支持其子域。
- 单个子域，例如 https://beta.example.com。
- 域（如 https://example.com）及其子域（如 https://beta.example.com）。
不支持尾随路径和查询参数。如果输入的 URI 具有尾随路径或查询参数（例如 https://example.com/path/new-feature），则会注册根域 (（如 https://example.com) 或子域），并忽略任何尾随路径或查询参数。
在 “子域支持 ”部分中，选择“ 是 ”或“ 否 ”选项按钮：
- 若要在域 (（如 https://example.com) ）中使用源试用版，而不支持其子域 (（例如 https://beta.example.com) ），请选择“ 否”。
- 若要仅在特定的子域（例如) ） https://beta.example.com (使用源试用版，请选择“ 否”。
- 若要在域 (（如 https://example.com) ）及其子域（如) ） https://beta.example.com (使用源试用版，请选择“ 是”。
在“Email地址”文本框中，提供域的有效开发人员联系人。
单击“ 提交 ”按钮。

会为顶级域生成源试用令牌，并发送给你。
创建名为 ad-selection-attestations.json的文件，并在目录中的顶级域中 /.well-known/ 托管该文件。例如：

https://contoso.example/.well-known/ad-selection-attestations.json

文件 ad-selection-attestations.json 必须在收到 OT 令牌后的 30 天内 发布。需要托管此 JSON 文件，以便完成证明并允许代码访问广告选择 API，以及使用受支持的 Microsoft Edge 客户端测试广告选择 API。

示例 JSON 文件

证明 JSON 文件必须命名为 ad-selection-attestations.json，并且必须符合以下标准。下面是文件的示例 ad-selection-attestations.json ：

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}

重要字段和值

该文件 ad-selection-attestations.json 必须包含为此顶级域生成并发送给你的源试用令牌。 "ownership_token": 是在为 广告选择 API 源试用版注册此域时生成的源试用令牌。
在节中 "platform_attestations": ， "platform": 必须是 "edge" 或 "android"。
该文件必须包含与 Ad Services API) 关联的 API (功能的列表。 "platform_attestations":在部分中，的有效成员"attestations":如下：
- "ad_selection_api":- main API，用于专用拍卖逻辑。
- "attribution_reporting_api": - 归因报告。
- "shared_storage_api": - 共享存储。
- "private_aggregation_api": - 专用聚合。
- 要求：
  - 每个 "..._api": 条目都必须有一个字段， "ServiceNotUsedForIdentifyingUserAcrossSites":具有 true 或 false 值。 true 表示此服务不用于跨站点标识用户。 false 表示此服务用于跨站点标识用户。

部署广告选择 API 服务

广告选择 API 使用受信任的执行环境 (TEE) ，为数据完整性、数据机密性和代码完整性提供级别保证;请参阅机密计算：应用程序和数据的 Hardware-Based 受信任执行。广告选择 API 提供的服务必须在 TEE 中运行，以保护这些服务使用的数据。

在 TEE 中运行的广告选择服务应部署在支持必要安全功能的云平台上。最初，可以使用机密 ACI 容器在 Azure 中部署服务;请参阅Azure 容器实例上的机密容器。

广告选择 API 提供卖家或买家需要部署的不同服务。

用于部署服务的映像

在所提供的服务映像中添加 User-Defined Functions (UDF) 。 User-Defined Functions 可以运行自定义业务逻辑。 User-Defined Functions 在部署的服务中的专用容器中运行。

每个映像定义一个服务。某些图像不包含 UDF，并且完全由预定义代码组成。某些图像包含 UDF，作为具有空正文或初学者代码的函数，这些函数是该服务的相关 User-Defined 函数。在这些图像中，使用自己的自定义代码填充 User-Defined Functions 的正文。

Microsoft为每个服务提供一个映像，该服务可以部署在云提供商上。这些是必须用于部署的公共映像。只有来自Microsoft的官方图像才能进行私人拍卖。

用于部署的映像：

面向卖家的服务

服务	说明
SellerFrontEnd	提供 HTTPS `/SelectAd` 终结点，该终结点接收来自卖家不受信任的广告服务的请求，以启动受保护的受众拍卖流。
拍卖	提供一个 `/ScoreAds` 终结点，该终结点接收来自 SellerFrontEnd 服务的请求，其中包含参与拍卖的出价。使用 SellerFrontEnd 服务用于选择优胜者的分数值进行响应。
键/值	接收来自 SellerFrontEnd 服务的请求，其中包含来自买家出价 (（例如) ） `ad_render_urls` 的查找键。返回拍卖所需的实时评分信号。在“自带服务” (BYOS) 模式下运行，因此卖方无需 (TEE) 的受信任执行环境中部署此服务，而是可以使用 Microsoft 提供的映像。

面向买家的服务

服务	说明
BuyerFrontEnd	提供一个 `/GetBids` 终结点，该终结点接收来自 SellerFrontEnd 服务的请求，以启动竞价流。
投标	提供一个 `/GenerateBids` 终结点，该终结点接收来自 BuyerFrontEnd 服务的请求，以处理投标并生成出价。生成出价，选择优胜者，然后选择要呈现的横幅。
键/值	接收来自 BuyerFrontEnd 服务的请求，并返回竞价所需的实时买家数据，对应于兴趣组中的查找键。此类请求在每个工作流中发生一次。在“自带服务” (BYOS) 模式下运行。
竞价选择 & 键/值	接收来自投标服务的请求，以选择并返回其他广告横幅， (可以参与竞价的考生) 。竞价选择 & 键/值服务还可以返回投标所需的其他信号。投标服务可能会向投标选择 & 键/值服务发送多个请求，也可以选择不发送任何请求，因为投标选择 & 键/值服务是可选的。投标选择 & 键/值服务必须部署在受信任的执行环境中， (TEE) 。
K-匿名	收集 k 匿名计数器，并检查获胜的广告创意是否通过 k-匿名检查。

用户定义的函数

卖家和购买者需要提供自己的自定义代码，作为 User-Defined Functions (UDF) ，这些函数在部署的服务中的专用容器中运行。这些 User-Defined Functions 可以执行自定义业务逻辑。

每个买家或卖方都可以部署给定服务的多个实例，例如：

SellerFrontEnd 和 Auction。
BuyerFrontend、投标和 K-匿名。

其中一些服务采用一个输入，该输入是定义 User-Defined Functions 的 JavaScript worklet。

面向卖家的 User-Defined 函数

UDF	运行 UDF 的服务	说明
`scoreAd()`	拍卖	为每个买家的出价生成分数，或拒绝出价。然后， SellerFrontEnd 服务使用此分数，从所有买家中选择一个赢家。
`reportResult()`	SellerFrontEnd	对于事件级报告。在选择最终获胜者后，在 SellerFrontEnd 服务中运行。通知卖方中标人，并提供出价值。

面向买家的 User-Defined 函数

UDF	运行 UDF 的服务	说明
`generateBids()`	投标	生成出价，并选择将显示的横幅。
`reportWin()`	SellerFrontEnd	对于事件级报告。如果买家的出价赢得拍卖，请在 SellerFrontEnd 服务中运行。通知买家他们已赢得拍卖，并生成稍后将触发的通知 URL，例如在横幅呈现或其他客户端事件期间。
`getValues()`	竞价选择 & 键/值	如果买家使用该项服务，请在竞价选择 & 键/值服务中运行。允许对数据查找和选择执行自定义代码。

部署指南

将广告选择 API 服务部署到 Azure：

在 Azure Microsoft 创建 Azure 帐户并创建订阅。
选择 “机密 ACO 容器 ”选项。
转到新窗口或选项卡中的 Terraform 部署脚本，然后下载 Terraform 部署脚本并查看部署文档。 注意： 确保下载的图像的哈希与下载的脚本中的哈希匹配。
Terraform 脚本已包含指向Microsoft提供的公共映像的链接。选择所需的服务，并按照包含 readme.md中的步骤部署它们。
1. 为环境设置任何特定标志，包括拍卖工作位置。
2. 配置所有先决条件并准备所有用于部署的工具。
3. 创建 Azure 资源并运行完成部署的 Terraform 脚本。
开发包括 (UDF) 在内的工作项 user-defined-function ，并启动广告选择 API 服务。

在网站上使用广告选择 API

若要开始使用广告选择 API，卖家和买家需要修改其网站的 JavaScript 代码，该代码在浏览器Microsoft Edge 时运行。

卖家：若要运行私人拍卖、提取兴趣组和进行报告，请在发布者网站上更新代码。
购买者：若要创建兴趣组并将其存储在浏览器中，请更新广告合作伙伴网站上的代码。可以使用委派机制来限制并允许在第三方域上创建兴趣组。

若要详细了解哪些 API 方法可用以及查看示例代码，请参阅广告选择 API 详细信息。

提供有关源试用版的反馈

若要提供有关广告选择 API 源试用版的反馈，请在 WICG/privacy-preserving-ads GitHub 存储库上创建新问题：

若要查看现有问题，请转到 WICG/隐私保留-广告存储库的“问题”选项卡。
若要提交新问题，请转到新问题表单。

另请参阅

源试用版：

设计和技术文档：