Aktivitätsunterstützung für Vollbildanzeigen

Hinweis: Die Privacy Sandbox für Android ist ein fortlaufendes Projekt. Dieses Dokument spiegelt das aktuelle Design wider. Ihr Feedback ist uns wichtig, damit wir die Funktionen weiter entwickeln und verbessern können.

Die SDK-Laufzeit schränkt ein, wie SDKs neue Aktivitäten starten können. Das stellt eine Herausforderung für Vollbildanzeigen dar, bei denen normalerweise eine separate Aktivität gestartet wird, um die Kontrolle und Nutzerfreundlichkeit zu verbessern. Um dies zu beheben, wird in der SDK-Laufzeit ein neuer Mechanismus für Aktivitäten in Sandboxes eingeführt.

SDKs, die in der SDK Runtime-Umgebung geladen werden, können keine <activity>-Tags direkt in ihrem Manifest definieren oder eigene Aktivitäten initiieren. Stattdessen wird eine neue Intent-Aktion eingeführt: START_SANDBOXED_ACTIVITY.

SDKs dürfen zwar auch keine Intents mit dieser Aktion starten, sie können aber die Client-App bitten, diesen Intent zu initiieren. 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 eine standardmäßige android.app.Activity, die 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 abzurufen.

Aktivitätserstellung in der SDK-Laufzeit

Es gibt zwei Hauptmethoden zum Erstellen von Aktivitäten: die optimierten Jetpack-Aktivitätsbibliotheken verwenden oder direkt mit Plattform-APIs interagieren.

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

Aktivitätsbibliotheken

Aktivitätsbibliotheken bieten mehrere Vorteile:

• Die internen Details der Registrierung von Aktivitäts-Handlern und der Freigabe ihrer IDs für Client-Apps abstrahieren
• App-Entwicklern wird mehr Kontrolle darüber gegeben, wie SDKs Aktivitäten in ihren Apps erstellen, indem sie Bedingungen (Prädikate) festlegen können, die erfüllt sein müssen.
• Eine einheitliche Möglichkeit für SDKs zum Definieren von APIs, 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 provider-Bibliothek stellt APIs für SDKs zum Starten von Aktivitäten bereit.
• Die Client-Bibliothek bietet APIs für Client-Apps zum Erstellen eines Aktivitäts-Launchers, mit dem SDKs Apps anfordern können, Aktivitäten zu starten.

Diese Bibliotheken führen die folgenden APIs ein:

• SdkActivityLauncher: Mit dem Aktivitäts-Launcher können SDKs das Starten von Aktivitäten über die Client-App steuern. Client-Apps sollten einen Launcher erstellen und ihn 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, mit der das SDK die App auffordert, Aktivitäten zu starten.

So starten Sie Aktivitäten mit Aktivitätsbibliotheken:

1. Das SDK fügt allen APIs, die Aktivitäten starten, einen Parameter vom Typ SdkActivityLauncher hinzu.
2. Die Client-App ruft createSdkActivityLauncher in einer ihrer Aktivitäten 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 Identitätstoken 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 sie beim Erstellen des Launchers einen Prädikatsausdruck übergeben. Wenn die App die Erstellung von Aktivitäten nicht steuern möchte, kann das Prädikat so festgelegt werden, dass es immer true zurückgibt.

Das folgende Diagramm zeigt den Ablauf bei Verwendung von Aktivitätsbibliotheken.

Sequenzdiagramm, das den Ablauf des Startens einer Aktivität mithilfe von Aktivitätsbibliotheken zeigt

Plattform-APIs

Die Plattform bietet die folgenden APIs, um das Erstellen und Verwalten von Aktivitäten in der Sandbox innerhalb der SDK Runtime zu erleichtern:

• SdkSandboxActivityHandler: Der Activity Handler wird verwendet, um das SDK zu benachrichtigen, wenn eine Aktivität erstellt wird. Er wird vom SDK registriert.
• Zur Unterstützung bei der Registrierung von Aktivitätshandlern kann das SDK die folgenden Methoden unter SdkSandboxController verwenden:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Registriert eine Instanz von SdkSandboxActivityHandler, wodurch eine IBinder-ID zurückgegeben wird.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Mit dieser Option wird eine registrierte Instanz von SdkSandboxActivityHandler anhand ihrer Kennung abgemeldet.
• 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 die ausgewählte Startaktivität und die Activity Handler-ID des SDKs übergeben.

Wenn eine Aktivität mit den Platform APIs gestartet werden soll, müssen SDKs diesen Ablauf einhalten:

1. Das SDK registriert einen Aktivitäts-Handler mithilfe der bereitgestellten APIs und erhält eine Kennung.
2. Das SDK gibt diese Kennung an die Client-App weiter.
3. Die Client-App ruft die Methode zum Starten einer Aktivität in der SDK-Laufzeit mit der Plattform-API startSdkSandboxActivity(Activity, IBinder) auf und übergibt als Parameter die ausgewählte Startaktivität für diese neue Aktivität und die Kennung des Aktivitäts-Handlers.
4. Die Plattform startet eine Aktivität und benachrichtigt das SDK über einen Rückruf im Activity Handler (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. Das SDK verwendet die Aktivität, um sie mit einer Anzeige zu füllen.

Hinweis: onActivityCreated(Activity) wird über Activity.onCreate(Bundle) aufgerufen. SDKs müssen in dieser Phase die Inhaltsanzeige füllen.

Bei der Verwendung von Plattform-APIs ist das SDK dafür verantwortlich, die Kennung des SdkSandboxActivityHandler zur passenden Zeit über seine APIs an die Client-App weiterzugeben und Client-Apps bei der Verwendung zu unterstützen.

Im folgenden Flussdiagramm hat das Beispiel-SDK die Methode launchActivity(AppCallback), für die ein Rückruf erwartet wird, der als Teil der SDK-API definiert ist. Über diesen Rückruf gibt das SDK die Kennung des Activity Handlers (SdkSandboxActivityHandler) an die Client-App weiter.

Ablaufdiagramm, das den Ablauf zum Starten einer Aktivität mithilfe von Plattform-APIs zeigt

Sichtbarkeit

In der SDK-Laufzeit werden Anzeigen, die in die Ansichtshierarchie der Client-App eingebunden sind, mithilfe von Sidecar-Kanälen gerendert, um SDK-Ansichten vom SDK-Prozess an den Prozess der Client-App zu übertragen.

Das SDK kann nicht dieselben View APIs verwenden, die außerhalb der SDK-Laufzeit verwendet werden, um zu bestimmen, ob die Anzeige für den Nutzer sichtbar ist, da der Anzeigen-View nicht am Fenster der Anwendung angehängt ist (Sichtbarkeit).

Im Gegensatz dazu wird die von der Plattform bereitgestellte Aktivität nativ im SDK-Runtime-Prozess ausgeführt. Sidechannels sind nicht erforderlich und SDKs können standardmäßige Android-Activity- und View-APIs verwenden.

Aufgrund dieser unterschiedlichen Implementierungen werden derzeit Bemühungen unternommen, die Oberflächen zu vereinheitlichen, um die Sichtbarkeitssignale unabhängig vom Kontext des Anzeigenladens abzurufen.

Lifecycle

Die über SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) an das SDK übergebene ActivityHolder implementiert LifecycleOwner und kann verwendet werden, um Informationen zur Lifecycle.Event zu erhalten.

Rückwärtsnavigation

Die Methode ActivityHolder.getOnBackPressedDispatcher() gibt OnBackPressedDispatcher zurück, mit dem OnBackPressedCallback-Instanzen registriert werden können, um die Rücknavigation zu steuern.