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

Die SDK-Laufzeit ermöglicht die Ausführung von Anzeigen-SDKs in einer Sandbox-Umgebung, wodurch sie nicht auf die Ansichtshierarchie eines Publishers zugreifen können. Zum Ausliefern von Anzeigen stellt die Plattform dem SDK eine SandboxedSdkProvider.getView API zur Verfügung, um eine Anzeigenansicht zu erhalten. Diese fasst sie als SurfacePackage zusammen, um sie über IPC (Inter-Process-Kommunikation) an die Clientanwendung zu senden. Dies hat mehrere Nachteile, die unten erläutert werden. In diesem Dokument wird dann eine vorgeschlagene Jetpack-Bibliothek vorgestellt, die zur Bewältigung dieser Herausforderungen entwickelt wird.

Gründe für die Erweiterung der Plattform-APIs

Die Framework-APIs sind auf Flexibilität ausgelegt und überlassen es die Aufgabe, einen Seitenkanal zwischen der Darstellung der Benutzeroberfläche bis zur App und dem SDK zu erstellen. Dieser Nebenkanal führt Folgendes aus:

  1. Ermöglicht das SDK, mehrere Anzeigenansichten während ihrer Lebensdauer zu verwalten und zu verstehen, was mit der Anzeigen-UI passiert, nachdem sie vom SDK erstellt wurde.
  2. Entkoppelt die Erstellung von Ansichten und die Inhaltsbindung. Wenn Sie den Side-Channel verwenden, kann das SDK ein Objekt zurückgeben, das der Anzeigenanfrage an die App (den Inhalt) entspricht und an den Anzeigencontainer gebunden werden kann, wann immer die App es für angemessen hält.
  3. Die zugrunde liegenden Plattformkonstrukte, die zur Darstellung von UI für verschiedene Prozesse verwendet werden, werden entfernt. (Die Plattform verwendet derzeit ein SurfaceControlViewhost und generiert daraus ein SurfacePackage.)
  4. Hiermit können Anzeigen-SDKs in der SDK-Laufzeit automatisch Benachrichtigungen erhalten, wenn sich die Benutzeroberfläche des Anzeigencontainers ändert. Wenn ein Publisher das Layout des Anzeigencontainers ändert, werden diese Änderungen vom SDK nicht erkannt, es sei denn, der Publisher ruft explizit eine API auf, um ihn zu benachrichtigen.
  5. Synchronisiert die Größe der Anzeigen-UI und des Anzeigencontainers ohne für den Nutzer sichtbare Verzögerung.
  6. Verwaltet automatisch die Abwärtskompatibilität. SurfacePackage ist erst ab API-Level 30 verfügbar. Auf Geräten, auf denen es keine SDK-Laufzeit gibt und das SDK für den Publisher prozesslokal ist, ist es außerdem unnötig, eine SurfacePackage für eine Anzeige zu erstellen, wenn eine Ansicht direkt über das SDK abgerufen werden kann. Mit dem Seitenkanal wird diese Komplexität vom SDK und vom App-Entwicklercode abgezogen.
  7. Ermöglicht die nahtlose Integration von Anzeigen-UI mit zusammensetzbaren Funktionen Jetpack Compose-Entwickler, die nicht mit Ansichten arbeiten, können auch weiterhin die vom SDK-Entwickler generierte UI hosten, die weiterhin mit Ansichten arbeitet.

UI-Bibliotheken

Die UI-Bibliotheken vermeiden die oben beschriebenen Komplexitäten und stellen den Side Channel bereit, den der Publisher und das SDK verwenden können, um die UI prozessübergreifend anzuzeigen und sie auf dem neuesten Stand zu halten, wenn der Nutzer mit ihnen und mit dem Gerät interagiert.

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 (normalerweise 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 Side Channel, der zum Erstellen und Verwalten einer UI-Sitzung erforderlich ist.

Die APIs

Darstellung der APIs für die SDK Runtime-Benutzeroberfläche:

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

SandboxedSdkView: Der vom Publisher erstellte Container enthält Inhalte, die über SandboxedUiAdapter abgerufen wurden.

Session: Wird vom SDK als Reaktion auf SandboxedUiAdapter.openSession() erstellt. Stellt einen UI-Sitzungsaufruf dar. Dies bildet das SDK-Ende des Kommunikationstunnels zwischen dem SDK und dem Publisher und erhält Benachrichtigungen über Änderungen in SandboxedSdkView, z. B. Fenstertrennungen, Größenänderungen oder Konfigurationsänderungen.

SessionClient: Wird von der Clientbibliothek erstellt und bildet das Ende des Kommunikationstunnels zwischen dem SDK und dem Publisher.

SandboxedSdkUiSessionStateChangedListener: Vom Publisher erstellt. Ein Listener auf Änderungen des Status der UI-Sitzung, die mit SandboxedSdkView verknüpft ist.

Abbildung: API-Beziehungen für die Präsentation der SDK Runtime UI
Beziehungen zwischen den Präsentations-APIs der SDK Runtime UI.

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

Ablaufsteuerung

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

Das vorherige Diagramm zeigt, wie der Verlag oder Webpublisher SandboxedSdkView programmatisch oder über seine XML-Datei erstellen und an eine SdkSandboxUiAdapter anhängen kann, die vom SDK über eine SDK-definierte API abgerufen wird. Der Verlag oder Webpublisher sollte SandboxedSdkView ein SandboxedSdkUiSessionStateChangedListener hinzufügen, bevor er SdkSandboxUiAdapter anhängt, um alle Statusänderungen der Benutzeroberfläche zu beobachten.

Abbildung, die den Prozess der offenen Sitzung zeigt.
Rufen Sie die UI aus dem SDK ab.

Dieses Diagramm zeigt, wie die Clientbibliothek die Konfigurationsänderung an das SDK weiterleitet, wenn die Aktivität des Verlags oder Webpublishers Konfigurationsänderungen verarbeitet, damit er die Benutzeroberfläche entsprechend aktualisieren kann. Dieser Vorgang kann beispielsweise ausgelöst werden, wenn der Nutzer das Gerät dreht und der Verlag oder Webpublisher durch das Festlegen von android:configChanges=["orientation"] die Verarbeitung von Konfigurationsänderungen in seiner Aktivität erklärt.

Vom Publisher initiierte UI-Änderung

Dieses Diagramm zeigt, wie das SDK mithilfe von Methoden in SessionClient eine Änderung im Anzeigencontainer anfordern kann. Die API wird ausgelöst, wenn das SDK die Größe der Anzeige anpassen möchte und der Publisher die Größe des Anzeigencontainers anpassen muss, um die neuen Abmessungen zu berücksichtigen. Dies kann als Reaktion auf eine Nutzerinteraktion wie mraid.resize() geschehen.

Durch das SDK initiierte UI-Änderung.

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

UI-Sitzung schließen

Z-Reihenfolge

Die Client-UI-Bibliothek verwendet SurfaceView intern zum Hosten der SDK-UI. SurfaceView kann die Z-Reihenfolge verwenden, um die UI entweder oben oder darunter anzuzeigen. Dies wird von der Methode SandboxedSdkView.orderProviderUiAboveClientUi() gesteuert, die einen booleschen Wert setOnTop akzeptiert.

Wenn setOnTop den Wert true hat, wird jeder android.view.MotionEvent im SandboxedSdkView an das SDK gesendet. Beim false werden sie an den Publisher gesendet. Standardmäßig werden Bewegungsereignisse an das SDK gesendet.

Publisher müssen in der Regel die Standard-Z-Reihenfolge der Anzeigenansichten nicht ändern. Wenn jedoch eine Benutzeroberfläche angezeigt wird, die eine Anzeige verdeckt (z. B. ein Drop-down-Menü), sollte die Z-Reihenfolge vorübergehend vom Standardwert geändert und 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 in der Reihenfolge Z über dem Publisher-Fenster angeordnet ist, werden MotionEvents von der Anzeigen-UI an das SDK gesendet. Scroll- und Ziehbewegungen, die auf der Benutzeroberfläche der Anzeige ausgelöst werden, haben besondere Vorteile:

  1. Vertikale Scroll- und fling-Gesten werden an den Container des Publishers gesendet und von diesem verarbeitet. Dies sorgt für eine gute Nutzererfahrung, wenn der Container des Publishers, in dem sich die Anzeigen-UI befindet, vertikal scrollbar ist. Für das SDK oder den Publisher sind keine zusätzlichen Arbeiten erforderlich.
  2. Horizontale Scroll- und fling-Gesten werden an das SDK gesendet und von diesem verarbeitet. Dies ist besonders nutzerfreundlich, wenn die Anzeigen-UI selbst horizontal scrollbar ist (z. B. bei einem Anzeigenkarussell).

Implementierungsleitfaden

Das SDK sollte Folgendes implementieren:

  • SandboxedUiAdapter: Wird als Antwort auf eine SDK-definierte API wie loadAd an den Publisher zurückgegeben. Die Methode openSession() dieser Implementierung sollte verwendet werden, um eine Anzeigenanfrage an die SDK-Server zu senden und eine Anzeigenansicht für diese Anfrage vorzubereiten.
  • Session**: Wird als Antwort auf den SandboxedUiAdapter.openSession-Aufruf zurückgegeben. Damit kann die Clientbibliothek die Anzeigen-UI abrufen und das SDK über Änderungen an der API informieren. Alle Session-Methoden sollten hier implementiert werden.

Der Publisher sollte Folgendes tun:

  1. Erstellen Sie ein SandboxedSdkView, entweder über XML oder programmatisch.
  2. Hängen Sie SandboxedSdkUiSessionStateChangedListener an SandboxedSdkView an, um Änderungen in der UI zu beobachten.
  3. Hängen Sie ein vom SDK bereitgestelltes SandboxedUiAdapter an SandboxedSdkView an.
  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 zu geeigneten Zeitpunkten auf Statusänderungen, die von SandboxedSdkUiSessionChangedListener gemeldet werden. Wenn die Sitzung beispielsweise durch das SDK unerwartet geschlossen wird, kann der Publisher SandboxedSdkView durch ein statisches Bild ersetzen oder aus seiner Ansichtshierarchie entfernen.
  6. Wenn Sie Übergänge vornehmen, die die Anzeigen-UI verdecken (z. B. ein Drop-down-Menü), sollten Sie vorübergehend orderProviderUiAboveClientUi auf „false“ setzen, um die Anzeigen-UI unter dem Fenster des Publishers zu positionieren. Wenn das Drop-down-Menü geschlossen ist, rufen Sie orderProviderUiAboveClientUi an true auf.

Die Zukunft der Plattform-APIs

Sobald die UI-Bibliotheken in der Betaphase sind, planen wir, die SDK-Laufzeitplattform-APIs SdkSandboxManager.requestSurfacePackage() und SandbxedSdkProvider.getView() für die Darstellung der Benutzeroberfläche einzustellen.

Offene Fragen

  1. Gibt es häufigere Anwendungsfälle für Anzeigen-UIs, die von den UI-Bibliotheken automatisch verarbeitet werden sollten?
  2. Welche UI-Frameworks verwenden Sie zur Darstellung der Anzeigen-UI? Erwarten Sie Probleme bei der Integration der UI-Bibliotheken in diese Frameworks?
  3. Ist die Benutzeroberfläche für scrollbare Anzeigen in einem scrollbaren Publisher-Container ein häufiger Anwendungsfall? Wie ist in diesem Fall die Scrollrichtung für die Anzeigen-UI und den Container? Welches Verhalten erwarten Sie, wenn der Nutzer ein Scrollen auf der Anzeigen-UI startet?