APIs zur Präsentation der SDK Runtime-Benutzeroberfläche

Mit der SDK-Laufzeit können Anzeigen-SDKs in einer Sandbox-Umgebung ausgeführt werden. Dadurch wird verhindert, dass sie auf die Ansichtshierarchie eines Publishers zugreifen können. Zum Anzeigen von Anzeigen stellt die Plattform dem SDK eine SandboxedSdkProvider.getView API zur Verfügung, um eine Anzeigenansicht abzurufen. Diese wird als SurfacePackage verpackt und über IPC (Inter-Process Communication) an die Clientanwendung gesendet. Das hat mehrere Nachteile, die unten erläutert werden. In diesem Dokument wird dann eine vorgeschlagene Jetpack-Bibliothek vorgestellt, die entwickelt wird, um diese Herausforderungen zu bewältigen.

Begründung für die Erweiterung der Plattform-APIs

Die Framework-APIs sind auf Flexibilität ausgelegt und überlassen die Aufgabe, einen Side-Channel für die UI-Präsentation zu erstellen, der App und dem SDK. Dieser Seitenkanal hat folgende Funktionen:

1. Ermöglicht dem SDK, mehrere Anzeigenansichten während ihres Lebenszyklus zu verwalten und zu verstehen, was mit der Anzeigen-UI passiert, nachdem sie vom SDK erstellt wurde.
2. Entkoppelt die Ansichtserstellung und die Inhaltsbindung. Über den Side-Channel kann das SDK ein Objekt zurückgeben, das der Anzeigenanfrage entspricht (der Inhalt). Dieses Objekt kann an den Anzeigencontainer gebunden werden, wann immer die App dies für angemessen hält.
3. Abstrahiert die zugrunde liegenden Plattformkonstrukte, die zum Anzeigen der Benutzeroberfläche in verschiedenen Prozessen verwendet werden. (Die Plattform verwendet derzeit ein SurfaceControlViewhost und generiert daraus ein SurfacePackage.)
4. Ermöglicht es, dass Anzeigen-SDKs in der SDK-Laufzeit automatisch Benachrichtigungen erhalten, wenn sich die Benutzeroberfläche des Anzeigencontainers ändert. Wenn ein Verlag oder Webpublisher das Layout des Anzeigencontainers ändert, werden diese Änderungen vom SDK nicht erkannt, es sei denn, der Verlag oder Webpublisher ruft explizit eine API auf, um das SDK zu benachrichtigen.
5. Synchronisiert die Größenänderungen der Anzeigen-UI und des Anzeigencontainers ohne für den Nutzer sichtbare Ruckler.
6. Die Abwärtskompatibilität wird automatisch verwaltet. SurfacePackage ist vor API-Level 30 nicht verfügbar. Außerdem ist es auf Geräten ohne SDK-Laufzeit, auf denen das SDK prozesslokal für den Publisher ist, ineffizient, ein SurfacePackage für eine Anzeige zu erstellen, wenn eine Ansicht direkt vom SDK abgerufen werden kann. Der Side Channel abstrahiert diese Komplexität vom SDK und vom App-Entwicklercode.
7. Ermöglicht die nahtlose Integration der Anzeigen-UI in Composables. Jetpack Compose-Entwickler, die nicht mit Ansichten arbeiten, können weiterhin UI-Elemente hosten, die vom SDK-Entwickler generiert wurden, der weiterhin mit Ansichten arbeitet.

UI-Bibliotheken

Die UI-Bibliotheken abstrahieren die oben beschriebenen Komplexitäten und stellen den Side-Channel bereit, über den Publisher und SDK die Benutzeroberfläche prozessübergreifend anzeigen und aktualisieren können, wenn der Nutzer mit ihr und dem Gerät interagiert.

Es gibt drei UI-Bibliotheken: core, client und provider. Die Core-Bibliothek enthält die Schnittstellen, die von Client- und Anbieterbibliotheken verwendet werden. Der UI-Anbieter (in der Regel das SDK) ist von der Anbieterbibliothek abhängig und der Nutzer der UI (in der Regel der Publisher) ist von der Clientbibliothek abhängig. Die Client- und Anbieterbibliotheken bilden zusammen den Side-Channel, der zum Erstellen und Verwalten einer UI-Sitzung erforderlich ist.

Die APIs

Die APIs für die UI-Darstellung der SDK-Laufzeit sind:

SandboxedUiAdapter: Wird vom SDK erstellt und bietet eine Möglichkeit, Inhalte abzurufen, die in der Benutzeroberfläche des Verlags oder Webpublishers angezeigt werden sollen.

SandboxedSdkView: Dieser vom Verlag oder Webpublisher erstellte Container enthält Inhalte, die über die SandboxedUiAdapter abgerufen wurden.

Session: Wird vom SDK als Reaktion auf die SandboxedUiAdapter.openSession() erstellt. Stellt eine UI-Sitzung dar. Dies ist das SDK-Ende des Kommunikationskanals zwischen dem SDK und dem Publisher. Es empfängt Benachrichtigungen über Änderungen in SandboxedSdkView, z. B. das Trennen von Fenstern, Größenänderungen oder Konfigurationsänderungen.

SessionClient: Diese Klasse wird von der Clientbibliothek erstellt und bildet das Publisher-Ende des Kommunikationskanals zwischen dem SDK und dem Publisher.

SandboxedSdkUiSessionStateChangedListener: Vom Verlag oder Webpublisher erstellt. Ein Listener für Änderungen am Status der UI-Sitzung, die mit SandboxedSdkView verknüpft ist.

Weitere Informationen zu diesen APIs finden Sie in der Referenzdokumentation zur Privacy Sandbox-Benutzeroberfläche.

Kontrollfluss

Die folgenden Diagramme zeigen die Interaktion zwischen den Client- und Anbieter-UI-Bibliotheken in verschiedenen Szenarien:

Im vorherigen Diagramm sehen Sie, wie der Publisher ein SandboxedSdkView programmatisch oder über sein XML erstellen und es an ein SdkSandboxUiAdapter anhängen kann, das über eine SDK-definierte API aus dem SDK abgerufen wurde. Um alle Änderungen des UI-Status zu beobachten, sollte der Publisher SandboxedSdkUiSessionStateChangedListener zu SandboxedSdkView hinzufügen, bevor SdkSandboxUiAdapter angehängt wird.

Dieses Diagramm zeigt, wie die Clientbibliothek Konfigurationsänderungen an das SDK weiterleitet, wenn die Aktivität des Verlags oder Webpublishers Konfigurationsänderungen verarbeitet, damit die UI entsprechend aktualisiert werden kann. Dieser Ablauf kann beispielsweise ausgelöst werden, wenn der Nutzer das Gerät dreht und der Publisher angibt, dass er Konfigurationsänderungen in seiner Aktivität verarbeitet, indem er android:configChanges=["orientation"] festlegt.

In diesem Diagramm wird veranschaulicht, wie das SDK mit Methoden für SessionClient eine Änderung des Anzeigencontainers anfordern kann. Diese API wird ausgelöst, wenn das SDK die Größe der Anzeige ändern möchte und der Publisher den Anzeigencontainer an die neuen Abmessungen anpassen muss. Das kann als Reaktion auf eine Nutzerinteraktion geschehen, z. B. mraid.resize().

Dieses Diagramm zeigt, wie die Sitzung geschlossen wird, wenn das SandboxedSdkView vom Fenster getrennt wird. Die Sitzung kann auch jederzeit vom SDK geschlossen werden, z.B. wenn der Nutzer die Netzwerkverbindung verliert, indem SessionClient.onSessionError() aufgerufen wird.

Z-Reihenfolge

In der Client-UI-Bibliothek wird intern ein SurfaceView verwendet, um die UI des SDK zu hosten. SurfaceView kann die Z-Reihenfolge verwenden, um die Benutzeroberfläche entweder über oder unter dem Fenster des Publishers anzuzeigen. Dies wird über die Methode SandboxedSdkView.orderProviderUiAboveClientUi() gesteuert, die einen booleschen Wert setOnTop akzeptiert.

Wenn setOnTop gleich true ist, wird jedes android.view.MotionEvent im SandboxedSdkView an das SDK gesendet. Wenn false, werden sie an den Publisher gesendet. Standardmäßig werden Bewegungsereignisse an das SDK gesendet.

Publisher müssen die Standard-Z-Reihenfolge von Anzeigenansichten in der Regel nicht ändern. Wenn jedoch eine Benutzeroberfläche angezeigt wird, die eine Anzeige abdeckt, z. B. ein Drop-down-Menü, sollte die Z-Reihenfolge vorübergehend von der Standardeinstellung abweichen und dann wiederhergestellt werden, wenn das abdeckende UI-Element geschlossen wird. Wir suchen nach Möglichkeiten, diesen Prozess in der Client-UI-Bibliothek zu automatisieren.

Scrollen

Wenn die Anzeigen-UI über dem Publisher-Fenster angeordnet ist, werden MotionEvents aus der Anzeigen-UI an das SDK gesendet. Scroll- und Wischgesten, die in der Anzeigen-UI ausgeführt werden, werden besonders behandelt:

1. Vertikales Scrollen und Wischen werden an den Container des Publishers gesendet und von diesem verarbeitet. Das sorgt für eine gute Nutzerfreundlichkeit, wenn der Container des Publishers, in dem sich die Anzeigen-UI befindet, vertikal gescrollt werden kann. Für das SDK oder den Publisher ist kein zusätzlicher Aufwand erforderlich.
2. Horizontale Scroll- und Wischbewegungen werden an das SDK gesendet und von diesem verarbeitet. Das sorgt für eine gute Nutzerfreundlichkeit, wenn die Anzeigenoberfläche selbst horizontal scrollbar ist, z. B. bei einem Anzeigenkarussell.

Implementierungsleitfaden

Das SDK sollte Folgendes implementieren:

• SandboxedUiAdapter: Dieser Wert wird dem Publisher als Antwort auf eine SDK-definierte API wie loadAd zurückgegeben. Die openSession()-Methode dieser Implementierung sollte verwendet werden, um eine Anzeigenanfrage an die Server des SDK zu senden und eine Anzeigenansicht für diese Anfrage vorzubereiten.
• Session**: Dieser Wert wird als Antwort auf den SandboxedUiAdapter.openSession-Aufruf zurückgegeben. Sie bietet der Clientbibliothek die Möglichkeit, die Anzeigen-UI abzurufen und das SDK über Änderungen an dieser API zu benachrichtigen. Alle Session-Methoden sollten hier implementiert werden.

Der Publisher sollte so vorgehen:

1. Erstellen Sie eine SandboxedSdkView entweder über XML oder programmgesteuert.
2. Hängen Sie ein SandboxedSdkUiSessionStateChangedListener an das SandboxedSdkView an, um Änderungen an der Benutzeroberfläche zu beobachten.
3. Hängen Sie ein von SandboxedUiAdapter bereitgestelltes SDK an SandboxedSdkView an.
4. Fügen Sie SandboxedSdkView wie gewohnt dem Fenster hinzu. Die Clientbibliothek kümmert sich dann um das Erstellen und Verwalten der UI-Sitzung mit dem SDK.
5. Reagieren Sie zu geeigneten Zeiten auf Änderungen des von SandboxedSdkUiSessionChangedListener gemeldeten Status. Wenn das SDK die Sitzung beispielsweise unerwartet schließt, kann der Publisher SandboxedSdkView durch ein statisches Bild ersetzen oder aus der Ansichtshierarchie entfernen.
6. Wenn Sie Übergänge vornehmen, die die Anzeigen-UI möglicherweise verdecken, z. B. ein Drop-down-Menü, setzen Sie orderProviderUiAboveClientUi vorübergehend auf „false“, um die Anzeigen-UI unter dem Fenster des Publishers zu positionieren. Wenn das Drop-down-Menü geschlossen wird, rufe orderProviderUiAboveClientUi bis true auf.

Die Zukunft der Plattform-APIs

Sobald die UI-Bibliotheken in die Betaphase eintreten, planen wir, die SDK-Laufzeitplattform-APIs für die UI-Darstellung, nämlich SdkSandboxManager.requestSurfacePackage() und SandbxedSdkProvider.getView(), einzustellen.

Offene Fragen

1. Gibt es weitere gängige Anwendungsfälle für die Anzeigen-Benutzeroberfläche, die von den UI-Bibliotheken automatisch verarbeitet werden sollten?
2. Welche UI-Frameworks verwenden Sie, um die Anzeigen-UI zu präsentieren? Erwarten Sie Probleme bei der Integration der UI-Bibliotheken in diese Frameworks?
3. Ist die Platzierung einer scrollbaren Anzeigen-Benutzeroberfläche in einem scrollbaren Publisher-Container ein häufiger Anwendungsfall für Sie? In welche Richtung wird in diesem Fall in der Anzeigen-UI und im Container gescrollt? Welches Verhalten erwarten Sie, wenn der Nutzer im Anzeigen-UI scrollt?