SDK 執行階段可視度設計提案

在 SDK 執行階段中，廣告 SDK 無法存取發布商的檢視區塊階層，但會具有專屬的檢視畫面。由於廣告檢視畫面並未附加至應用程式視窗，因此 SDK 無法在 SDK 執行階段外使用相同的 View API，判斷廣告是否向使用者顯示。這包括不會傳回預期值的 Android View API，例如 getLocationOnScreen、getLocationInWindow 或 getVisibility。

支援廣告可視度評估功能是 SDK 執行階段的核心規定。這個設計提案的目標是支援 Open Measurement 和類似的評估服務。本文討論的解決方案或許也適用於 Attribution Reporting API。歡迎提出對這個提案的意見回饋。

功能

此設計的目標為協助廣告 SDK 或評估服務合作夥伴計算下列可視度資料 (名稱尚未確定，隨時可能變動)：

SDK 執行階段可視度總覽。

• viewport [Rect]：代表裝置螢幕或應用程式視窗的幾何圖形，視平台功能而定。
• uiContainerGeometry [Rect]：所顯示的 SandboxedSdkView 幾何圖形。
• alpha [float]：所顯示的 SandboxedSdkView 不透明度。
• onScreenGeometry [Rect]：不會遭父項檢視畫面裁剪的 uiContainerGeometry 子集，取決於所包含的 viewport。
• occludedGeometry [Rect]：onScreenGeometry 中遭應用程式階層中任何檢視畫面遮蔽的部分。包含每個遮蔽的 Rect，分別對應至零、一或多個與 SandboxedSdkView onScreenGeometry 重疊的應用程式檢視畫面。

需求條件

• uiContainerGeometry、onScreenGeometry 和 occludedGeometry 的值會以 viewport 的座標空間表示。
• 回報可視度變更情形時，會盡可能減少延遲時間。
• 從廣告檢視畫面第一次到最後一次出現的整個生命週期，皆可評估可視度。

設計提案

本提案的基礎為利用提供者和用戶端 UI 程式庫呈現 UI 的做法。我們將擴充 UI 程式庫，允許 SDK 註冊一或多個 UI 工作階段觀察器。每當偵測到會影響「capabilities」一節所列資料類型的相關事件時，觀察器就會收到可視度資訊。SDK 執行階段中的評估 SDK 包括 OMID 和 MRAID 實作項目，這些 SDK 可將這個觀察器附加至 UI 工作階段，這樣 SDK 就能直接收到這類資訊。評估服務合作夥伴產生 JavaScript 可視度事件時，可結合從 UI 程式庫取得的資訊，以及現有內容的資料，例如使用插入至廣告素材的評估指令碼時可用的資料。

可視度的控管流程。

用戶端程式庫會運用 ViewTreeObserver 等事件監聽器，監聽廣告 UI 變更情形。每當用戶端程式庫認為廣告 UI 的變更方式可能影響可視度評估功能，就會確認上次傳送通知至觀察器的時間。如果上次更新時間超過允許的延遲時間，系統就會建立新的 AdContainerInfo 物件，並將通知分派給觀察器。允許的延遲時間是由 SDK 設定，行動裝置上的最短延遲時間至多為 200 毫秒。比起現今 Android 上大多數 OMID 實作項目執行的輪詢作業，這種事件型模型較能維護系統健康狀態。

API

以下項目會新增至 privacysandbox.ui.core 程式庫：

• SessionObserver：通常是由評估 SDK 實作，並附加至 SDK 透過 privacysandbox.ui 傳回的工作階段。這個介面也能讓評估 SDK 選擇接收特定類別的可視度信號。如此一來，UI 用戶端程式庫只會收集觀察器感興趣的信號，因此較能維護系統整體健康狀態。
• registerObserver()：已新增至 Session 類別，這個方法能讓任何具有工作階段存取權的項目註冊觀察器。如果在 UI 工作階段開啟後才註冊觀測器，這些項目就會立即收到快取的 AdContainerInfo。若是在工作階段開啟前完成註冊，則會在工作階段開啟時收到 AdContainerInfo。
• AdContainerInfo：具有 getter 的類別，可讓觀察器針對「功能」一節所列的資料類型，取得唯讀的廣告容器資訊。這些 getter 的回傳值會盡可能對應至 View 及其子類別中現有 getter 的可包裝回傳值。如果使用 Jetpack Compose 建立廣告容器，這個項目會公開容器的語意屬性。這個類別可用於計算與可視度相關的 MRAID 和 OMID 事件。
• SessionObserverotifyAdContainerChanged()：在可視度變更時通知觀察器，且會傳遞 AdContainerInfo 物件。只要偵測到會影響「功能」一節所列資料類型的事件，系統就會呼叫此方法。請注意，系統在呼叫工作階段上的方法時，也可能呼叫這個方法。舉例來說，系統會呼叫 Session.notifyResized() 來要求 SDK 調整廣告大小，並在這類情況下呼叫 SessionObserver.notifyAdContainerChanged()。
• SessionObserverotifySessionClosed()：在工作階段關閉時通知觀察器。

注意：SessionObserver 的生命週期會與工作階段的生命週期相連結。工作階段關閉後，SessionObserver 會收到 notifySessionClosed() 呼叫，然後就不會再收到其他方法。由於 UI 提供者 SDK 可能會關閉工作階段，或是 SandboxedSdkView 會從發布商應用程式視窗卸離，因此評估 SDK 必須區分 UI 工作階段和廣告工作階段。廣告可能會在多個工作階段中顯示。舉例來說，如果發布商不處理裝置旋轉事件，系統就會在每次裝置旋轉時重新啟動活動。刪除活動時，SandboxedSdkView 會從視窗卸離，UI 工作階段也會關閉。如果發布商在活動重新啟動時保留 UI 轉接程式，或許能將相同的轉接程式附加至新的 SandboxedSdkView，並在活動開始後開啟新的工作階段。評估服務合作夥伴就能將觀察器附加至新的工作階段，還或許會選擇重複使用附加至上一個工作階段的觀察器，方便持續評估。

預計推出的改善項目

如果應用程式遭到入侵，在應用程式程序中執行的任何程式碼都可能遭到修改，包括 privacysandbox.ui.client 程式庫的程式碼。因此，在應用程式程序中執行的任何信號收集邏輯，都很容易遭到應用程式程式碼竄改。以上概念也適用於在 Privacy Sandbox 推出前部署的 SDK 程式碼。這類程式碼也是在應用程式程序中運作，所以 UI 程式庫的信號收集作業並不會進一步降低安全性。

此外，SDK 執行階段中的程式碼可使用名為 setTrustedPresentationCallback 的平台 API，該 API 能針對廣告 UI 呈現作業提供更完善的架構保證。setTrustedPresentationCallback 適用於介面層級，可協助對包含廣告 UI 的介面做出斷言，方法是指定呈現作業的最低門檻，例如可見像素百分比、顯示時間長度或縮放比例。如上所述，系統可核對這項資料與 UI 用戶端程式庫提供的可視度資料。由於架構提供的資料較為可靠，所以如果 UI 程式庫事件的資料與架構資料不一致，可以捨棄 UI 程式庫的事件資料。舉例來說，如果通知表示畫面未顯示廣告 UI 的像素，系統因此叫用提供給 setTrustedPresentationCallback 的事件監聽器，而用戶端 UI 程式庫在畫面上顯示的像素數量並非零，則可以捨棄用戶端 UI 程式庫的資料。

開放式問題

歡迎大家就以下幾點提供意見回饋：

1. 您是否有意瞭解某些可視度信號，但本文並未提到？
2. 在具有重要 UI 變更的前提下，目前的提案會至少每 200 毫秒更新一次可視度。您可以接受這樣的頻率嗎？或者您偏好的頻率為何？
3. 在 setTrustedPresentationCallback 資料不相符時，您偏好自行分析 setTrustedPresentationCallback 中的資訊，還是希望提供者 UI 程式庫從用戶端 UI 程式庫推送資料？
4. 您如何取用可視度信號？請提供意見回饋來回答這些問題，協助我們瞭解您的用途。