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

中介服務是賣方廣告平台提供收益管理服務的常見方式。在中介服務工作流程中，中介服務 SDK (「中介服務」) 會叫用多個廣告聯播網 (「中介服務」或「中介服務」)，為指定廣告空間取得最佳廣告。在某些情況下，中介服務和叫用的廣告聯播網都需要 SDK 在裝置上互動。

本文將說明 SDK 執行階段中，中介服務工作流程的主要變更。涵蓋下列主題：

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

從 AGP 8.5 和下列版本的 SDK 執行階段 Jetpack 程式庫開始，即可在 SDK 執行階段中支援中介服務廣告：

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 互動，在裝置上提供中介服務。
  • 中介對象：由中介服務呼叫的廣告聯播網 SDK，負責提供及放送廣告。
  • 中介服務轉接程式：中介服務 SDK 使用的 SDK，可提供 API 介面轉譯功能，與各種中介服務 SDK 互通，通常由中介服務提供。這些可以是可感知執行階段或無法感知執行階段。

一般中介服務流程

如果 SDK 需要在 SDK 執行階段支援中介服務用途，您必須進行一些變更。本節將回顧中介服務流程的關鍵要素，以便解決中介服務和中介服務對象所需的變更。

我們說明的流程是簡化版裝置端中介服務，使用多個廣告聯播網 SDK，可做為討論基礎，瞭解如何進行必要變更，讓中介服務流程與 SDK 執行階段相容。

由於中介服務流程的實作方式各不相同，我們將著重於下列兩大流程：

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

初始化

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

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

廣告 UI 呈現

在先前步驟的最終請求後算繪廣告時，流程取決於廣告類型：

橫幅廣告 全螢幕廣告 原生廣告
中介服務 SDK 會建立廣告檢視區塊，包裝勝出中介服務的廣告檢視區塊。

這個 View 也可能會設定接聽程式，或自動重新整理廣告 (使用相同或不同的中介服務)。		 中介服務 SDK 會向中介服務對象請求全螢幕廣告，後者則會啟動活動。 發布商會使用中介服務 SDK 傳回的元件，管理檢視區塊的處理和膨脹。

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

中介服務在 SDK 執行階段中的運作方式，取決於中介服務是否支援執行階段。根據這項資訊，我們可能會遇到下列情況：

  • 中介服務和中介目標都在 SDK 執行階段中：RE 中介目標
  • 中介服務位於 SDK 執行階段，中介服務對象位於應用程式內：應用程式內中介服務對象

RE Mediatee

下圖為架構圖，概略說明中介服務的已啟用執行階段 (RE) 和可感知執行階段 (RA) SDK、RE 中介服務介面卡，以及中介服務對象的 RE SDK 之間的互動。

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

架構圖：大致說明中介服務的支援執行階段 (RE) 和支援執行階段 (RA) SDK、RE 中介服務轉接程式，以及中介服務對象的 RE SDK 之間的互動。
圖 1. 中介服務和中介服務對象都是 RE SDK。

初始化

考量啟用執行階段的仲介服務和仲介對象的初始化、探索和通訊時，流程會遵循下列步驟：

  1. 應用程式 (或 RA SDK) 會使用 SdkSandboxManager#loadSdk 載入並初始化中介服務 SDK。
  2. 中介服務 SDK 初始化時，會使用 SdkSandboxController#loadSdk 在 SDK 執行階段載入並初始化所有必要的中介服務。
  3. RE SDK 可以呼叫 SdkSandboxController#getSandboxedSdks，探索執行階段中載入的所有 SDK。
RE - RE 中介服務循序圖，顯示先前所述的流程。
圖 2. Flow to initialise an RE mediatee.

廣告 UI 呈現

以下章節說明如何從中介服務載入橫幅和全螢幕廣告。

RE Mediatee 橫幅廣告

如果應用程式要求載入橫幅廣告，完成顯示的流程如下：

  1. 中介服務會為這個廣告選取勝出的中介服務。
  2. 中介方會從中介對象取得 SandboxedUiAdapter。
  3. 中介服務會將 UiAdapter 轉送至應用程式。
在 RE-RE 中介服務中完成算繪橫幅廣告的流程。
圖 3. 流程：完成從 RE 中介服務合作夥伴算繪橫幅廣告。

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

重疊廣告轉為橫幅廣告

中介服務如要在廣告中加入疊加層，必須按照下列方式修改流程：

  1. 中介服務會使用疊加層和 SandboxedSdkView 建立版面配置。
  2. 中介服務會為這個廣告選取勝出的中介服務。
  3. 中介服務會從中介目標取得 SandboxedUiAdapter。
  4. 中介器會將中介對象的 UiAdapter 設為 SandboxedSdkView。
  5. 中介服務會將填入的檢視區塊提供給應用程式。
將檢視區塊疊加在從 RE 中介服務取得的橫幅廣告上。
將檢視區塊疊加在從 RE Mediatee 取得的橫幅廣告上。
RE Mediatee 全螢幕廣告

如果應用程式要求載入全螢幕廣告，系統會按照下列步驟執行流程：

  1. 應用程式 (或 RA SDK) 會將 SdkActivityLauncher 傳遞給中介服務，要求載入廣告。
    1. 用戶端可以使用述詞限制活動的建立。
  2. 中介服務會為這個廣告選取勝出的中介服務。
  3. 中介服務會要求中介服務對象載入廣告，並傳遞應用程式的 SdkActivityLauncher。
  4. 受調解者會註冊活動處理常式，並取得已註冊活動的 ID 權杖。
  5. 受調解者會使用 SdkActivityLauncher 要求使用這個權杖啟動活動。
  6. 如果用戶端應用程式的述詞允許，SDK 執行階段會在專屬程序中啟動這項活動。
從 RE Mediatee 顯示中介服務全螢幕應用程式的流程。
圖 4. 流程圖：說明如何從 RE Mediatee 載入中介服務全螢幕廣告。

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

應用程式內中介服務

下圖為架構圖，概略說明中介服務的 RE 和 RA SDK、不瞭解 SDK 執行階段的中介服務介面卡，以及靜態連結至應用程式的受中介服務 SDK (同樣不瞭解執行階段) 之間的互動。

架構圖：大致說明中介服務的 RE 和 RA SDK、不瞭解 SDK 執行階段的中介服務轉接程式，以及靜態連結至應用程式 (也不瞭解執行階段) 的中介服務對象 SDK 之間的互動。
圖 5. 即使 mediatee 知道 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 轉送至應用程式。
從應用程式內中介服務完成橫幅廣告的算繪流程
圖 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. 應用程式內中介服務會忽略述詞。

參與討論及分享意見

Android 版 Privacy Sandbox 是一項持續進行的計畫，本文說明的是目前的設計。竭誠邀請您分享意見回饋，協助我們持續開發及提升功能。回報錯誤來提供意見回饋。