Compila y usa un SDK habilitado para el entorno de ejecución

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

Consume el SDK habilitado para el entorno de ejecución

En esta sección, se describe cómo los clientes pueden interactuar con las APIs del SDK habilitado para el tiempo de ejecución (RE) declarado.

En el caso de esta guía, nos referimos a tu módulo del SDK existente (o SDK compatible con el tiempo de ejecución) como el cliente.

Si deseas integrar el SDK habilitado para el entorno de ejecución directamente en tu app, el módulo de la app es el cliente.

Carga el SDK habilitado para el entorno de ejecución

Lo primero que debes hacer en tu SDK o app cliente compatible con el tiempo de ejecución es cargar el SDK habilitado para el tiempo de ejecución.

La clase SdkSandboxManager ayuda a cargar los SDKs habilitados para el entorno de ejecución y devuelve una clase IBinder a la que el SDK compatible con el entorno de ejecución puede vincularse a la interfaz declarada en el SDK habilitado para el entorno de ejecución.

Debes asegurarte de cargar cada SDK habilitado para el entorno de ejecución solo una vez, o el administrador de SDK devolverá una excepción.

Las herramientas de generación de shim generan clases de ayuda para convertir la interfaz IBinder que devuelve SdkSandboxManager en la interfaz de la API del SDK declarada.

Las herramientas usan la interfaz anotada con @PrivacySandboxService para generar una clase *Factory.

Esta clase contiene una función wrapTo* estática que convierte un objeto IBinder en una instancia de la interfaz del SDK habilitado para el entorno de ejecución.

Tu SDK compatible con el entorno de ejecución puede comunicarse con el SDK habilitado para el entorno de ejecución a través de esta interfaz y, luego, invocar las APIs del SDK que declaraste en el paso anterior.

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

Uso de la biblioteca de IU

Si deseas usar la biblioteca de IU para mostrar anuncios, asegúrate de haber agregado androidx.privacysandbox.ui:ui-core y androidx.privacysandbox.ui:ui-client a las dependencias en el archivo build.gradle de tu SDK compatible con el entorno de ejecución.

Carga un anuncio de banner con SandboxedSdkView

androidx.privacysandbox.ui:ui-client presenta un nuevo ViewGroup llamado SandboxedSdkView para alojar la IU creada por un SDK habilitado para el entorno de ejecución.

setAdapter() abre una sesión con el SDK habilitado para el tiempo de ejecución para recibir la vista del anuncio y las notificaciones de los cambios en la IU. Cuando el SDK abre la sesión, se muestra el anuncio.

Esto se podría integrar de la siguiente manera:

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

Tu SDK compatible con el tiempo de ejecución también puede recibir notificaciones cuando cambia el estado de la sesión para la presentación de la IU. Para ello, sigue estos pasos:

  1. Crea una clase SessionStateChangeListener() para controlar las diferentes situaciones:

    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. Agrega un objeto de escucha de cambio de estado al SandboxedSdkView que creaste anteriormente. Se llama al objeto de escucha de inmediato con el estado actual en cuanto se adjunta a la vista.

Ten en cuenta lo siguiente:

  • Si el SDK compatible con el tiempo de ejecución llama a los métodos SandboxedSdkView cuando la sesión aún no terminó de abrirse, todos los efectos se aplicarán después de que la sesión termine de abrirse.
    • Métodos como SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • No se admite llamar a métodos que agregan o quitan una vista de SandboxedSdkView (como addView(), removeView(), removeViewAt(), etcétera), por lo que se arroja un UnsupportedOperationException.
    • Solo usa setAdapter() para mostrar el anuncio.
  • SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) activa o desactiva el orden Z, lo que afecta si los MotionEvents de la interacción del usuario se envían al SDK habilitado para el entorno de ejecución o al SDK compatible con el entorno de ejecución.

Iniciar actividades

Para iniciar actividades que pertenecen al SDK habilitado para el entorno de ejecución, usa la extensión createSdkActivityLauncher para crear un selector en el SDK compatible con el entorno de ejecución.

Luego, este objeto de inicio se puede pasar a tu SDK habilitado para el entorno de ejecución, lo que le permite iniciar actividades según sea necesario.

Puedes usar un predicado para controlar si se iniciará la actividad o no. El predicado debe devolver un valor true para que se permitan las actividades.

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

Dentro de tu SDK habilitado para el entorno de ejecución, registra SdkSandboxActivityHandlerCompat y proporciónalo a 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)
}

El ActivityHolder que se pasa a SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implementa LifecycleOwner, lo que le da a tu SDK habilitado para el entorno de ejecución acceso al ciclo de vida de la actividad.

También proporciona la API de getOnBackPressedDispatcher, que se puede usar para registrar instancias de getOnBackPressedCallback para controlar el comportamiento del botón Atrás dentro de la actividad.


Paso 3: Compila un SDK habilitado para el tiempo de ejecución Paso 5: Prueba y compila para la distribución