Aktivitätsunterstützung für Vollbildanzeigen

Mit der SDK Runtime gelten Einschränkungen dafür, wie SDKs neue Aktivitäten starten können. Dies stellt eine Herausforderung für Vollbildanzeigen dar, bei denen für eine bessere Kontrolle und Nutzererfahrung normalerweise eine separate Aktivität gestartet wird. Um dieses Problem zu beheben, wurde mit SDK Runtime ein neuer Mechanismus für Aktivitäten in einer Sandbox eingeführt.

SDKs, die in der SDK-Laufzeitumgebung geladen werden, können <activity>-Tags nicht direkt in ihrem Manifest definieren oder ihre eigenen Aktivitäten initiieren. Stattdessen wird die neue Intent-Aktion START_SANDBOXED_ACTIVITY eingeführt.

Mit dieser Aktion können SDKs zwar auch keine Intents starten, aber SDKs können die Client-App anfordern, um den Intent zu starten. Das System erstellt dann eine plattformdefinierte Aktivität und übergibt sie an das SDK. Diese Aktivität wird im selben Prozess wie das SDK ausgeführt.

Das SDK kann diese Aktivität dann verwenden, um die Vollbildanzeige zu implementieren und zu verwalten.

Die von der Plattform bereitgestellte Aktivität ist ein Standard-android.app.Activity, der im Rahmen der Aufgabe der Client-App gestartet wird.

Achtung:Die bereitgestellte Aktivität (android.app.Activity) wird von einigen AndroidX-Bibliotheken auf SDK-Seite nur eingeschränkt unterstützt, insbesondere von Compose.

Achtung: Die Context dieser Aktivität sollte nicht direkt vom SDK verwendet werden. Stattdessen müssen SDKs SandboxedSdkProvider#getContext() verwenden, um den entsprechenden Kontext für ihre Vorgänge zu erhalten.

Aktivitäten in der SDK-Laufzeit erstellen

Es gibt zwei Hauptmethoden, um Aktivitäten zu erstellen: die optimierten Aktivitätenbibliotheken von Jetpack oder die direkte Interaktion mit Platform-APIs.

Wir empfehlen die Verwendung von Aktivitätsbibliotheken, da sie die Erstellung von Aktivitäten vereinfachen, da sie die zugrunde liegende Komplexität abstrahieren.

Aktivitätenbibliotheken

Aktivitätsbibliotheken bieten mehrere Vorteile:

• Abstrahieren Sie die internen Details der Registrierung von Aktivitäts-Handlern und der Freigabe ihrer IDs für Client-Apps.
• Gibt App-Entwicklern mehr Kontrolle darüber, wie SDKs Aktivitäten in ihren Apps erstellen, indem sie Bedingungen (Prädikate) festlegen können, die erfüllt sein müssen.
• Erstellen Sie eine einheitliche Möglichkeit für SDKs, APIs zu definieren, die Aktivitäten starten.

Es gibt drei Aktivitätsbibliotheken: Core, Client und Provider.

• Die core-Bibliothek stellt die Schnittstellen bereit, die von Client-Apps und Anbieterbibliotheken verwendet werden.
• Die Bibliothek provider stellt APIs für SDKs zum Starten von Aktivitäten bereit.
• Die Clientbibliothek stellt APIs für Client-Apps zur Verfügung, mit denen ein Aktivitäts-Launcher erstellt werden kann. Mit diesen APIs können SDKs Apps zum Starten von Aktivitäten auffordern.

Diese Bibliotheken führen die folgenden APIs ein:

• SdkActivityLauncher: Mit dem Aktivitäts-Launcher können SDKs Aktivitäten über die Client-App starten. Client-Apps sollten einen Launcher erstellen und als Parameter an die APIs des SDKs übergeben, die Aktivitäten starten.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): Eine Erweiterungsfunktion, die die Client-App aus ihren Aktivitäten aufrufen kann, um Launcher zu erstellen.
• SdkActivityLauncher.launchSdkActivity(IBinder): Eine Methode, die vom SDK verwendet wird, um die App zum Starten von Aktivitäten anzufordern.

Der Ablauf beim Starten von Aktivitäten mit Aktivitätsbibliotheken ist folgender:

1. Das SDK fügt allen APIs, die Aktivitäten starten, einen Parameter des Typs SdkActivityLauncher hinzu.
2. Die Client-App ruft für eine der Aktivitäten createSdkActivityLauncher auf, um einen Launcher zu erstellen, der bei API-Aufrufen an das SDK übergeben werden kann.
3. Das SDK ruft SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) auf und ruft das ID-Token ab.
4. Das SDK ruft launchSdkActivity auf, um die Aktivität zu starten.

Hinweis :Wenn die Client-App eine Bedingung für SDKs zum Erstellen von Aktivitäten hinzufügen möchte, kann beim Erstellen des Launchers ein Prädikatausdruck übergeben werden. Wenn die App die Aktivitätserstellung nicht konditionieren soll, kann sie dafür sorgen, dass das Prädikat immer true zurückgibt.

Das folgende Diagramm zeigt den Ablauf für die Verwendung von Aktivitätsbibliotheken.

Sequenzdiagramm, das den Ablauf zum Starten einer Aktivität mithilfe von Aktivitätsbibliotheken zeigt.

Plattform-APIs

Die Plattform führt die folgenden APIs ein, um das Erstellen und Verwalten von Aktivitäten in einer Sandbox innerhalb der SDK-Laufzeit zu vereinfachen:

• SdkSandboxActivityHandler: Der Aktivitäts-Handler wird verwendet, um das SDK zu benachrichtigen, wenn eine Aktivität erstellt und vom SDK registriert wird.
• Zur Unterstützung bei der Registrierung von Aktivitäts-Handlern kann das SDK die folgenden Methoden unter SdkSandboxController verwenden:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Registriert eine Instanz von SdkSandboxActivityHandler, die eine IBinder-Kennung zurückgibt.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Hebt die Registrierung einer registrierten Instanz von SdkSandboxActivityHandler anhand ihrer ID auf.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Diese Methode wird von der Client-App aufgerufen und löst das Erstellen von Aktivitäten für das SDK aus. Die Client-App muss als Parameter ihre ausgewählte Startaktivität und die Aktivitäts-Handler-ID des SDKs übergeben.

Um eine Aktivität mit den Platform APIs zu starten, müssen SDKs so vorgehen:

1. Das SDK registriert einen Aktivitäts-Handler mithilfe der bereitgestellten APIs und ruft eine Kennung ab.
2. Das SDK gibt diese Kennung an die Client-App weiter.
3. Die Client-App ruft die Methode auf, um eine Aktivität in der SDK-Laufzeit mit der Plattform-API startSdkSandboxActivity(Activity, IBinder) zu starten. Dabei werden die ausgewählte Startaktivität für diese neue Aktivität und die ID des Aktivitäts-Handlers als Parameter übergeben.
4. Die Plattform startet eine Aktivität und benachrichtigt das SDK über einen Callback im Activity Handler (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. Das SDK verwendet die Aktivität, um eine Anzeige zu platzieren.

Hinweis :onActivityCreated(Activity) wird über Activity.onCreate(Bundle) aufgerufen. SDKs werden in dieser Phase die Inhaltsansicht bereitstellen.

Durch die Verwendung von Platform APIs ist das SDK dafür verantwortlich, die Kennung des SdkSandboxActivityHandler zu einem geeigneten Zeitpunkt über seine APIs an die Client-App weiterzugeben. Außerdem muss das SDK die Verwendung der Client-Apps anleiten.

Im folgenden Flussdiagramm enthält das Beispiel-SDK die Methode launchActivity(AppCallback), die einen Callback erwartet (definiert als Teil der SDK API). Dieser Callback wird vom SDK verwendet, um die ID des Aktivitäts-Handlers (SdkSandboxActivityHandler) mit der Client-App zu teilen.

Sequenzdiagramm, das den Ablauf zum Starten einer Aktivität mit Plattform-APIs zeigt.

Sichtbarkeit

Innerhalb von SDK Runtime verwenden Anzeigen, die in die Ansichtshierarchie der Client-App integriert sind, Nebenkanäle, um SDK-Ansichten vom SDK-Prozess bis zum Prozess der Client-App zu rendern.

Das SDK kann nicht dieselben View APIs wie außerhalb der SDK-Laufzeit verwenden, um zu bestimmen, ob die Anzeige für den Nutzer sichtbar ist, da die Anzeigenansicht nicht mit dem Fenster der Anwendung verknüpft ist (Sichtbarkeit).

Im Gegensatz dazu wird die von der Plattform bereitgestellte Aktivität nativ innerhalb des SDK Runtime-Prozesses ausgeführt, wodurch die Notwendigkeit von Nebenkanälen entfällt und SDKs die Verwendung der standardmäßigen Android-APIs Activity und View ermöglichen.

Aufgrund dieser unterschiedlichen Implementierungen versuchen wir, die Schnittstellen so zu vereinheitlichen, dass die Sichtbarkeitssignale unabhängig vom Ladekontext der Anzeige abgerufen werden.

Lifecycle

Der ActivityHolder, der über SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder)-Implementierungen LifecycleOwner an das SDK übergeben wird, kann als Lifecycle.Event verwendet werden.

Rückwärtsnavigation

Die Methode ActivityHolder.getOnBackPressedDispatcher() gibt OnBackPressedDispatcher zurück, mit dem OnBackPressedCallback-Instanzen für die Rückwärtsnavigation registriert werden können.