SDK 執行階段中的中介服務支援

中介服務是賣方廣告平台提供收益管理的常見做法。在中介服務工作流程中，中介服務 SDK (「中介者」) 會叫用多個廣告聯播網 (「中介者」或「中介者」)，以便取得指定版位最合適的廣告。在某些情況下，中介服務器和其叫用的廣告聯播網都需要在裝置上安裝 SDK 並進行互動。

本文概述 SDK 執行階段中中介服務工作流程的重大變更。涵蓋以下主題：

• 先前中介服務流程與目前 SDK 執行階段中介服務支援功能的差異
• 在 SDK 執行階段中設定中介服務工作流程的動作，以及轉換的不同階段
• 如何處理並非所有 SDK 都已遷移至 Runtime 的情況指南

AGP 8.5 和下列 SDK 執行階段 Jetpack 程式庫版本支援中介廣告：

Androidx 程式庫	版本
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

詞彙解釋

下列關鍵字詞可協助您瞭解 SDK 執行階段中的中介服務：

• 支援執行階段的 SDK (RE SDK)：這種 SDK 可在 SDK 執行階段環境中執行，並透過程序間通訊 (IPC) 與應用程式通訊。
• 支援執行階段的 SDK (RA SDK)：非支援執行階段的 SDK，會以靜態方式連結至應用程式，可能包含現有的 SDK 程式碼，以及用於呼叫支援執行階段的 SDK 的新程式碼。
• 應用程式內 SDK：與應用程式靜態連結的 SDK，不會偵測 SDK 執行階段。這可能是尚未改用 SDK 執行階段的廣告聯播網，或是發布商的自訂轉接器。
• 中介服務：廣告中介服務 SDK，可透過與其他廣告聯播網 SDK 互動，在裝置上提供中介服務。
• Mediatee：Mediator 呼叫的廣告聯播網 SDK，用於提供及顯示廣告。
• 中介服務轉接程式：Mediator SDK 使用的 SDK，可提供 API 介面轉譯功能，與各種中介服務 SDK 互通，通常由中介服務提供。這些可以是執行階段感知或執行階段不感知。

一般中介服務流程

如果您的 SDK 需要在 SDK 執行階段中支援中介服務用途，就必須實作一些變更。本節將回顧中介服務流程的重要元素，以便我們處理中介服務供應商和中介服務對象所需的變更。

我們所述的流程是使用多個廣告聯播網 SDK 的簡化版裝置端中介服務，可用於討論讓中介服務歷程與 SDK 執行階段相容所需的變更。

由於中介服務流程的實作方式各有不同，我們將重點放在以下兩個主要流程：

• 初始化 (包括探索廣告聯播網和通訊)
• 廣告使用者介面 (UI) 呈現方式

初始化

以下是標準初始化、廣告聯播網探索和通訊流程：

1. 用戶端應用程式啟動中介軟體
2. 中介服務會探索並初始化相關的媒介服務和轉接程式
3. 中介服務會使用轉接程式與每個媒介對象進行通訊
4. 用戶端應用程式要求中介服務載入廣告
5. 用戶端應用程式要求中介服務顯示這則廣告

注意： 這個流程假設用戶端應用程式會依附中介服務 SDK、中介服務 SDK 和中介服務轉接程式，並使用這些元件建構應用程式。

廣告 UI 呈現

在前一個步驟中完成最終請求後，如果要轉譯廣告，流程取決於廣告類型：

橫幅廣告	全螢幕廣告	原生廣告
中介服務 SDK 會建立廣告檢視畫面，用來包裝獲勝中介服務的廣告檢視畫面。 此外，它也可能會為這個 View 設定事件監聽器，或自動重新載入廣告 (使用相同或不同的媒介代理商)。	中介服務器 SDK 會向中介服務請求全螢幕廣告，而中介服務會啟動活動。	發布商會使用仲介器 SDK 傳回的元件，管理檢視區塊處理和充氣作業。

SDK 執行階段中的中介服務流程

中介服務在 SDK 執行階段中的運作方式會因中介對象是否支援執行階段而有所不同。因此，我們可以採用下列做法：

• 中介服務和媒介服務皆位於 SDK 執行階段：RE 媒介服務
• 中介服務位於 SDK 執行階段，而中介服務對象位於應用程式中：應用程式中介服務對象

RE Mediatee

下圖為架構圖，概略說明中介服務的執行階段支援 (RE) 和執行階段感知 (RA) SDK、RE 中介服務轉接器，以及中介服務的 RE SDK 之間的互動情形。

中介服務轉接程式必須與其所連結的中介服務處於相同程序，因此也必須遷移至 SDK 執行階段。

**圖 1.** 中介服務器和中介服務接收器都是 RE SDK。

初始化

在考量初始化、探索和通訊時，不論是啟用執行階段的仲介者或媒介，流程都會遵循以下步驟：

1. 應用程式 (或 RA SDK) 會使用 SdkSandboxManager#loadSdk 載入並初始化中介軟體 SDK。
2. 在初始化期間，中介 SDK 會使用 SdkSandboxController#loadSdk 載入並初始化 SDK 執行階段中所有必要的中介。
3. RE SDK 可以呼叫 SdkSandboxController#getSandboxedSdks，在執行階段中探索所有已載入的 SDK。

**圖 2.** 用於初始化 RE 中介服務的流程。

注意： 請使用 *Compat Runtime Manager 和 Controller 類別，確保啟用執行階段的 SDK 具備回溯相容性。

廣告 UI 呈現

以下章節將說明如何透過 RE 媒體方載入橫幅廣告和全螢幕廣告。

RE Mediatee 橫幅廣告

在應用程式要求載入橫幅廣告的情況下，完成算繪的流程如下：

1. 仲介會為這則廣告選出勝出的媒介。
2. 中介者會從中介對象取得 SandboxedUiAdapter。
3. 中介者會將 UiAdapter 轉送至應用程式。

**圖 3.** 流程，用於從 RE 中介服務完成轉譯橫幅廣告。

進一步瞭解 SandboxedUiAdapter 和 SDK 執行階段 UI 程式庫的用法。

橫幅廣告重疊

如果中介服務供應商想在廣告中加入疊加層，就必須修改流程，如下所示：

1. 中介者會使用疊加層和 SandboxedSdkView 建立版面配置。
2. 仲介會為這則廣告選出勝出的媒介。
3. 中介者會從中介對象取得 SandboxedUiAdapter。
4. 中介者會將媒介的 UiAdapter 設為 SandboxedSdkView。
5. 仲介會將填入資料的檢視畫面提供給應用程式。

流程，用於在從 RE Mediatee 取得的橫幅廣告上方重疊檢視畫面。

RE Mediatee 全螢幕廣告

在應用程式要求載入全螢幕廣告時，流程會按照以下步驟進行：

1. 應用程式 (或 RA SDK) 會將 SdkActivityLauncher 傳遞至中介服務，並附上載入廣告的要求。
   1. 用戶端可以使用謂詞限制活動建立作業。
2. 仲介會為這則廣告選出勝出的媒介。
3. 中介服務會要求中介服務對象載入廣告，並從應用程式傳遞 SdkActivityLauncher。
4. mediatee 會註冊活動處理常式，並取得已註冊活動的 ID 權杖。
5. 媒介使用 SdkActivityLauncher 要求使用此權杖啟動活動。
6. 如果用戶端應用程式的述詞允許，SDK 執行階段就會在專屬程序中啟動這項活動。

**圖 4.** 流程圖：說明如何從 RE Mediatee 載入經仲介的全螢幕廣告。

注意： Mediate 可使用註冊活動處理常式時使用的 ActivityHolder，取得所有活動生命週期事件。

進一步瞭解 SDK 執行階段中 Activity 對全螢幕廣告的支援情形。

應用程式內 Mediatee

下圖為架構圖，概略說明中介服務的 RE 和 RA SDK 互動情形、不瞭解 SDK 執行階段的中介服務轉接程式，以及與應用程式靜態連結的媒介 SDK (也未瞭解執行階段)。

**圖 5.** 即使媒介項知道 RE SDK，也會以靜態方式連結至應用程式。

初始化

由於在中介器與應用程式之間的連結為靜態連結，且尚未遷移至 SDK 執行階段，因此中介器的支援執行階段 SDK 應具備註冊程序。

您應使用中介服務的 API 存取這項註冊作業，但實作細節則由各中介服務自行決定。我們將此 API 稱為 MediationSandboxedSdk#registerInAppMediatee。

在考量 RE 中介服務器 SDK 和應用程式內中介服務器 SDK 的初始化、探索和通訊作業時，流程會遵循下列步驟：

1. 應用程式會載入並初始化中介服務的執行階段感知 SDK。
2. 中介服務的 RA SDK：
   1. 使用 SdkSandboxManager#loadSdk 初始化中介服務的 RE SDK。
   2. 初始化所有應用程式內媒介 SDK。
   3. 使用 RE SDK 提供的 API (MediationSandboxedSdk#registerInAppMediate) 來探索及註冊應用程式內的媒介 SDK。

除了註冊所有應用程式內媒介 SDK 之外，仲介的 RE SDK 還可使用 SdkSandboxController#getSandboxedSdks 探索 SDK 執行階段中載入的所有 SDK。

**圖 6.** 請注意，我們會使用建議的中介服務 API 註冊應用程式內中介服務的參照。

廣告 UI 呈現

以下章節將說明如何透過應用程式內媒體供應器載入橫幅廣告和全螢幕廣告。

應用程式內中介橫幅廣告

在應用程式要求載入橫幅廣告的情況下，完成算繪的流程如下：

1. 中介服務的執行階段感知 SDK 會將應用程式的請求轉送至支援執行階段的 SDK。
2. 中介服務器的 RE SDK 會選取相關的中介服務器。
3. 中介服務的 RE SDK 會擷取對中介服務的參照，並要求透過 RA SDK 載入廣告。
4. RA SDK 會從應用程式內的媒合對象取得 View。
5. RA SDK 會為收到的 View 建立 SandboxedUiAdapter。
6. RA SDK 會將 UiAdapter 轉送至 RE SDK。
7. RE SDK 會將 UiAdapter 轉送至應用程式。

注意： 由於此 SandboxedUiAdapter 是從應用程式程序接收，因此我們不建議在這個 View 中加入疊加層，因為這可能會導致延遲、效能和行為問題。

**圖 7.** 請注意，當中介服務從應用程式內的中介對象取得 V1 時，不應在 V1 上疊加檢視畫面。

應用程式內中介全螢幕廣告

在應用程式要求載入全螢幕廣告時，流程會按照以下步驟進行：

1. 應用程式會將 SdkActivityLauncher 傳送至中介服務器的 RA SDK，並附上載入廣告的要求。
   1. 用戶端可以使用謂詞限制活動建立作業。
2. 中介服務的 RA SDK 會將應用程式的請求轉送至 RE SDK。
3. 中介服務的 RE SDK：
   1. 選取相關的媒介。
   2. 擷取對應用程式內中介服務的參照。
   3. 要求透過 RA SDK 載入廣告。
4. RA SDK 會要求媒合對象載入廣告。
5. 媒介會直接啟動活動。應用程式的判定式不會生效。

**圖 8.** 應用程式內中介服務會忽略該判定式。

注意： 與活動相關的所有事件都會提供給中介服務，就像在 SDK 執行階段之前一樣。

互動並分享意見回饋

Android 版 Privacy Sandbox 是一個持續進行中的專案，本文件反映其目前的設計。我們會持續開發及改善相關功能，因此非常重視您的意見回饋。回報錯誤以提供意見回饋。