构建和使用支持运行时的 SDK

1
 Key concepts
2
 Set up your development environment
3
 Build an RE SDK
4
 Consume the RE SDK
5
 Testing, and building for distribution

使用支持运行时的 SDK

本部分介绍客户端如何与声明的已启用运行时交互 (RE) SDK API。

在本指南中，我们会引用您现有的 SDK 模块（或运行时感知型 SDK） SDK）作为客户端运行。

如果您希望将支持运行时的 SDK 直接嵌入到您的应用中，应用模块 是客户端

加载支持运行时的 SDK

对于运行时感知型 SDK 或客户端应用，您首先要做的是加载 支持运行时的 SDK。

SdkSandboxManager 类可协助加载支持运行时的 SDK，并返回 IBinder 类 运行时感知型 SDK 可以绑定到 支持运行时的 SDK。

您需要确保每个支持运行时的 SDK 仅加载一次， 系统将返回异常

shim 生成工具会生成辅助类，用于转换 IBinder SdkSandboxManager返回声明的 SDK API 接口。

这些工具使用带有 @PrivacySandboxService 注解的接口生成 一个 *Factory 类。

此类包含一个静态 wrapTo* 函数，用于转换 IBinder 对象转换为支持运行时的 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
}

界面库使用情况

如果您想使用界面库展示广告，请确保您已将 androidx.privacysandbox.ui:ui-core和androidx.privacysandbox.ui:ui-client 添加到运行时感知 SDK 的 build.gradle 中的依赖项。

使用 SandboxedSdkView 加载横幅广告

androidx.privacysandbox.ui:ui-client 引入了一种ViewGroup SandboxedSdkView，用于托管由支持运行时的 SDK 创建的界面。

setAdapter() 会打开一个与支持运行时的 SDK 的会话， 接收广告视图和界面更改通知。当 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)
    }
}

当界面的会话状态发生变化时，运行时感知型 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。

开始活动

如需启动支持运行时的 SDK 拥有的 activity，请使用 createSdkActivityLauncher 扩展程序在运行时感知 SDK 中创建启动器。

然后，您可以将此启动器传递到支持运行时的 SDK，以便其根据需要启动 activity。

您可以使用谓词来控制是否启动 activity。 该谓词需要返回 true 值，系统才能允许 activity。

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)
}

传递给ActivityHolder SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) 实现 LifecycleOwner，使支持运行时的 SDK 能够访问 activity 的生命周期。

它还提供 getOnBackPressedDispatcher API，可用于 注册 getOnBackPressedCallback 实例以处理返回按钮行为 activity 中。


第 3 步：构建支持运行时的 SDK 第 5 步：测试和构建应用以进行分发