SDK 執行階段可讓廣告 SDK 在沙箱環境中執行，防止廣告 SDK 存取發布者的檢視區塊階層。為顯示廣告，平台會向 SDK 公開 SandboxedSdkProvider.getView API 來取得廣告檢視畫面，並將其封裝為 SurfacePackage，透過處理序間通訊 (IPC) 傳送至用戶端應用程式。這麼做有幾項缺點，請參閱下文。本文件會接著介紹專為克服這些挑戰而建構的建議 Jetpack 程式庫。
擴充平台 API 的理由
架構 API 的設計可提供靈活彈性，並將為 UI 呈現作業建構側邊管道的工作，交由應用程式和 SDK 處理。這個側邊管道具有以下功用：
- 讓 SDK 管理生命週期內的多個廣告檢視畫面，並瞭解在 SDK 建立廣告 UI 後廣告 UI 所受到的影響。
- 分離檢視畫面建立作業和內容繫結作業。使用側邊管道可讓 SDK 傳回與應用程式廣告請求相對應的物件 (內容)，而應用程式可在每個適當時機，將該物件繫結至廣告容器。
- 除去用於跨程序顯示 UI 的基礎平台結構 (該平台目前使用
SurfaceControlViewhost，並從中產生SurfacePackage)。 - 在 SDK 執行階段啟用廣告 SDK，方便在廣告容器 UI 變更時自動接收通知。如果發布者變更廣告容器的版面配置，發布者必須明確呼叫 API 來通知 SDK，SDK 才會知道發生變更。
- 同步處理廣告 UI 和廣告容器的大小調整作業，不讓使用者看見任何卡頓情形。
- 自動管理回溯相容性。
SurfacePackage不適用於 API 級別 30 以下的版本。此外，如果裝置上沒有 SDK 執行階段，且 SDK 為發布者本機程序，那麼在可從 SDK 直接取得廣告檢視畫面的情況下，就沒有必要建立SurfacePackage。側邊管道可從 SDK 和應用程式開發人員程式碼中，除去這項複雜作業。 - 啟用廣告 UI，與可組合函式流暢整合。如果 Jetpack Compose 開發人員不使用檢視畫面，也可以繼續代管由仍使用檢視畫面的 SDK 開發人員所產生的 UI。
UI 程式庫
UI 程式庫可除去上述複雜作業，為發布者和 SDK 提供可用於跨程序顯示 UI 的側邊管道，並在使用者與 UI 和裝置互動時持續更新 UI。
UI 程式庫有三種，分別為「核心」、「用戶端」和「提供者」程式庫。核心程式庫會提供介面，供用戶端程式庫和提供者程式庫使用。UI 提供者 (通常是 SDK) 取決於提供者程式庫，UI 取用者 (通常是發布者) 則取決於用戶端程式庫。用戶端程式庫和提供者程式庫會共同構成所需的側邊管道，用於建立和維護 UI 工作階段。
API
以下是用來在 SDK 執行階段呈現 UI 的 API：
SandboxedUiAdapter：由 SDK 建立，可取得發布者 UI 要顯示的內容。
SandboxedSdkView：由發布者建立，這個容器會保留透過 SandboxedUiAdapter 取得的內容。
Session：由 SDK 建立，用於回應 SandboxedUiAdapter.openSession()，代表一個 UI 工作階段呼叫。此 API 會構成 SDK 與發布者之間通訊通道的 SDK 端，並接收 SandboxedSdkView 異動通知，例如視窗卸離、大小調整或設定變更。
SessionClient：由用戶端程式庫建立，會構成 SDK 和發布者之間通訊通道的發布者端。
SandboxedSdkUiSessionStateChangedListener：由發布者建立。這個事件監聽器會監聽與 SandboxedSdkView 相關聯的 UI 工作階段狀態變更。
如要進一步瞭解這些 API，請參閱 privacysandbox-ui 參考文件。
控制流程
下圖說明用戶端與提供者 UI 程式庫在多種情況下的互動方式：
上圖顯示發布者如何以程式輔助方式或 XML 建立 SandboxedSdkView，並透過 SDK 定義的 API，將該項目附加至從 SDK 取得的 SdkSandboxUiAdapter。如要掌握所有 UI 狀態變更，發布者應在附加 SdkSandboxUiAdapter「之前」，將 SandboxedSdkUiSessionStateChangedListener 新增至 SandboxedSdkView。
下圖顯示發布者的活動處理設定變更時，用戶端程式庫會負責將設定變更轉送至 SDK，方便 SDK 據此更新 UI。舉例來說，當使用者旋轉裝置，且發布者透過設定 android:configChanges=["orientation"] 來宣告處理活動設定變更時，就會觸發這個流程。
這張圖表說明 SDK 如何使用 SessionClient 上的方法，在廣告容器中要求變更。當 SDK 想重新調整廣告大小，且需要發布者配合新尺寸調整廣告容器大小時，就會觸發這個 API。在回應使用者互動 (例如 mraid.resize()) 時，可能會發生這種情況。
此圖表說明當 SandboxedSdkView 從視窗卸離時，工作階段會如何關閉。SDK 也可以叫用 SessionClient.onSessionError()，隨時關閉工作階段，例如在使用者失去網路連線時。
Z 順序
用戶端 UI 程式庫會在內部使用 SurfaceView，代管 SDK 的 UI。SurfaceView 可以使用 Z 順序，在發布者視窗上方或下方顯示 UI。SandboxedSdkView.orderProviderUiAboveClientUi() 方法會接受布林值 setOnTop，可以控制上述位置。
當 setOnTop 為 true，SandboxedSdkView 上的每個 android.view.MotionEvent 都會傳送至 SDK。若為 false，則會傳送至發布者。根據預設，動作事件會傳送至 SDK。
發布者通常不需要變更廣告檢視畫面的預設 Z 順序。不過，在顯示會遮住廣告的 UI (例如下拉式選單) 時，應暫時捨棄預設的 Z 順序，待遮住廣告的 UI 元素關閉後，再還原 Z 順序。我們正在尋找方法，在用戶端 UI 程式庫中自動執行這項程序。
捲動
如果廣告 UI 以 Z 順序顯示在發布者視窗上方，廣告 UI 的 MotionEvents 就會傳送至 SDK。系統會以特別的方式，處理從廣告 UI 上啟動的捲動和快速滑過手勢：
- 垂直的捲動和快速滑過手勢會傳送至發布者容器，並由發布者容器處理。如此一來，當放入廣告 UI 的發布者容器可垂直捲動時，就能提供良好的使用者體驗。您不需要為此對 SDK 或發布者執行額外工作。
- 水平的捲動和快速滑過手勢會傳送至 SDK，並由 SDK 處理。如果廣告 UI 本身為可水平捲動 (例如廣告輪轉介面)，就能提供良好的使用者體驗。
實作指南
SDK 應實作下列項目：
SandboxedUiAdapter：系統會將這個項目傳回給發布者，用來回應 SDK 定義的 API，例如loadAd。此導入作業的openSession()方法應用於向 SDK 伺服器發出廣告請求，並準備該要求的廣告檢視畫面。Session**：系統會傳回這個項目，用來回應SandboxedUiAdapter.openSession呼叫。這可讓用戶端程式庫取得廣告 UI，並向 SDK 通知此 API 的變更。所有Session方法都應在此實作。
發布者應執行下列操作：
- 利用 XML 或程式輔助方法建立
SandboxedSdkView。 - 將
SandboxedSdkUiSessionStateChangedListener附加至SandboxedSdkView，掌握 UI 變更情形。 - 將 SDK 提供的
SandboxedUiAdapter附加至SandboxedSdkView。 - 照常將
SandboxedSdkView新增至視窗，讓用戶端程式庫利用 SDK 建立及維護 UI 工作階段。 - 在適當時機回應
SandboxedSdkUiSessionChangedListener回報的狀態變更。舉例來說，如果 SDK 意外關閉工作階段，發布者可將SandboxedSdkView替換成靜態圖片，或將圖片從檢視區塊階層中移除。 - 在製作可能遮住廣告 UI 的轉場效果 (例如下拉式選單) 時，暫時將
orderProviderUiAboveClientUi設為 false，將廣告 UI 置於發布者視窗下方。等下拉式選單關閉後，再呼叫orderProviderUiAboveClientUi並設為true。
平台 API 的日後發展
我們預計在 UI 程式庫進入 Beta 版後，淘汰與呈現 UI 相關的 SDK 執行階段平台 API，也就是 SdkSandboxManager.requestSurfacePackage() 和 SandbxedSdkProvider.getView()。
開放式問題
- UI 程式庫還應自動處理哪些常見的廣告 UI 用途？
- 您目前使用哪種 UI 架構顯示廣告 UI？您預期在整合 UI 程式庫與這些架構時遇到哪些問題？
- 將可捲動的廣告 UI 放在可捲動的發布者容器中，對您而言是常見用途嗎？在這個情況下，廣告 UI 和容器的捲動方向為何？當使用者開始捲動廣告 UI 時，您預期會發生哪些行為？