FLEDGE 現已改名為 Protected Audience。瞭解詳情

版本資訊

Android 版 Privacy Sandbox 提供開發人員預覽版和 Beta 版計畫。我們日後會在開發人員預覽版中推出全新的 API 和功能，並將穩定版 API 升級至 Beta 版計畫。歡迎提供意見回饋。

如果您是第一次使用 Android 版 Privacy Sandbox，請先參閱「計畫總覽」。如要開始在專案中建構 Privacy Sandbox，請設定開發環境，並在您的測試裝置或模擬器上取得 Android 版 Privacy Sandbox。

目前版本

Android 版 Privacy Sandbox 2023 年 3 月的 Beta 版更新

Android 版 Privacy Sandbox 在 2023 年 3 月推出 Beta 版，內含適用於 Android 13 公開裝置的 Privacy Sandbox API 更新。這個版本包含 Ad Services Extensions 5 API，功能與開發人員預覽版 6 類似，但有幾處關鍵修正。

已知限制

  • 為更新 FLEDGE 自訂目標對象而定期執行的背景擷取工作會導致程序異常終止。有鑑於此問題，我們將 FLEDGE 預設為停用。

一般

  • 從這個版本起，您可以使用 Attribution Reporting API。該 API 先前已停用。如果您在之前的 Beta 版本中使用 Attribution Reporting API，請先透過下列任一步驟清除您的應用程式或裝置資料，再使用這個 Beta 版本：
    • 在裝置或模擬器中前往「設定」，並針對任何用於測試的應用程式清除應用程式專屬儲存空間 (而不只是快取而已)。
    • 將實體/模擬裝置恢復原廠設定。
    • 如果是模擬裝置，請執行 Wipe Data 函式。
  • 歸因報表現已支援偵錯金鑰，可讓開發人員接收未經修改的報表以及由 Attribution API 產生的隱私權加強報表。改用 Privacy Sandbox 時，偵錯金鑰也讓您有機會深入瞭解報表的結構。
  • 歸因報表最近出現廣告服務錯誤，其中 registerSource 和 registerTrigger 會在例外狀況下執行失敗。如果您在開發期間遇到這些問題，我們已推出修正方案，因此一段時間後，這些問題應該都能迎刃而解。
  • Topics API 預覽功能現可媲美 Android 開發人員預覽版的 Privacy Sandbox。Topics API 呼叫端可預覽主題，但主題擷取呼叫不會納入每週週期計算，觀察到的呼叫端主題清單也不會更新。詳情請參閱 shouldRecordObservation 欄位。

  • 如要在 Android 版 FLEDGE 中啟用測試功能，請註冊參加 Beta 版計畫，並使用相同的 Google 帳戶登入測試裝置。否則，您嘗試呼叫 API 時會產生 IllegalStateException 並顯示「Service is not available」訊息。在下一個 Beta 版本中，我們應會恢復支援 FLEDGE。

    與此同時，您可以使用開發人員預覽版繼續進行測試 (建議做法)。此外，您也可以在裝置上手動啟用 FLEDGE，但請留意以下事項：

    您可以使用下列 ADB 指令啟用 FLEDGE。不過，這會導致背景擷取程序異常終止，進而對系統健康狀態指標造成負面影響。由於平台可能會重設這些值，因此這並非一勞永逸的解決方案。

    adb shell device_config set_sync_disabled_for_tests persistent
adb shell setprop debug.adservices.fledge_select_ads_kill_switch false
adb shell setprop debug.adservices.fledge_custom_audience_service_kill_switch false
adb shell device_config put adservices fledge_background_fetch_enabled true

開發人員預覽版 7

發布日期：2023 年 1 月 26 日

Android 版 FLEDGE API

  • 下列 JavaScript 方法中的 custom_audience_signals 參數已重新命名：
    • generateBid() 已重新命名為 custom_audience_bidding_signals。
    • scoreAd() 已重新命名為 custom_audience_scoring_signals。
    • reportWin() 已重新命名為 custom_audience_reporting_signals。
  • 這個版本加入了新的 selectAds 覆寫值，會利用 AdSelectionFromOutcomeConfig 比較 selectAds 結果。也就是說，採用此 API 的廣告技術 SDK 可以執行刊登序列中介服務。詳情請參閱開發人員指南。
  • selectAds() API 可以在廣告選擇程序期間快取所擷取 JavaScript 的出價和評分邏輯。
    • 在 JavaScript 擷取呼叫期間，可以使用伺服器傳回的 Cache-Control 標頭控制快取。使用 no-cache 或 no-store 可防止 JavaScript 回應受到快取，使用 max-age 則能控制快取持續時間。
    • 目前的快取項目 max-age 的預設值是兩天。

Attribution Reporting on Android API

過往版本

初始 Beta 版，2023 年 1 月

發布日期：2023 年 1 月 9 日

Android 版 Privacy Sandbox Beta 版 1 的發布象徵 Privacy Sandbox API 首次應用於公開裝置，並改進了以下方面。

一般

  • Android 版 Privacy Sandbox Beta 1 的功能與開發人員預覽版 5 相同，並加上下列其他功能和限制。
  • 開發人員必須完成註冊程序，才能使用廣告相關 API (包括 Topics、FLEDGE 和歸因報表)。註冊程序會驗證開發人員身分，並收集 API 所需的開發人員專屬資料。
  • Android 版 Privacy Sandbox Beta 1 發布後，註冊完成並提交詳細資料至許可清單的開發人員，可能有機會在自己的實體裝置上進行測試。如要根據發布的穩定版 API 進行開發，請下載新的 SDK Ad Services Extensions 4。

Topics API

Attribution Reporting API

  • 歸因報表已停用，因此無法在這個版本中使用。下一個 Beta 版本應重新啟用此 API 的存取權。建議您繼續使用開發人員預覽版進行測試。

SDK 執行階段

我們預計將在下一個主要 Android 平台版本中修正下列限制：

  • 目前無法正常在 RecyclerView 這類可捲動的檢視畫面中顯示廣告。如果元素調整過大小，可能會出現資源浪費情形。使用者觸控捲動事件未正確傳遞至執行階段。
  • SDK 執行階段程序無法使用 WebView 算繪功能。
  • 無法使用個別 SDK 儲存空間。
  • 尚未支援 getAdId 和 getAppSetId API。

開發人員預覽版 6

發布日期：2022 年 10 月 31 日

Android 版 Privacy Sandbox 開發人員預覽版 6 改進了以下方面：

一般

  • 為準備發布正式版，開發人員預覽版 6 推出了旗標，用於在預設情況下停用 Privacy-Preserving API 存取權。如要進行測試，請執行下列指令，在開發人員預覽版中啟用 Privacy-Preserving API 存取權：

    adb shell device_config put adservices global_kill_switch false

  • AdIdManager 和 AppSetIdManager API 僅適用於 Google Play 服務 22.36.16 以上版本。

    • 在 Android 裝置上，確認「設定」>「應用程式」>「Google Play 服務」下方列出的版本正確無誤。
    • 如果需要將 Google Play 服務更新為適當的版本，請使用您的 Google 帳戶登入 Android 測試裝置或模擬器。然後依序前往「Google Play 商店」>「個人資料」圖示 >「設定」>「關於」。在「Play 商店版本」標題下方，輕觸「更新 Play 商店」。
    • 這個步驟僅適用於開發和測試，在 Privacy Sandbox 推出公開版本後無需執行此步驟。

Topics API

  • 新增 Preview API，以切換 getTopics 是否註冊為觀測器。
  • 對 GetTopicsRequest 類別的初始化程式碼進行小幅變更。
  • 發布 Topics API 整合指南。

Android 版 FLEDGE API

  • 如果您要對實際伺服器進行測試，現在會強制執行 API。請按照這些步驟設定裝置。如果使用範例應用程式中的遠端覆寫功能，則不需要執行這些步驟。
  • 破壞性變更：
    • 將參數中的 Url 替換為 Uri。這種做法適用於所有 FLEDGE API 以及出價和評分邏輯的自訂 JavaScript。
    • 已從 Custom Audience API 輸入內容中移除 owner 欄位。
  • 未完成的自訂目標對象現在可立即用於重新整理背景。
  • JavaScript 記憶體限制現在設為 10 MB。這種做法適用於出價和評分邏輯。

Attribution Reporting API

  • 廣告技術必須先註冊，才能使用開發人員預覽版 6 中的 Attribution Reporting API。詳情請參閱「註冊 Privacy Sandbox 帳戶」一文。
  • 這個版本推出偵錯金鑰，可讓開發人員接收未經修改的報表以及由 Attribution Reporting API 產生的隱私權加強報表。改用 Privacy Sandbox 時，偵錯金鑰也讓您有機會深入瞭解報表的結構。

開發人員預覽版 5

一般

  • 您必須先啟用 API 並設定 API 專屬權限，才能在開發人員預覽版 5 中存取 Privacy Sandbox API。
    • Android 版 Privacy Sandbox 的設計可讓使用者控制裝置是否啟用隱私權保護 API 和 SDK 執行階段。這些設定在開發人員預覽版 5 中預設為停用。您可以使用 ADB 指令啟用 API 存取權。
    • 呼叫端應用程式必須在資訊清單中指定 API 專屬權限，以及會控制內嵌 SDK 存取權的相關 AdServices 設定。
  • 在前景執行時，應用程式必須呼叫隱私權保護 API。
  • AdIdManager 和 AppSetIdManager 目前尚無法運作，我們將在日後推出的版本中啟用這些功能。

SDK 執行階段

  • sendData() 將於日後推出的版本中淘汰。
  • loadSdk() 現在會傳回 IBinder 物件，方便您在已啟用執行階段的 SDK 與 AIDL 中定義的應用程式之間進行雙向通訊。
  • 應用程式可以存取其他已啟用執行階段的 SDK 生命週期事件，例如 SDK 程序終止時的情況。

Attribution Reporting API

這個版本推出了 Attribution Reporting API 的額外功能，包括：

  • 支援經過加密的匯總報表。
  • 支援跨應用程式和網站評估功能。
  • 將來源和觸發條件登錄回應的標頭合併：
    • 來源：Attribution-Reporting-Register-Aggregatable-Source 現已併入 Attribution-Reporting-Register-Source
    • 觸發條件：Attribution-Reporting-Register-Event-Trigger, Attribution-Reporting-Register-Aggregatable-Trigger-Data 和 Attribution-Reporting-Register-Aggregatable-Values 已合併為名為 Attribution-Reporting-Register-Event-Trigger 的單一標頭
    • Attribution-Reporting-Redirects 仍是獨立標頭

Android 版 FLEDGE API

這個版本提供多項新功能和改善項目，以及破壞性變更：

  • 破壞性變更：
    • runAdSelection() 已重新命名為 selectAds()。
    • 將 AdSelectionConfig.Builder.setAdSelectionSignals() 的參數替換為 AdSelectionSignals，用來代表 JSON 物件。
    • 更改 String 的用法，以便使用 AdTechIdentifier 物件代表廣告技術的買方/賣方。
    • 新增 TestCustomAudienceManager 和 TestAdSelectionManager 類別，用於覆寫遠端 JavaScript 擷取。
    • 自訂目標對象的擁有者必須是呼叫端應用程式的套件名稱。
  • FLEDGE API 現在會根據開發人員指南中所述的一組限制條件來驗證呼叫端應用程式。以下提供一些重要範例。
    • selectAds 和 reportImpression 現在有執行時間限制，超過限制時間後呼叫就會終止。
    • selectAds 和 reportImpression 現在對 JavaScript 執行期間的記憶體消耗量設有限制。如果記憶體消耗量超過所設限制，API 就會擲回錯誤。
    • selectAds 和 reportImpression 現在會驗證 AdSelectionConfig 物件，確保欄位使用有效語法，且網址位於賣方欄位所用的 eTLD+1 底下。
    • AdServices 現在會在建立自訂目標對象時進行驗證。部分驗證程序包括確認到期時間是否有效，以及對應用程式可建立的自訂目標對象數量和 joinCustomAudience 呼叫中提供的廣告總大小設限。此外，驗證功能也會強制規定，針對信號、出價邏輯擷取和背景擷取作業所提供的 URI，皆須位於買方的網域中。
  • 每天自訂目標對象中繼資料都會由背景擷取程序更新。
  • 系統會在解除安裝「擁有者」應用程式時，一併移除自訂目標對象。
  • 支援在廣告選擇期間指定受信任的評分信號和受信任的出價資料。如要瞭解回應格式，請參閱程式碼範例。
  • Android 版 FLEDGE API 必須搭配使用 WebView 105.0.5195.58 以上版本。詳情請參閱開發人員指南中的設定資訊。

  • 已知問題：

    • 加入自訂目標對象時，如果任何中繼資料或 AdData 值為空白或 null，則平台目前不會立即執行背景更新。自訂目標對象必須等到一天後完成更新，才能供廣告選擇使用。日後推出的版本將會讓不完整的自訂目標對象能夠立即透過背景擷取進行更新。目前預設的 JavaScript 記憶體執行上限過低，在裝置上執行一般工作負載可能造成 JavaScriptEngine 停止運作。JavaScript 執行作業可能會意外終止，並顯示錯誤訊息 "Fatal javascript OOM in CALL_AND_RETRY_LAST"。

      您可以手動解決這個問題，方法是使用下列指令設定適當的記憶體門檻：

      adb shell "device_config put adservices fledge_js_isolate_enforce_max_heap_size 10485760"

    • 不符合必要 JSON 結構的自訂目標對象廣告會在背景擷取期間更新。

Topics API

工具更新

Android Studio Canary 支援使用新模組類型建構 SDK APK。SDK 執行階段開發人員指南已更新，GitHub 中的 Privacy Sandbox 範例應用程式也反映了這項更新。

開發人員預覽版 4

發布日期：2022 年 7 月 14 日

Android 版 Privacy Sandbox 開發人員預覽版 4 新增以下功能：

SDK 執行階段

  • 應用程式現在可以透過新增 sendData()，與執行階段啟用的 SDK (RE-SDK) 通訊。
  • 本機儲存空間現在可在 SDK 執行階段流程中使用。
  • SDK 也可以在 SDK 執行階段中呈現獨立式影片廣告或內容。
  • 新增有關反射使用情形的說明，包括內容不在其他 RE-SDK 中的用途。

Attribution Reporting API

這個版本推出的變更內容，可清楚呈現 Attribution Reporting API 的使用方式，例如：

  • 匯總報表格式的變更以改善可讀性。
  • 更新「轉換篩選」和「可出價」功能的標頭欄位。
  • 在「WebApp API 參考資料」中新增說明，以說明來源和觸發條件註冊，以及隱私權和同意 API 的可用性。

Android 版 FLEDGE API

這個版本包含可協助測試及偵錯的新功能，以及內部改善功能：

  • 新增對覆寫遠端網址的支援功能，用於在開發期間擷取 JavaScript 邏輯。
  • 改善廣告選擇期間的錯誤回報。
  • 系統現在會在廣告選擇期間篩選出無效的自訂目標對象。

Topics API

這個版本對 Topics API 進行了幾項重大變更，最重要的是：

  • getTopics() API 的傳回類型已變更為新的 Topic 物件類型，該物件會封裝與分類法中主題對應的整數 ID 以及分類器和分類版本的相關資訊。您應使用此 API 更新任何現有的應用程式。
  • Topics API 現在必須使用新的一般權限。
  • 推出「裝置端分類器」系統，用於根據可公開取得的應用程式資訊動態指派主題。

已知問題

  • 這些裝置映像檔 (修訂版本 6) 的初始版本無法在 Android Emulator 31.2.10 版上載入。我們已在 2022 年 7 月 27 日更新裝置映像檔，以便解決此問題。

開發人員預覽版 3

發布日期：2022 年 6 月 9 日

Android 版 Privacy Sandbox 開發人員預覽 3 加入 Attribution Reporting API 和 Android 版 FLEDGE 的功能。

Attribution Reporting API

Attribution Reporting API 透過避免仰賴跨方 ID 的方式，進一步保護使用者隱私，同時顧及重要使用情境，支援應用程式和網頁的歸因與轉換評估功能。

這個版本包含開發人員資源，可協助您測試下列 Attribution Reporting API 功能：

  • 登錄歸因來源並觸發事件
  • 採用來源優先和安裝後歸因
  • 接收事件報表
  • 接收可匯總的報表 (此版本未經過加密)

提供應用程式範例與參考廣告技術伺服器，以協助進行測試

已知問題：

Android 版 FLEDGE

Android 的 FLEDGE 導入新的廣告顯示方法：根據應用程式開發人員定義的「自訂目標對象」和應用程式內互動情形來放送廣告。這項解決方案會將這些資訊和相關聯的廣告儲存在本機，並提供一個工作流程架構，方便使用自動化調度管理方式選取廣告。

這個版本包含開發人員資源，可協助您測試下列 Android 版 FLEDGE 功能：

  • 加入或退出自訂目標對象，並觀察參數值如何影響競價結果
  • 從遠端端點擷取 JavaScript 競價代碼
  • 設定及啟動裝置端廣告競價
  • 處理曝光報表
  • 提供範例應用程式和模擬伺服器設定，以協助進行測試

已知問題：

開發人員預覽版 2

發布日期：2022 年 5 月 17 日

開發人員預覽版 2 包含 MeasurementManager Attribution Reporting API 的早期預覽。

  • 您可以呼叫 registerSource() 和 registerTrigger() 註冊應用程式廣告事件，並取得應用程式到應用程式歸因的事件層級報表資料。我們目前採用的是最終接觸歸因模式。報表將按照報表期的定義寄送。詳情請參閱 MeasurementManager API 參考資料。

  • 實際上傳報表的時間是固定的時段，而不是確切的安排時間。報表上傳間隔預設為 4 小時，但可以透過下列 adb 指令覆寫：

    adb shell device_config put adservices measurement_main_reporting_job_period_ms <duration in milliseconds>

  • 我們會在日後推出的版本中發布用來測試 API 的範例應用程式和參考廣告技術供應商伺服器。

  • 我們將在日後推出的版本中提供其他 MeasurementManager Attribution Reporting API 功能，例如匯總報表、安裝後歸屬和重新導向。

開發人員預覽版 1

發布日期：2022 年 4 月 28 日

開發人員預覽版 1 包含 Topics API 和 SDK 執行階段的早期預先發布版。日後推出的版本將支援 Android 版 FLEDGE 和 Attribution Reporting API 功能。

  • Topics API
    • getTopics() API 目前會根據部分應用程式的離線分類功能傳回測試值。尚未實作裝置端分類。
    • 您可以使用 adb 指令覆寫週期間隔並強制觸發週期運算。
    • 詳情請參閱「主題開發人員指南」。
  • SDK 執行階段
    • 您可以使用 SDK 應用程式資訊清單檔案中的新 <sdk-library> 元素，來封裝及建構支援執行階段的 SDK (RE SDK)。在支援的測試裝置或模擬器上安裝 RE SDK，如同您平常在開發期間安裝應用程式一樣。
    • 您可以將應用程式與 RE SDK 整合、載入至 SDK 執行階段，並測試受限存取權對 SDK 程式碼的影響 (權限、記憶體和應用程式對 SDK 通訊)。我們尚未實作 RE SDK 專用的 Storage API，但預計將於日後版本中推出。
    • SDK 可以在 SDK 執行階段中，提供以 WebView 為基礎的橫幅廣告或內容。
    • 詳情請參閱「SDK 執行階段開發人員指南」。
  • Android Lint 檢查
    • 在以 API 級別 TiramisuPrivacySandbox 編譯的專案中，Android Lint 檢查可能錯誤顯示警告。舉例來說，您可能會看到這樣的警告訊息：「Call requires API level 33」(呼叫需要 API 級別 33)。您可以使用 @SuppressLint("NewApi") 註解暫時解決這個問題。