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 einzublenden, Plattform stellt dem SDK eine SandboxedSdkProvider.getView API zur Verfügung, um eine Anzeige zu erhalten und fasst es als SurfacePackage zusammen, das über IPC gesendet wird. Kommunikation zwischen Prozessen und der Clientanwendung. Das hat mehrere Nachteile, die unten beschrieben werden. In diesem Dokument wird dann ein vorgeschlagener Jetpack-Bibliothek, 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. Diese Seite Kanal:

  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. Abstrahiert die zugrunde liegenden Plattformkonstrukte, die zur Darstellung der UI für Prozesse. (Die Plattform verwendet derzeit SurfaceControlViewhost und generiert daraus ein SurfacePackage.)
  4. Aktiviert Anzeigen-SDKs in der SDK Runtime, um automatisch Benachrichtigungen zu erhalten 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 Größenänderungen der Anzeigen-Benutzeroberfläche und des Anzeigencontainers ohne für den Nutzer sichtbare Verzögerung.
  6. Verwaltet die Abwärtskompatibilität automatisch. SurfacePackage ist nicht vor API-Level 30 verfügbar. Außerdem können Sie auf Geräten, auf denen kein SDK vorhanden ist, und das SDK ist für den Publisher prozessbezogen. Es verschwendet Erstellen eines SurfacePackage für eine Anzeige, wenn ein Aufruf direkt über des SDK. Der Seitenkanal abstrahiert diese Komplexität von SDK und App weg. Entwicklercode.
  7. Ermöglicht die nahtlose Integration der Anzeigen-UI 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 Side-Channel, über den der Publisher und das SDK die Benutzeroberfläche prozessübergreifend präsentieren können. aktualisiert werden, wenn der Nutzer damit und mit dem Gerät interagiert.

Es gibt drei UI-Bibliotheken: core, client und provider. Kernbibliothek stellt die von Client- und Anbieterbibliotheken verwendeten Schnittstellen bereit. Der UI-Anbieter (in der Regel das SDK) hängt von der Anbieterbibliothek und dem Nutzer der Benutzeroberfläche ab. (in der Regel der Publisher) von der Clientbibliothek abhängt. Gemeinsam hat der Kunde und Anbieterbibliotheken den Nebenkanal bilden, der für die Erstellung und und Pflegen einer UI-Sitzung.

Die APIs

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

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

SandboxedSdkView: Dieser Container wird vom Publisher erstellt und enthält Inhalte, die über die SandboxedUiAdapter erhalten wurden.

Session: Wird vom SDK als Reaktion auf den SandboxedUiAdapter.openSession(). 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: Wird von der Clientbibliothek erstellt und bildet das Publisher-Ende des Kommunikationstunnels zwischen dem SDK und dem Publisher.

SandboxedSdkUiSessionStateChangedListener: Vom Publisher erstellt A Listener für Statusänderungen der UI-Sitzung, die mit SandboxedSdkView

Abbildung, die die Beziehungen zwischen SDK Runtime UI-Darstellungs-APIs zeigt
Beziehungen zwischen den SDK Runtime UI-Präsentations-APIs

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

Ablauf steuern

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 Prozess für offene Sitzungen 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 z. B. ausgelöst werden, wenn der Nutzer das Gerät dreht und der Publisher erklärt, Konfigurationsänderungen in ihrer Aktivität, indem sie android:configChanges=["orientation"]

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 anpassen möchte und der Publisher muss die Größe des Anzeigencontainers anpassen, damit Dimensionen. Dies kann als Reaktion auf Nutzerinteraktionen passieren, z. B. mraid.resize()

Vom SDK initiierte UI-Änderung

Dieses Diagramm zeigt, wie die Sitzung geschlossen wird, wenn die SandboxedSdkView getrennt ist aus dem Fenster. Die Sitzung kann auch jederzeit geschlossen werden (z.B. wenn der Nutzer durch den Aufruf der Netzwerkverbindung) durch das SDK SessionClient.onSessionError()

Die UI-Sitzung schließen

Z-Reihenfolge

Die Client-UI-Bibliothek verwendet intern einen SurfaceView, um die SDK-UI zu hosten. In SurfaceView kann die Benutzeroberfläche in der Reihenfolge Z verwendet werden, um entweder die Benutzeroberfläche des Publishers oder darunter befinden. Dies wird über die Methode SandboxedSdkView.orderProviderUiAboveClientUi() gesteuert, die einen booleschen setOnTop akzeptiert.

Wenn setOnTop = true ist, werden alle android.view.MotionEvent in der SandboxedSdkView an das SDK gesendet. Wenn false, werden diese an den Publisher. Standardmäßig werden Bewegungsereignisse an das SDK gesendet.

Publisher müssen die standardmäßige Z-Reihenfolge der Anzeigenansichten in der Regel nicht ändern. Wenn jedoch eine Benutzeroberfläche angezeigt wird, die eine Anzeige verdeckt, wie etwa ein Dropdown-Menü, Die Z-Reihenfolge sollte vorübergehend von der Standardeinstellung umgedreht und dann wiederhergestellt werden, wenn Das abzudeckende UI-Element wird geschlossen. Wir arbeiten daran, diesen Prozess in der Client-UI-Bibliothek zu automatisieren.

Scrollen

Wenn die Anzeigen-UI von Z nach oben über dem Publisher-Fenster angeordnet ist, wird MotionEvents von der an das SDK gesendet werden. Scroll- und Kippgesten, die auf der Anzeigen-Benutzeroberfläche Sonderbehandlung:

  1. Vertikale Scroll- und Fling-Gesten werden an das Team des Publishers gesendet und von diesen gesteuert. Container. Dies sorgt für eine gute Nutzererfahrung, wenn der Container des Publishers, in dem die Anzeigen-UI platziert ist, vertikal scrollbar ist. Hierfür sind keine zusätzlichen die am SDK oder dem Publisher arbeiten.
  2. Horizontales Scrollen und Wischgesten werden an das SDK gesendet und dort verarbeitet. Dieses eine gute Nutzererfahrung bietet, wenn die Benutzeroberfläche selbst horizontal scrollbar ist (z. B. im Anzeigenkarussell).

Implementierungsleitfaden

Das SDK sollte Folgendes implementieren:

  • SandboxedUiAdapter: Wird dem Publisher als Antwort auf eine SDK-definierte API wie loadAd zurückgegeben. Die openSession()-Methode dieses Implementierung, um eine Anzeigenanfrage an die SDK-Server und einen Anzeigenaufruf für diese Anfrage vorbereiten.
  • Session**: Wird als Antwort auf den Anruf in SandboxedUiAdapter.openSession. Sie bietet dem Kunden die Möglichkeit, um die Anzeigen-Benutzeroberfläche zu erhalten und das SDK über Änderungen an dieser API zu informieren. Hier sollten alle Session-Methoden implementiert werden.

Der Verlag oder Webpublisher geht so vor:

  1. Erstellen Sie eine SandboxedSdkView, entweder über XML oder programmatisch.
  2. Fügen Sie dem SandboxedSdkView ein SandboxedSdkUiSessionStateChangedListener hinzu, um Änderungen an der Benutzeroberfläche zu beobachten.
  3. Hängen Sie ein von Ihnen bereitgestelltes SDK an die SandboxedSdkView an.
  4. Fügen Sie dem Fenster wie gewohnt SandboxedSdkView hinzu und lassen Sie die Clientbibliothek verwenden. erstellen und verwalten die UI-Sitzung mit dem SDK.
  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. Es wird häufig die Benutzeroberfläche für scrollbare Anzeigen in einem scrollbaren Publisher-Container verwendet. das richtige Argument für Sie? In welche Richtung wird in diesem Fall die Anzeigeoberfläche und der Container gescrollt? Welches Verhalten erwarten Sie, wenn der Nutzer auf der Anzeigen-UI scrollt?