註冊廣告選取 API

發行項
11/06/2024

廣告選取 API 可在您的網站上提供使用者相關的廣告，而不需要使用第三方 Cookie。請參閱存放庫中的privacy-preserving-ads廣告選取概觀。

廣告選取 API 可以由下列專案使用：

執行供應端平臺 (SSP) 的銷售人員，可以使用 API 為其發行者提供更高品質的廣告。
執行需求端平臺 (DSP) 的購買者，可以使用 API 來改善廣告活動的效率。

若要開始使用廣告選取 API 並測試端對端流程，請註冊廣告選取 API 的有限預覽。

身為操作供應端平臺的賣方或操作需求端平臺的買方，請使用本指南來：

註冊原始試用版，以註冊廣告選取 API 有限預覽版。
發佈您的證明 JSON 檔案，以完成 API 證明。
使用支援的雲端提供者設定評估環境。
檢視廣告選取 API 檔。
準備 User-Defined Functions (UDF) 。
將您的服務部署至 Azure。
在您的網站上測試廣告選取 API。

預覽可用的時機和位置？

從 130.0.2808.0 開始的 Microsoft Edge 版本，在歐洲經濟區域 (EEA) 和英國 (英國) 以外的有限開發人員選擇加入預覽版中支援廣告選取 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 天內 發佈。若要完成證明並允許您的程式代碼存取廣告選取 API，您必須裝載此 JSON 檔案，才能使用支援的 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"。
檔案必須包含 API 清單， (與廣告服務 API) 相關聯的功能。在區段中 "platform_attestations": ，的有效成員 "attestations": 如下：
- "ad_selection_api": - 私人公開邏輯的主要 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 函式可以執行自定義商業規則。 User-Defined 函式會在已部署服務內的私人容器中執行。

每個映像都會定義一個服務。有些影像不包含 UDF，且完全由預先定義的程式代碼組成。某些影像包含 UDF，做為具有空白主體或入門程式代碼的函式，與該服務的相關 User-Defined 函式。使用您自己的自定義程式代碼，填入這些影像中 User-Defined 函式的主體。

Microsoft提供每個服務的映像，這些服務可以部署在雲端提供者上。這些是必須用於部署的公用映像。只有來自Microsoft的官方影像才能執行私人的公開公開。

部署的映射：

銷售人員的服務

Service	描述
SellerFrontEnd	`/SelectAd`提供 HTTPS 端點，此端點會接收來自賣方不受信任廣告服務的要求，以起始受保護對象的互動流程。
拍賣	`/ScoreAds`提供端點，此端點會接收來自 SellerFrontEnd 服務的要求，其中包含參與收購的報價。以 SellerFrontEnd 服務用來選擇成功者的分數值回應。
索引鍵/值	從 SellerFrontEnd 服務接收要求，其中包含來自購買者之 (的查閱密鑰，例如 `ad_render_urls`) 。傳回進行這次的必備即時評分訊號。以自備服務 (BYOS) 模式執行，因此賣方不需要在信任的執行環境中部署此服務 (TEE) ，而是可以改用 Microsoft 所提供的映射。

購買者服務

Service	描述
BuyerFrontEnd	`/GetBids`提供端點，以接收來自 SellerFrontEnd 服務的要求，以起始流動流程。
投標	`/GenerateBids`提供端點，此端點會接收來自 BuyerFrontEnd 服務的要求，以處理報價併產生報價。產生報價、選擇成功者，然後選取要轉譯的橫幅。
索引鍵/值	接收來自 BuyerFrontEnd 服務的要求，並傳回購買者所需的即時買方數據，對應至 Interest 群組中的查閱密鑰。這類要求會在每個工作流程中發生一次。以自備服務 (BYOS) 模式執行。
選取索引鍵/值 & 選取範圍	接收來自新手服務的要求，以選取並傳回其他廣告橫幅， (可參與廣告的候選) 。「選取索引鍵 & 索引鍵/值」服務也可以傳回額外的訊號，這是為了獲得支援而需要的訊號。由於選取範圍 & 索引鍵/值服務是選擇性的，因此，[函數] 服務可能會將多個要求傳送至 [主要選取範圍] & [索引鍵/值] 服務，或選擇不傳送任何要求。索引鍵/值服務 & 選取範圍必須部署在信任的執行環境中， (TEE) 。
K-匿名	收集 k 匿名計數器，並檢查獲勝廣告素材是否通過 k 匿名檢查。

使用者定義函數

銷售人員和買方必須提供自己的自定義程式碼，User-Defined Functions (UDF) ，這些 UDF 會在已部署服務內的私人容器中執行。這些 User-Defined 函式可以執行自定義商業規則。

每個買方或賣方都可以部署指定服務的多個實例，例如：

SellerFrontEnd 和 Eller。
BuyerFrontend、 Marketplace 和 K-Anonymity。

其中一些服務會接受輸入，這是定義 User-Defined 函式的 JavaScript 工作流程。

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) 和啟動廣告選取 API 服務的工作專案 user-defined-function 。

在您的網站上使用廣告選取 API

若要開始使用廣告選取 API，銷售人員和買方必須修改瀏覽器Microsoft Edge 時所執行的網站 JavaScript 程式代碼。

銷售人員：若要執行私人交易、擷取興趣群組，以及進行報告，請更新發行者網站上的程序代碼。
購買者：若要建立興趣群組並將其儲存在瀏覽器中，請更新廣告合作夥伴網站上的程序代碼。您可以使用委派機制來限制和允許建立第三方網域上的興趣群組。

若要深入瞭解可用的 API 方法，以及檢視範例程式代碼，請參閱廣告選取 API 詳細數據。

提供有關原始試用版的意見反應

若要提供有關廣告選取 API 原始試用的意見反應，請在 WICG/privacy-preserving-ads GitHub 存放庫上建立新問題：

若要檢視現有問題，請移至 WICG/privacy-preserving-ads 存放庫的 [問題] 索引卷標。
若要提交新問題，請移至新問題窗體。

另請參閱

原始試用版：

設計和技術檔：

部署的映射：

部署文稿：

Terraform 部署腳本

TEE) (信任的執行環境：

機密運算：Hardware-Based 應用程式和數據的受信任執行

天藍色：

共用方式為

預覽可用的時機和位置？

用於測試的旗標

範例 JSON 檔案

重要欄位和值

部署廣告選取 API 服務

用於部署服務的映像

銷售人員的服務

購買者服務

使用者定義函數

User-Defined 銷售人員的函式

User-Defined 適用於買方的函式

部署指南

在您的網站上使用廣告選取 API

提供有關原始試用版的意見反應

另請參閱

意見反應

其他資源

共用方式為

證明註冊和Alpha註冊

預覽可用的時機和位置？

用於測試的旗標

註冊和證明需求和程式

範例 JSON 檔案

重要欄位和值

部署廣告選取 API 服務

用於部署服務的映像

銷售人員的服務

購買者服務

使用者定義函數

User-Defined 銷售人員的函式

User-Defined 適用於買方的函式

部署指南

在您的網站上使用廣告選取 API

提供有關原始試用版的意見反應

另請參閱

意見反應

其他資源