Runtime-fähiges SDK erstellen und nutzen

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

Laufzeitfähiges SDK verwenden

In diesem Abschnitt wird beschrieben, wie Clients mit den deklarierten APIs für Runtime-fähige (RE) SDKs interagieren können.

In diesem Leitfaden bezeichnen wir Ihr vorhandenes SDK-Modul (oder das laufzeitfähige SDK) als Client.

Wenn Sie das laufzeitfähige SDK direkt in Ihre App einbinden möchten, ist das App-Modul der Client.

Laufzeitfähiges SDK laden

Als Erstes müssen Sie das laufzeitfähige SDK in Ihr laufzeitfähiges SDK oder Ihre Client-App laden.

Die Klasse SdkSandboxManager unterstützt das Laden von laufzeitfähigen SDKs und gibt eine IBinder-Klasse zurück, die an die im laufzeitfähigen SDK deklarierte Schnittstelle gebunden werden kann.

Sie müssen dafür sorgen, dass jedes SDK mit Laufzeitfunktion nur einmal geladen wird. Andernfalls gibt der SDK-Manager eine Ausnahme zurück.

Mit den Shim-Generierungstools werden Hilfsklassen generiert, um die von SdkSandboxManager zurückgegebene IBinder-Schnittstelle wieder in die deklarierte SDK-API-Schnittstelle zu konvertieren.

Die Tools verwenden die mit @PrivacySandboxService annotierte Schnittstelle, um eine *Factory-Klasse zu generieren.

Diese Klasse enthält eine statische wrapTo*-Funktion, die ein IBinder-Objekt in eine Instanz der Schnittstelle Ihres runtime-fähigen SDK konvertiert.

Ihr laufzeitfähiges SDK kann über diese Schnittstelle mit dem laufzeitaktivierten SDK kommunizieren und die SDK-APIs aufrufen, die Sie im vorherigen Schritt deklariert haben.

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

Verwendung der UI-Bibliothek

Wenn Sie die UI-Bibliothek verwenden möchten, um Anzeigen zu präsentieren, müssen Sie androidx.privacysandbox.ui:ui-core und androidx.privacysandbox.ui:ui-client den Abhängigkeiten in der build.gradle-Datei Ihres laufzeitfähigen SDK hinzufügen.

Banneranzeige mit SandboxedSdkView laden

In androidx.privacysandbox.ui:ui-client wird ein neues ViewGroup namens SandboxedSdkView eingeführt, um die Benutzeroberfläche zu hosten, die von einem laufzeitfähigen SDK erstellt wird.

setAdapter() öffnet eine Sitzung mit dem Laufzeit-fähigen SDK, um die Anzeigenansicht und Benachrichtigungen über Änderungen an der Benutzeroberfläche zu empfangen. Wenn das SDK die Sitzung öffnet, wird die Anzeige ausgeliefert.

Das könnte so aussehen:

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

Ihr laufzeitfähiges SDK kann auch benachrichtigt werden, wenn sich der Sitzungsstatus für die UI-Präsentation ändert. Gehen Sie dazu so vor:

  1. Erstellen Sie eine SessionStateChangeListener()-Klasse, um die verschiedenen Szenarien zu verarbeiten:

    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. Fügen Sie dem SandboxedSdkView, das Sie zuvor instanziiert haben, einen Listener für Statusänderungen hinzu. Der Listener wird sofort mit dem aktuellen Status aufgerufen, sobald er an die Ansicht angehängt wird.

Wichtige Hinweise:

  • Wenn das laufzeitfähige SDK SandboxedSdkView-Methoden aufruft, während die Sitzung noch nicht vollständig geöffnet wurde, werden alle Effekte angewendet, nachdem die Sitzung vollständig geöffnet wurde.
    • Methoden wie SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop)
  • Das Aufrufen von Methoden, die eine Ansicht aus SandboxedSdkView hinzufügen oder entfernen (z. B. addView(), removeView(), removeViewAt() usw.), wird nicht unterstützt und führt zu einer UnsupportedOperationException.
    • Verwenden Sie setAdapter() nur, um die Anzeige zu präsentieren.
  • Mit SandboxedSdkView.orderProviderUiAboveClientUi(providerUiOnTop) wird die Z-Reihenfolge umgeschaltet. Das wirkt sich darauf aus, ob MotionEvents aus Nutzerinteraktionen an das laufzeitfähige SDK oder das laufzeitkompatible SDK gesendet werden.

Aktivitäten starten

Wenn Sie Aktivitäten starten möchten, die zum Laufzeit-fähigen SDK gehören, verwenden Sie die Erweiterung createSdkActivityLauncher, um einen Launcher im Laufzeit-fähigen SDK zu erstellen.

Dieser Launcher kann dann an Ihr laufzeitfähiges SDK übergeben werden, damit es bei Bedarf Aktivitäten starten kann.

Mit einem Prädikat können Sie festlegen, ob die Aktivität gestartet wird oder nicht. Das Prädikat muss den Wert true zurückgeben, damit Aktivitäten zulässig sind.

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

Registrieren Sie SdkSandboxActivityHandlerCompat in Ihrem laufzeitfähigen SDK und stellen Sie es SdkActivityLauncher.LaunchSdkActivity(IBinder) zur Verfügung.

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

Die an SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) übergebene ActivityHolder implementiert LifecycleOwner und ermöglicht Ihrem laufzeitfähigen SDK den Zugriff auf den Lebenszyklus der Aktivität.

Außerdem wird die getOnBackPressedDispatcher API bereitgestellt, mit der getOnBackPressedCallback-Instanzen registriert werden können, um das Verhalten der Zurück-Schaltfläche in der Aktivität zu verarbeiten.


Schritt 3: Laufzeitfähiges SDK erstellen Schritt 5: Testen und für die Verteilung erstellen