SDK 執行階段 API:整合指南

詳閱 Android 版 Privacy Sandbox 說明文件時,請利用「開發人員預覽版」或「Beta 版」按鈕選取您要使用的計畫版本,因為兩者的操作說明可能不盡相同。


為協助您規劃整合作業,本指南可讓您全面瞭解整合程序,其中可能包含尚未在 Privacy Sandbox 當前 Android 開發人員預覽階段中實作的功能。在這類情況下,我們會提供時間軸指引。

下方圖表顯示了 SDK 執行階段整合作業的更新開發工作流程。同一欄中列出的部分可以同時處理;例如,可以在設定合作夥伴參與度的同時設定測試環境。

SDK 執行階段整合工作流程的圖表。
SDK 執行階段整合的工作流程。

事前準備和設定

完成這項前置作業部分可確保您對 SDK 執行階段有充分的瞭解,並在廣告技術生態系統中使用這個 API 時取得有意義的結果。

熟悉 API

開始閱讀設計提案,熟悉 SDK 執行階段、其功能和限制。

詳閱開發人員指南,瞭解如何整合用途所需的程式碼和 API 呼叫。

針對說明文件提交任何意見回饋,特別是對沒有定論的問題提供意見回饋。

歡迎註冊,以接收有關 Android 版 Privacy Sandbox 的最新消息。這有助於隨時掌握日後版本推出的新功能。

設定並測試範例應用程式

準備好整合時,請按照這裡的操作說明,在 Android Studio 中下載最新的開發人員預覽版。本指南需要使用最新的 Android Studio Canary 版本。您可以同時執行這個版本的 Android Studio 與目前使用的其他版本,因此如果無法達成這項要求,請告訴我們

範例應用程式中的程式碼建立分支版本並加以執行,熟悉如何在裝置或模擬器中安裝名為"example-sdk"的 RE SDK 和名為「client-app」的用戶端應用程式,確保能載入範例廣告。

配合 SDK 執行階段來調整現有的 SDK

本節的目標是要透過在已啟用執行階段的 SDK (RE SDK) 中,從現有 SDK 實作功能 (例如顯示橫幅廣告),以及設定應用程式和 RE SDK 之間的通訊。

  • 建立或更新 sdk-example 和 sdk-implementation,以便實作 RE SDK 中的功能。

  • 在架構方面,請考慮將 RE SDK 新增為現有 SDK 的依附元件,作為包裝函式。這樣一來,用戶端應用程式就能繼續直接呼叫現有的 SDK 或包裝函式。包裝函式 SDK 可根據下述各種不同的策略,轉送 API 呼叫。

SDK 執行階段整合後的系統架構圖。
整合 SDK 執行階段後的系統架構。

如果是需要自訂資料的用途 (例如呼叫 PPAPI),則必須使用 IPC 建立 API 定義。使用 Android 的 IBinder 和 AIDL 建立通訊協定,用於將任何必要資訊或動作必要的資訊傳送至啟用執行階段的 SDK。詳情請參閱 SDK 執行階段開發人員指南中的這裡

將流量轉送至可支援執行階段的 SDK

API 呼叫的轉送策略

根據您的用途,建議透過現有的 SDK 和 RE SDK 程式碼路徑轉送 SDK 呼叫。這可協助您在初始推出期間實作 A/B 測試。為簡化應用程式整合作業,本指南會考慮應用程式取決於 RE SDK,並視情況委派給現有的 SDK。請考慮以下策略:

將一定比例的 SDK 呼叫轉送至 RE SDK

只將特定百分比的 SDK 呼叫轉送至 RE SDK。將其餘部分轉送至現有的 SDK 程式碼路徑。舉例來說,如果您需要滿足 SDK 請求 (例如顯示橫幅廣告) 的情況,請考慮採用這項策略。

  • 修改現有的 SDK,將一定比例的請求轉送至 RE SDK。舉例來說,您可以使用以 Firebase 遠端設定為基礎的伺服器動態設定旗標,以動態方式控制改移條件。
  • 基本上,這個 API 是現有 SDK 唯一需要與應用程式互動的介面,而且負責將 SDK 要求轉送至新的 RE SDK。
  • 您的程式碼只能重新導向可由 RE SDK 處理的要求。舉例來說,請確認 SDK 執行階段是否支援此廣告格式。
  • 請按照這些操作說明更新 SDK 程式碼,與 RE SDK 互動。

轉送邏輯的虛擬程式碼:

void showAd(AdRequest request) {
  if (request.isBannerAd() && enableRuntimeSdkDiversion() == true) {
    // Call showAd() from the RE SDK
  } else {
    // Call showAd() using the existing SDK code path
  }
}

將所有 SDK 呼叫轉送至現有 SDK 和 RE SDK

在支援的裝置上,將所有 SDK 呼叫轉送至現有 SDK 程式碼路徑和 RE SDK 程式碼路徑。當您需要將現有程式碼路徑和新程式碼路徑以便比較時,請考慮採用此策略。例如比較轉換報表結果。

  • 修改程式碼,將所有 SDK 呼叫轉送至現有 SDK 程式碼路徑和 RE SDK 程式碼路徑。請確認 SDK 執行階段是否支援此功能,以及是否成功載入 RE SDK。

轉送邏輯的虛擬程式碼:

void reportAttribution(AdRequest request) {
  if (request.isFeatureSupported() && isSdkLoaded() == true) {
    // Call RE SDK
  }

  // Call existing SDK code path
}

Beta 版封測:測試可支援執行階段的 SDK 發布作業

Google Play 為開發人員提供了廣告相關 SDK 的封閉式 Beta 版計畫,參加條件是註冊 Beta 版計畫,並已執行本機測試。如有意願參加,請按這裡申請加入。