建構和使用支援執行階段的 SDK

使用支援執行階段的 SDK

本節說明用戶端如何與已宣告的執行階段啟用 (RE) SDK API 互動。

在本指南中，我們將現有的 SDK 模組 (或可感知執行階段的 SDK) 稱為用戶端。

如要將支援執行階段的 SDK 直接導入應用程式，應用程式模組就是用戶端。

載入支援執行階段的 SDK

在支援執行階段的 SDK 或用戶端應用程式中，您要做的第一件事是載入支援執行階段的 SDK。

SdkSandboxManager 類別可協助載入啟用執行階段的 SDK，並傳回 IBinder 類別，供可感知執行階段的 SDK 繫結至啟用執行階段 SDK 中宣告的介面。

請務必只載入每個支援執行階段的 SDK 一次，否則 SDK 管理工具會傳回例外狀況。

墊片生成工具會產生輔助類別，將 SdkSandboxManager 傳回的 IBinder 介面轉換回宣告的 SDK API 介面。

工具會使用以 @PrivacySandboxService 註解的介面，產生 *Factory 類別。

這個類別包含靜態 wrapTo* 函式，可將 IBinder 物件轉換為已啟用執行階段的 SDK 介面例項。

支援執行階段的 SDK 可以使用這個介面與支援執行階段的 SDK 通訊，並叫用您在上一個步驟中宣告的 SDK API。

// Name of the SDK to be loaded, defined in your ASB module
private const val SDK_NAME = "com.example.sdk"

try {
    // SdkSandboxManagerCompat is used to communicate with the sandbox and load SDKs with backward compatibility.
    val sandboxManagerCompat = SdkSandboxManagerCompat.from(context)
    val sandboxedSdk = sandboxManagerCompat.loadSdk(SDK_NAME, Bundle.EMPTY)
    val mySdk = MySdkFactory.wrapToMySdk(sandboxedSdk.getInterface()!!)
} catch (e: LoadSdkCompatException) {
    Log.e(TAG, "Failed to load SDK, error code: ${e.loadSdkErrorCode}", e)
    return null
}

使用 UI 程式庫

如要使用 UI 程式庫顯示廣告，請務必在支援執行階段的 SDK 的 build.gradle 中，將 androidx.privacysandbox.ui:ui-core 和 androidx.privacysandbox.ui:ui-client 新增至依附元件。

使用 SandboxedSdkView 載入橫幅廣告

androidx.privacysandbox.ui:ui-client 導入新的 ViewGroup，稱為SandboxedSdkView，用於代管啟用執行階段的 SDK 所建立的 UI。

setAdapter() 會開啟與啟用執行階段的 SDK 的工作階段，以接收廣告檢視畫面和 UI 變更通知。SDK 開啟工作階段時，系統會顯示廣告。

整合方式如下：

class BannerAd(context: Context, attrs: AttributeSet) : LinearLayout(context, attrs) {
    suspend fun loadAd() {
        // mySdk is the previously loaded SDK in the SDK Runtime.
        val bannerAd = mySdk.loadAd()
        val sandboxedSdkView = SandboxedSdkView(context)
        addViewToLayout(sandboxedSdkView)

        // This renders the ad.
        sandboxedSdkView.setAdapter(bannerAd)
        return
    }
    private fun addViewToLayout(view: View) {
        view.layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
        super.addView(view)
    }
}

當 UI 呈現的會期狀態變更時，執行階段感知 SDK 也會收到通知。步驟如下：

1. 建立 SessionStateChangeListener() 類別來處理不同情境：

   private class SessionStateChangeListener() : SandboxedSdkUiSessionStateChangedListener {
       override fun onStateChanged(state: SandboxedSdkUiSessionState) {
           if (state is SandboxedSdkUiSessionState.Error) {
           // Some error has occurred while opening the session. Handle
           // accordingly.
           Log.e(TAG, state.throwable.message!!);
           } else if (state is SandboxedSdkUiSessionState.Loading) {
               // The session is attempting to be opened.
           } else if (state is SandboxedSdkUiSessionState.Active) {
               // The session is open and the UI presentation was successful.
           } else if (state is SandboxedSdkUiSessionState.Idle) {
               // There is no open session.
           }
       }
   }
   

2. 在您先前例項化的 SandboxedSdkView 中新增狀態變更監聽器。附加至檢視區塊後，系統會立即呼叫事件監聽器，並提供目前狀態。

注意事項：

• 如果工作階段尚未完成開啟，但支援執行階段的 SDK 呼叫了 SandboxedSdkView 方法，系統會在工作階段完成開啟後套用所有效果。
  • 例如 SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) 等方法
• 系統不支援呼叫可從 SandboxedSdkView 新增或移除檢視區塊的方法 (例如 addView()、removeView()、removeViewAt() 等)，否則會擲回 UnsupportedOperationException。
  • 只能使用 setAdapter() 顯示廣告。
• SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) 切換 Z 排序，這會影響使用者互動產生的 MotionEvents 是否傳送至支援執行階段的 SDK 或支援執行階段的 SDK。
  • 如果設為 false，系統會將 MotionEvents 傳送至支援執行階段的 SDK，否則會傳送至已啟用執行階段的 SDK。進一步瞭解如何使用 UI Presentation API 進行 Z 排序。

開始活動

如要啟動執行階段支援的 SDK 所擁有的活動，請使用 createSdkActivityLauncher 擴充功能，在執行階段感知 SDK 中建立啟動器。

接著，您可以將這個啟動器傳遞至支援執行階段的 SDK，讓 SDK 視需要啟動活動。

您可以使用述詞控制是否要啟動活動。 如要允許活動，述詞必須傳回 true 值。

val launchSdkActivityPredicate = {
    // Boolean which has to be true to launch the activities
    }
val launcher = baseActivity.createSdkActivityLauncher(launchSdkActivityPredicate)
fullscreenService.showActivity(launcher)

在啟用執行階段的 SDK 中，註冊 SdkSandboxActivityHandlerCompat，並提供給 SdkActivityLauncher.LaunchSdkActivity(IBinder)。

fun showActivity(activityLauncher: SdkActivityLauncher) {
    val handler = object : SdkSandboxActivityHandlerCompat {
        override fun onActivityCreated(activityHolder: ActivityHolder) {
            activityHolder.getActivity().setContentView(contentView)
        }
    }

    val token = controller.registerSdkSandboxActivityHandler(handler)
    activityLauncher.launchSdkActivity(token)
}

傳遞至 SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) 的 ActivityHolder 會實作 LifecycleOwner，讓支援執行階段的 SDK 存取活動的生命週期。

此外，這個 API 也提供 getOnBackPressedDispatcher API，可用於註冊 getOnBackPressedCallback 執行個體，以處理活動中的返回按鈕行為。

arrow_back_ios步驟 3：建構支援執行階段的 SDK 步驟 5：測試及建構發布版本arrow_forward_ios