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:
- 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.
- 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.
- 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 einSurfacePackage
.) - 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.
- Synchronisiert die Größe der Anzeigen-UI und des Anzeigencontainers ohne für den Nutzer sichtbare Verzögerung.
- 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, eineSurfacePackage
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. - 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.
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.
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.
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.
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.
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:
- 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.
- 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 wieloadAd
an den Publisher zurückgegeben. Die MethodeopenSession()
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 denSandboxedUiAdapter.openSession
-Aufruf zurückgegeben. Damit kann die Clientbibliothek die Anzeigen-UI abrufen und das SDK über Änderungen an der API informieren. AlleSession
-Methoden sollten hier implementiert werden.
Der Publisher sollte Folgendes tun:
- Erstellen Sie ein
SandboxedSdkView
, entweder über XML oder programmatisch. - Hängen Sie
SandboxedSdkUiSessionStateChangedListener
anSandboxedSdkView
an, um Änderungen in der UI zu beobachten. - Hängen Sie ein vom SDK bereitgestelltes
SandboxedUiAdapter
anSandboxedSdkView
an. - Fügen Sie dem Fenster wie gewohnt
SandboxedSdkView
hinzu und lassen Sie die Clientbibliothek die UI-Sitzung mit dem SDK erstellen und verwalten. - 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 PublisherSandboxedSdkView
durch ein statisches Bild ersetzen oder aus seiner Ansichtshierarchie entfernen. - 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 SieorderProviderUiAboveClientUi
antrue
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
- Gibt es häufigere Anwendungsfälle für Anzeigen-UIs, die von den UI-Bibliotheken automatisch verarbeitet werden sollten?
- Welche UI-Frameworks verwenden Sie zur Darstellung der Anzeigen-UI? Erwarten Sie Probleme bei der Integration der UI-Bibliotheken in diese Frameworks?
- 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?