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

Mit der SDK-Laufzeit können Anzeigen-SDKs in einer Sandbox-Umgebung ausgeführt werden, sodass sie nicht auf die Ansichtshierarchie eines Publishers zugreifen können. Um Anzeigen anzuzeigen, stellt die Plattform dem SDK eine SandboxedSdkProvider.getView API zur Verfügung, um eine Anzeigenansicht abzurufen, und verpackt sie als SurfacePackage, um sie über IPC (Inter-Process Communication) an die Clientanwendung zu senden. Das hat mehrere Nachteile, die unten beschrieben werden. In diesem Dokument wird dann eine vorgeschlagene Jetpack-Bibliothek vorgestellt, die entwickelt wird, um diese Herausforderungen zu meistern.

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

Die Framework-APIs sind flexibel und überlassen die Aufgabe, einen Nebenkanal für die UI-Darstellung zu erstellen, der App und dem SDK. Dieser Seitenkanal hat folgende Funktionen:

  1. Ermöglicht es dem SDK, mehrere Anzeigenaufrufe während ihrer Lebensdauer zu verwalten und zu verstehen, was mit der Anzeigen-UI passiert, nachdem sie vom SDK erstellt wurde.
  2. Trennt die Erstellung von Ansichten von der Bindung von Inhalten. Mithilfe des Sidechannels kann das SDK ein Objekt zurückgeben, das der Anzeigenanfrage an die App entspricht (der Inhalt), das nach Bedarf an den Anzeigencontainer gebunden werden kann.
  3. Die zugrunde liegenden Plattformkonstrukte werden abstrahiert, die für die Darstellung der Benutzeroberfläche in verschiedenen Prozessen verwendet werden. (Die Plattform verwendet derzeit eine SurfaceControlViewhost und generiert daraus eine SurfacePackage.)
  4. Hiermit können Anzeigen-SDKs in der SDK-Laufzeit automatisch benachrichtigt werden, wenn sich die Benutzeroberfläche des Anzeigencontainers ändert. Wenn ein Publisher das Layout des Anzeigencontainers ändert, werden diese Änderungen nicht an das SDK gesendet, es sei denn, der Publisher ruft explizit eine API auf, um es zu benachrichtigen.
  5. Synchronisiert die Größenänderung der Anzeigen-UI und des Anzeigencontainers ohne für den Nutzer sichtbare Ruckler.
  6. Verwaltet die Abwärtskompatibilität automatisch. SurfacePackage ist vor API-Level 30 nicht verfügbar. Außerdem ist es auf Geräten, auf denen keine SDK-Laufzeit vorhanden ist und das SDK prozesslokal für den Publisher ist, verschwenderisch, eine SurfacePackage für eine Anzeige zu erstellen, wenn eine Datenansicht direkt aus dem SDK abgerufen werden kann. Der Sidechannel abstrahiert diese Komplexität vom SDK- und App-Entwicklercode.
  7. Ermöglicht die nahtlose Integration der Anzeigen-Benutzeroberfläche in Composables. Jetpack Compose-Entwickler, die nicht mit Ansichten arbeiten, können weiterhin die vom SDK-Entwickler generierte Benutzeroberfläche hosten, der noch mit Ansichten arbeitet.

UI-Bibliotheken

Die UI-Bibliotheken abstrahieren die oben beschriebenen Komplexitäten und bieten den Publishern und dem SDK einen Nebenkanal, über den die Benutzeroberfläche prozessübergreifend angezeigt und bei Interaktionen des Nutzers mit der Benutzeroberfläche und dem Gerät aktualisiert werden kann.

Es gibt drei UI-Bibliotheken: core, client und provider. Die Kernbibliothek stellt die Schnittstellen bereit, die von Client- und Anbieterbibliotheken verwendet werden. Der UI-Anbieter (in der Regel das SDK) hängt von der Anbieterbibliothek ab und der Nutzer der UI (in der Regel der Publisher) von der Clientbibliothek. Zusammen bilden die Client- und Anbieterbibliotheken den Sidechannel, der zum Erstellen und Verwalten einer UI-Sitzung erforderlich ist.

APIs

Die APIs für die Darstellung der SDK-Laufzeit-Benutzeroberfläche sind:

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

SandboxedSdkView: Ein vom Publisher erstellter Container, der Inhalte enthält, die über die SandboxedUiAdapter abgerufen wurden.

Session: Wird vom SDK als Reaktion auf die SandboxedUiAdapter.openSession() erstellt. Stellt einen UI-Sitzungsaufruf dar. Dies bildet das SDK-Ende des Kommunikationstunnels zwischen dem SDK und dem Publisher und empfängt Benachrichtigungen zu Änderungen in SandboxedSdkView, z. B. zum Trennen von Fenstern, zum Ändern der Größe oder zu Konfigurationsänderungen.

SessionClient: Dieser Wert wird von der Clientbibliothek erstellt und bildet das Publisher-Ende des Kommunikationstunnels 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.

Abbildung, die die Beziehungen zwischen der SDK Runtime UI-Präsentations-API zeigt
Beziehungen zwischen den APIs zur Darstellung der SDK-Laufzeit-Benutzeroberfläche

Weitere Informationen zu diesen APIs finden Sie in der Referenzdokumentation für privacysandbox-ui.

Kontrollfluss

Die folgenden Diagramme zeigen die Interaktion zwischen den UI-Bibliotheken von Kunden und Anbietern in verschiedenen Szenarien:

Im vorherigen Diagramm wird gezeigt, wie der Publisher eine SandboxedSdkView programmatisch oder über seine XML-Datei erstellen und an eine SdkSandboxUiAdapter anhängen kann, die über eine vom SDK definierte API aus dem SDK abgerufen wird. Um alle Änderungen am UI-Status zu beobachten, sollte der Publisher SandboxedSdkUiSessionStateChangedListener zu SandboxedSdkView hinzufügen, bevor er SdkSandboxUiAdapter anhängt.

Abbildung, die den Ablauf einer offenen Sitzung zeigt
UI aus dem SDK abrufen

Dieses Diagramm zeigt, wie die Clientbibliothek die Konfigurationsänderung an das SDK weiterleitet, wenn die Aktivität des Publishers Konfigurationsänderungen verarbeitet, damit die Benutzeroberfläche entsprechend aktualisiert werden kann. Dieser Ablauf kann beispielsweise ausgelöst werden, wenn der Nutzer das Gerät dreht und der Publisher die Verarbeitung von Konfigurationsänderungen in seinen Aktivitäten angibt, indem er android:configChanges=["orientation"] festlegt.

Vom Publisher initiierte Änderung der Benutzeroberfläche.

In diesem Diagramm wird veranschaulicht, wie das SDK mithilfe von Methoden auf SessionClient eine Änderung am Anzeigencontainer anfordern kann. Diese API wird ausgelöst, wenn das SDK die Größe der Anzeige ändern möchte und der Publisher die Größe des Anzeigencontainers entsprechend anpassen muss. Das kann auf eine Nutzerinteraktion wie mraid.resize() zurückzuführen sein.

SDK-initiierte UI-Änderung.

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

Schließen der UI-Sitzung.

Z-Reihenfolge

Die Client-UI-Bibliothek verwendet intern einen SurfaceView, um die Benutzeroberfläche des SDKs zu hosten. SurfaceView kann die Benutzeroberfläche entweder über oder unter dem Fenster des Publishers anzeigen lassen. Dies wird über die Methode SandboxedSdkView.orderProviderUiAboveClientUi() gesteuert, die einen booleschen Wert setOnTop akzeptiert.

Wenn setOnTop = true ist, werden alle android.view.MotionEvent in der 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 Anzeigenaufrufen in der Regel nicht ändern. Wenn jedoch eine Benutzeroberfläche angezeigt wird, die eine Anzeige überdeckt, z. B. ein Drop-down-Menü, sollte die Z-Reihenfolge vorübergehend vom Standard umgekehrt und dann wiederhergestellt werden, wenn das überlagernde Benutzeroberflächenelement geschlossen wird. Wir arbeiten daran, diesen Prozess in der Client-UI-Bibliothek zu automatisieren.

Scrollen

Wenn die Anzeigen-UI im Z-Index über dem Publisher-Fenster angeordnet ist, werden MotionEvents von der Anzeigen-UI an das SDK gesendet. Scroll- und Wischgesten, die über die Anzeigen-UI gestartet werden, werden besonders behandelt:

  1. Vertikale Scroll- und Wischgesten werden an den Container des Publishers gesendet und dort verarbeitet. Dies sorgt für eine gute Nutzererfahrung, wenn der Container des Publishers, in dem die Anzeigen-UI platziert ist, vertikal scrollbar ist. Das erfordert keine zusätzlichen Arbeiten seitens des SDKs oder des Publishers.
  2. Horizontales Scrollen und Wisch-Gesten werden an das SDK gesendet und dort verarbeitet. Dies sorgt für eine gute Nutzererfahrung, wenn die Anzeigenoberfläche selbst horizontal scrollbar ist (z. B. ein Anzeigenkarussell).

Implementierungsleitfaden

Das SDK sollte Folgendes implementieren:

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

Der Verlag oder Webpublisher sollte Folgendes tun:

  1. Erstellen Sie eine SandboxedSdkView, entweder über XML oder programmatisch.
  2. Hängen Sie ein SandboxedSdkUiSessionStateChangedListener an das SandboxedSdkView an, um Änderungen an der Benutzeroberfläche zu beobachten.
  3. Hängen Sie ein von Ihnen bereitgestelltes SDK an die SandboxedSdkView an.SandboxedUiAdapter
  4. Fügen Sie dem Fenster wie gewohnt SandboxedSdkView hinzu und lassen Sie die Clientbibliothek die UI-Sitzung mit dem SDK erstellen und verwalten.
  5. Reagieren Sie bei Bedarf auf Änderungen des Status, der von SandboxedSdkUiSessionChangedListener gemeldet wird. Wenn das SDK beispielsweise die Sitzung unerwartet schließt, kann der Publisher SandboxedSdkView durch ein statisches Bild ersetzen oder aus der Ansichtshierarchie entfernen.
  6. Wenn Sie Übergänge verwenden, die die Anzeigen-UI verdecken könnten, z. B. ein Drop-down-Menü, setzen Sie orderProviderUiAboveClientUi vorübergehend auf „false“, um die Anzeigen-UI unter dem Fenster des Publishers zu platzieren. Nachdem das Drop-down-Menü geschlossen wurde, geben Sie orderProviderUiAboveClientUi bis true ein.

Die Zukunft der Plattform-APIs

Sobald die UI-Bibliotheken in die Betaphase übergehen, werden die SDK-Laufzeit-Plattform-APIs für die UI-Darstellung eingestellt, nämlich SdkSandboxManager.requestSurfacePackage() und SandbxedSdkProvider.getView().

Offene Fragen

  1. Gibt es weitere gängige Anwendungsfälle für die Anzeigenoberfläche, die von den UI-Bibliotheken automatisch verarbeitet werden sollten?
  2. Welche UI-Frameworks verwenden Sie, um die Anzeigenoberfläche anzuzeigen? Erwarten Sie Probleme bei der Einbindung der UI-Bibliotheken in diese Frameworks?
  3. Ist die Ansicht einer scrollbaren Anzeige in einem scrollbaren Publisher-Container ein gängiger Anwendungsfall für Sie? In welche Richtung wird in diesem Fall die Anzeige-UI und der Container gescrollt? Welches Verhalten erwarten Sie, wenn der Nutzer auf der Anzeigen-UI scrollt?