Créer et utiliser un SDK compatible avec l'environnement d'exécution

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

Utiliser le SDK compatible avec l'environnement d'exécution

Cette section décrit comment les clients peuvent interagir avec les API du SDK avec activation du runtime (RE, runtime-enabled).

Dans ce guide, nous appelons "client" votre module SDK existant (ou SDK compatible avec le runtime).

Si vous souhaitez intégrer directement le SDK compatible avec l'environnement d'exécution dans votre application, le module d'application est le client.

Charger le SDK compatible avec l'environnement d'exécution

La première chose à faire sur votre SDK ou application cliente compatible avec le runtime est de charger le SDK compatible avec le runtime.

La classe SdkSandboxManager permet de charger les SDK compatibles avec l'environnement d'exécution et renvoie une classe IBinder à laquelle le SDK compatible avec l'environnement d'exécution peut se lier à l'interface déclarée dans le SDK compatible avec l'environnement d'exécution.

Vous devez vous assurer de ne charger chaque SDK compatible avec l'environnement d'exécution qu'une seule fois, sinon le gestionnaire de SDK renverra une exception.

Les outils de génération de shims génèrent des classes d'assistance pour convertir l'interface IBinder renvoyée par SdkSandboxManager en interface d'API SDK déclarée.

Les outils utilisent l'interface annotée avec @PrivacySandboxService pour générer une classe *Factory.

Cette classe contient une fonction wrapTo* statique qui convertit un objet IBinder en instance de l'interface de votre SDK compatible avec l'environnement d'exécution.

Votre SDK compatible avec l'environnement d'exécution peut communiquer avec le SDK activé pour l'environnement d'exécution à l'aide de cette interface et appeler les API du SDK que vous avez déclarées à l'étape précédente.

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

Utilisation de la bibliothèque d'UI

Si vous souhaitez utiliser la bibliothèque d'UI pour afficher des annonces, assurez-vous d'avoir ajouté androidx.privacysandbox.ui:ui-core et androidx.privacysandbox.ui:ui-client aux dépendances dans le fichier build.gradle de votre SDK compatible avec le runtime.

Charger une bannière à l'aide de SandboxedSdkView

androidx.privacysandbox.ui:ui-client introduit un nouveau ViewGroup appelé SandboxedSdkView pour héberger l'UI créée par un SDK compatible avec l'environnement d'exécution.

setAdapter() ouvre une session avec le SDK compatible avec le runtime pour recevoir la vue d'annonce et les notifications de modifications de l'UI. Lorsque le SDK ouvre la session, l'annonce s'affiche.

Vous pouvez l'intégrer comme suit :

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

Votre SDK compatible avec l'exécution peut également recevoir une notification lorsque l'état de la session change pour la présentation de l'UI. Pour ce faire :

  1. Créez une classe SessionStateChangeListener() pour gérer les différents scénarios :

    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. Ajoutez un écouteur de changement d'état à l'SandboxedSdkView que vous avez instancié précédemment. L'écouteur est immédiatement appelé avec l'état actuel dès qu'il est associé à la vue.

Veuillez noter les points suivants :

  • Si le SDK compatible avec le temps d'exécution appelle les méthodes SandboxedSdkView alors que la session n'est pas encore ouverte, tous les effets seront appliqués une fois la session ouverte.
    • Méthodes telles que SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • L'appel de méthodes qui ajoutent ou suppriment une vue de SandboxedSdkView (telles que addView(), removeView(), removeViewAt(), etc.) n'est pas pris en charge et génère une UnsupportedOperationException.
    • Utilisez uniquement setAdapter() pour diffuser l'annonce.
  • SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) active ou désactive l'ordre Z, ce qui détermine si MotionEvents provenant de l'interaction de l'utilisateur est envoyé au SDK compatible avec l'environnement d'exécution ou au SDK compatible avec l'environnement d'exécution.

Démarrer des activités

Pour démarrer des activités appartenant au SDK compatible avec le runtime, utilisez l'extension createSdkActivityLauncher pour créer un lanceur dans le SDK compatible avec le runtime.

Ce lanceur peut ensuite être transmis à votre SDK compatible avec l'environnement d'exécution, ce qui lui permet de lancer des activités si nécessaire.

Vous pouvez utiliser un prédicat pour déterminer si l'activité sera lancée ou non. Le prédicat doit renvoyer une valeur true pour que les activités soient autorisées.

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

Dans votre SDK compatible avec l'environnement d'exécution, enregistrez SdkSandboxActivityHandlerCompat et fournissez-le à 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)
}

Le ActivityHolder transmis à SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implémente LifecycleOwner, ce qui donne à votre SDK compatible avec l'environnement d'exécution l'accès au cycle de vie de l'activité.

Il fournit également l'API getOnBackPressedDispatcher, qui peut être utilisée pour enregistrer des instances getOnBackPressedCallback afin de gérer le comportement du bouton "Retour" dans l'activité.


Étape 3 : Créez un SDK compatible avec le runtime Étape 5 : Testez et créez pour la distribution