本頁面由 Cloud Translation API 翻譯而成。

privacysandbox ui

TODO

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2025 年 12 月 17 日	-	-	-	1.0.0-alpha17

宣告依附元件

如要新增 privacysandbox-ui 的依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    // Use to implement privacysandbox ui-client
    implementation "androidx.privacysandbox.ui:ui-client:1.0.0-alpha17"

    // Use to implement privacysandbox ui-core
    implementation "androidx.privacysandbox.ui:ui-core:1.0.0-alpha17"

    // Use to implement privacysandbox ui-core
    implementation "androidx.privacysandbox.ui:ui-provider:1.0.0-alpha17"
}

Kotlin

dependencies {
    // Use to implement privacysandbox ui-client
    implementation("androidx.privacysandbox.ui:ui-client:1.0.0-alpha17")

    // Use to implement privacysandbox ui-core
    implementation("androidx.privacysandbox.ui:ui-core:1.0.0-alpha17")

    // Use to implement privacysandbox ui-provider
    implementation("androidx.privacysandbox.ui:ui-provider:1.0.0-alpha17")

    
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.0 版本

1.0.0-alpha17 版本

2025 年 12 月 17 日

發布 androidx.privacysandbox.ui:ui-*:1.0.0-alpha17。1.0.0-alpha17 版包含這些修訂項目。

這個程式庫已淘汰，不會再收到任何更新。

API 變更 - 淘汰 privacysandbox.ui API (I858d5、b/452878636) - minSdk 從 API 21 改為 API 23 (Ifa120、b/380448311) - 將實驗性 SandboxedSdkUi 與非實驗性 SandboxedSdkUi 解除連結。(Ie9154、b/430118542) - SdkSandboxControllerCompat 遷移至 sdkruntime-provider (Id99fb、b/426122358) - 用戶端應用程式無法使用 SandboxedSdkView 或 SandboxedSdkUi 變更相對於用戶端視窗的供應商 UI z 級別。(I87e9f、b/413659157)

修正錯誤

將預設 minSdk 從 API 21 移至 API 23 (Ibdfca、b/380448311、b/435705964、b/435705223)
在 SharedUiContainer 工作階段管理中新增 PoolingContainer 支援：如果容器位於 PoolingContainer 內，系統不會關閉共用 UI 工作階段。(Iabe16、b/352500350)

1.0.0-alpha16 版本

2025 年 5 月 20 日

發布 androidx.privacysandbox.ui:ui-*:1.0.0-alpha16。1.0.0-alpha16 版包含這些修訂項目。

新功能

新增邏輯來測量 SandboxedSdkView 上的障礙物，如果相關聯的 SessionObserverFactory.signalOptions 中包含 SandboxedUiAdapterSignalOptions.OBSTRUCTIONS，系統就會在 SessionObserver.onUiContainerChanged() 中傳送這項資訊。系統會根據視野本身回報障礙物。

API 變更

將 SandboxedSdkUi 從 ui-client 移至新的 ui-client-compose 程式庫。
新增邏輯，用於測量 UI 容器上的障礙物。(I34bea)

修正錯誤

修正 SandboxedSdkView.setAlpha()，現在會更新內容檢視區塊的 Alpha 值。

1.0.0-alpha15 版本

2025 年 3 月 26 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha15、androidx.privacysandbox.ui:ui-core:1.0.0-alpha15 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha15。1.0.0-alpha15 版包含這些修訂項目。

新功能

將 SandboxedSdkView 和 SandboxedSdkUi 的預設 Z 順序設為「下方」，表示供應商的介面現在位於用戶端視窗下方。新增支援功能，讓 UI 提供者在用戶端視窗收到 MotionEvents 後，也能在這個模式下接收 MotionEvents。
在 SessionObserverFactory 介面中新增 signalOptions 欄位。這可用於定義一組字串選項，判斷要為相關聯的 SessionObserver 收集哪些信號。初始信號集定義於 SandboxedUiAdapterSignalOptions。如未設定任何信號選項，系統只會呼叫 SessionObserver.onSessionOpened() 和 SessionObserver.onSessionClosed()。

API 變更

SandboxedUiAdapter.openSession() 中的「SessionConstants」已重新命名為「SessionData」。

已知問題

在 SDK 執行階段載入 SDK 時，如果 SandboxedSdkView 或 SandboxedSdkUi 的 Z 順序為「上方」，手勢會由供應商視窗專屬接收，不再轉移至用戶端視窗。

1.0.0-alpha14 版本

2025 年 2 月 26 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha14、androidx.privacysandbox.ui:ui-core:1.0.0-alpha14 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha14。1.0.0-alpha14 版包含這些修訂項目。

新功能

您現在可以建立「共用 UI」，也就是可同時包含用戶端和供應商擁有的元素的 UI。共用 UI 可使用 SharedUiContainer (擴充 ViewGroup) 代管。新版 API 採用與 SandboxedSdkView 和 SandboxedUiAdapter 類似的工作階段管理概念。
這個版本新增的所有 API 都位於 SharedUiPresentationApi @RequiresOptIn 標記後方。

API 變更

已將工作階段管理和資產註冊 API 新增至 SharedUiContainer。工作階段管理功能是使用同一版本中推出的 SharedUiAdapter 實作。(Ic60b0)
新增 SharedUiContainer，可代管用戶端和供應商擁有的 UI。並將所有子項檢視區塊放在左上角。(Ia7310)
新增對 SharedUiAdapter 的回溯相容性支援。(I56d7a)
新增 SharedUiAdapter，用於管理可代管用戶端和供應商擁有 UI 的 View 容器工作階段。工作階段管理邏輯與 SandboxedUiAdapter 類似。(I501f6)

修正錯誤

在呼叫 onVisibilityAggregated 時計算可視度。(I91c69)

已知問題

如果放在 PoolingContainer 內，SharedUiContainer 會在視窗卸離時關閉工作階段。

1.0.0-alpha13 版

2025 年 1 月 29 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha13、androidx.privacysandbox.ui:ui-core:1.0.0-alpha13 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha13。1.0.0-alpha13 版包含這些修訂項目。

新功能

新增名為 SandboxedSdkUi 的可組合物件，可用於在 Compose UI 中顯示遠端內容。這個物件會使用現有的 SandboxedSdkView 概念進行工作階段管理和事件監聽器。(I009cf)
變更 SandboxedUiAdapter.openSession 簽章，納入取代先前 windowInputToken 的新 SessionConstants 參數。這個參數用於傳遞 SandboxedUiAdapter.Session 生命週期內保持不變的值。(Ibc0df、I28435)

已知問題

捲動 SandboxedSdkUi 時，系統不會傳送 SessionObserver 事件。
SandboxedSdkUi 處於 Z 軸上方模式時，不會遭到父項檢視區塊裁剪。

API 變更

移除已淘汰的 SDKActivityLauncher 程式碼 (I49a4f)
新增 SessionObserverFactoryRegistry 介面，將觀察程式工廠註冊邏輯與 SandboxedUiAdapter 分開。(I245cc)

1.0.0-alpha12 版

2024 年 12 月 11 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha12、androidx.privacysandbox.ui:ui-core:1.0.0-alpha12 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha12。1.0.0-alpha12 版包含這些修訂項目。

新功能

以 SandboxedSdkViewEventListener 取代 StateChangedListener。這個事件監聽器可用於監聽顯示的 UI、工作階段關閉和工作階段錯誤事件。

API 變更

新增 SandboxedSdkViewEventListener，用於監聽 SandboxedSdkView 內的 UI 事件。這個版本也會移除 StateChangedListener。(Id71ea)

修正錯誤

已從 SandboxedSdkView 移除剪裁界線邏輯。如果 SandboxedSdkView 放置在可捲動的容器中，且尚未呼叫 orderProviderUiAboveClientUi(false) (直到修正基礎架構錯誤為止)，就會導致使用者體驗問題。(Id420d)
修正了使用 DelegatingSandboxedUiAdapter 時，遠端程序終止可能發生的 RemoteException 問題。

1.0.0-alpha11 版本

2024 年 11 月 13 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha11、androidx.privacysandbox.ui:ui-core:1.0.0-alpha11 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha11。1.0.0-alpha11 版包含這些修訂項目。

新功能

推出實驗性 API DelegatingSandboxedUiAdapter，可擴充 SandboxedUiAdapter，並用於在不同 SandboxedUiAdapters 之間委派。在 SandboxedSdkView 等用戶端容器上設定這個轉接程式時，委派轉接程式可以使用 updateDelegate 變更委派轉接程式。這會關閉現有工作階段，並為新代表建立新的 SandboxedUiAdapter.Session。這樣一來，代表就能順利交接。(I5f1c5、I9e3e7)
改善對邊框間距的 SandboxedSdkView 支援。(Ic414f)

修正錯誤

修正可能在全域版面配置事件中發生的 NullPointerException。

1.0.0-alpha10 版本

2024 年 9 月 18 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha10、androidx.privacysandbox.ui:ui-core:1.0.0-alpha10 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha10。1.0.0-alpha10 版包含這些修訂項目。

新功能

更新工作階段開啟邏輯，只有在包含 SandboxedSdkView 的視窗可見時，才在 SandboxedSdkView 內開啟工作階段。
更新 SessionObserver 邏輯，在包含 SandboxedSdkView 的視窗顯示設定變更時傳送 onUiContainerChanged。

修正錯誤

視窗顯示設定變更時，叫用 onUiContainerChanged (I541cf)
移除手動列出新平台 API 存取權的步驟，因為使用 AGP 7.3 以上版本 (例如 R8 3.3 版) 的 R8 時，系統會透過 API 建模自動執行這項作業，而使用 AGP 8.1 以上版本 (例如 D8 8.1 版) 時，所有建構作業都會自動執行這項作業。如果用戶端未使用 AGP，建議更新至 D8 8.1 以上版本。詳情請參閱這篇文章。(If6b4c、b/345472586)

1.0.0-alpha09 版本

2024 年 6 月 26 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha09、androidx.privacysandbox.ui:ui-core:1.0.0-alpha09 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha09。1.0.0-alpha09 版包含這些修訂項目。

新功能

導入 AbstractSandboxedUiAdapter 和 AbstractSandboxedUiAdapter.AbstractSession 抽象類別，UI 提供者可使用這些類別，避免實作整個 SandboxedUiAdapter 或 Session 介面。建議 UI 提供者使用這些抽象類別。
新增 registerObserverFactory 邏輯，可將 SessionObserverFactory 附加至 SandboxedUiAdapter。將 SessionObserverFactory 附加至介面卡時，系統會為該介面卡建立的每個新 UI 工作階段建立 SessionObserver。建立的 SessionObserver 會在 UI 工作階段開啟時收到 onSessionOpened 回呼。當 Session 檢視區塊的 UI 呈現方式變更時，系統會呼叫 SessionObserver.onUiContainerChanged。onUiContainerChanged 會受到節流，最多每 200 毫秒呼叫一次。
新增 SandboxedSdkViewUiInfo，可從 SessionObserver.onUiContainerChanged 中傳送的 Bundle 建立。這個物件代表代管 UI 工作階段的 SandboxedSdkView UI 狀態。其中包含高度和寬度資訊、代表螢幕上可見檢視區塊幾何圖形的 Rect，以及代表檢視區塊不透明度的不透明度提示。

API 變更

在 SandboxedSdkViewUiInfo 中新增不透明度提示。(I093ac)
新增 SessionObserver.onUiContainerChanged 和 SandboxedSdkViewUiInfo。(Ie98bc)
新增 SessionObserver 介面和註冊邏輯。(I047dc)
新增 AbstractSandboxedUiAdapter 和 AbstractSession。(I3617a)

已知問題

如果 UI 提供者與用戶端應用程式位於相同程序，則容器捲動時不會傳送 SessionObserver.onUiContainerChanged。

1.0.0-alpha08 版本

2024 年 5 月 14 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha08、androidx.privacysandbox.ui:ui-core:1.0.0-alpha08 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha08。1.0.0-alpha08 版包含這些修訂項目。

新功能

開始支援在 PoolingContainer (例如 RecyclerView) 中使用 SandboxedSdkView。如果 SandboxedSdkView 的父項是 PoolingContainer，UI 工作階段的生命週期會與 PoolingContainer 的生命週期保持一致，確保工作階段在視窗卸離後仍可持續存在。

API 變更

已淘汰 Privacy Sandbox 活動 API。這些 API 現在位於專屬的 Activity 程式庫 androidx.privacysandbox.activity。(I68beb)

修正錯誤

修正在共用容器中顯示遠端內容時的轉譯錯誤。(I804df)
修正錯誤：在回溯相容模式下，ViewGroups 會導致轉譯問題。(I8de92)
如果 SandboxedSdkView 的其中一個父項是 PoolingContainer，請在 PoolingContainer 指出可以釋放資源時關閉 UI 工作階段，而不是在視窗卸離時關閉。(I2046b)

外部貢獻

GestureDetectorCompat 現已淘汰，因為 GestureDetector 可從 minSdk 取得。(Icc4cd)

1.0.0-alpha07 版本

2023 年 10 月 18 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha07、androidx.privacysandbox.ui:ui-core:1.0.0-alpha07 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha07。1.0.0-alpha07 版包含此連結所列的修訂項目。

新功能

新增程式庫的回溯相容性支援。在 API 33 以下版本，供應商的檢視區塊會在應用程式程序中以不同的類別載入器算繪。(If0b7a)
新增邏輯，允許在同一影格中提交主機和供應商容器的大小調整作業，避免 UI 發生明顯的卡頓情形。(Ic2cd9)

API 變更

程式庫的 MinSdk 已提升至 API 21。(I474b8)

1.0.0-alpha06 版本

2023 年 9 月 20 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha06、androidx.privacysandbox.ui:ui-core:1.0.0-alpha06 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha06。1.0.0-alpha06 版包含此連結所列的修訂項目。

新功能

新增邏輯，將 SandboxedSdkView 裁剪至「界限父項」View，以便在其中捲動。這可確保 SandboxedSdkView 的內容不會遮蔽其他檢視區塊，或根內容檢視區塊以外的任何 UI 元件。(I9ea94)

API 變更

將 SandboxedSdkView.setZOrderOnTopAndEnableUserInteraction 重新命名為 orderProviderUiAboveClientUi (Iecb7e)

修正錯誤

將正確的 Z 順序值傳送給主機。(Ib0ddf)
僅轉移垂直捲動/滑動的手勢焦點。(I0528c)

1.0.0-alpha05 版本

2023 年 8 月 9 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha05、androidx.privacysandbox.ui:ui-core:1.0.0-alpha05 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha05。查看 1.0.0-alpha05 版的修訂項。

新功能

新增邏輯，將觸控焦點轉移至主機，並在捲動和撥動手勢源自 SandboxedSdkView 時執行此操作。這樣一來，用戶可捲動的容器代管供應商 UI 就能正確回應捲動和甩動動作。

API 變更

已將 windowInputToken 參數新增至 SandboxedUiAdapter (Ief578)

修正錯誤

在第一次繪製後，將工作階段狀態設為「有效」(I36f3f)
修正 SandboxedSdkView 的版面配置問題。(I09cb8)
新增將觸控焦點轉移至主機的邏輯。(I33b54)
在 SandboxedUiAdapter 中新增 windowInputToken 參數。這是為了確保 SurfaceControlViewHost 的權杖與內嵌階層的主機正確建立關聯。(Ief578)
在主執行緒中執行 notifyResized。(I62440)
修正 Session.close() 流程中的異常終止問題。(I5392e)

1.0.0-alpha04 版本

2023 年 6 月 21 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha04、androidx.privacysandbox.ui:ui-core:1.0.0-alpha04 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha04。1.0.0-alpha04 版包含這些修訂項目。

新功能

介紹 SdkActivityLauncher。這個介面可讓支援執行階段的 SDK 啟動活動。(I5b3dc)

修正錯誤

修正 notifyZOrderChanged 競爭狀況。確保 UI 提供者會收到所有 Z 順序變更的通知。如果 SandboxedSdkView 的 Z 順序在呼叫 openSession 前變更，系統不會明確通知 UI 提供者。

1.0.0-alpha03 版本

2023 年 5 月 24 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha03、androidx.privacysandbox.ui:ui-core:1.0.0-alpha03 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha03。查看 1.0.0-alpha03 版的修訂項。

新功能

StateChangedListener 會通知應用程式 UI 工作階段的變更

API 變更

新增 StateChangedListener 以取代 ErrorConsumer (Icd5d3)

修正錯誤

修正 notifyZOrderChanged 競爭條件，確保 UI 提供者收到所有 Z 順序變更的通知

1.0.0-alpha02 版

2023 年 4 月 19 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha02、androidx.privacysandbox.ui:ui-core:1.0.0-alpha02 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha02。1.0.0-alpha02 版本包含以下修訂項目。

修正錯誤

Disabled flaking testChangingSandboxedSdkViewLayoutChangesChildLayout test

1.0.0-alpha01 版

2023 年 3 月 8 日

發布 androidx.privacysandbox.ui:ui-client:1.0.0-alpha01、androidx.privacysandbox.ui:ui-core:1.0.0-alpha01 和 androidx.privacysandbox.ui:ui-provider:1.0.0-alpha01。1.0.0-alpha01 版本包含這些修訂版本。

新功能

這些是新的 Jetpack 程式庫，應用程式和支援 Runtime 的 SDK (Privacy Sandbox) 可使用這些程式庫，讓應用程式 (用戶端) 代管 SDK (提供者) 提供的任何 UI。