Vermittlungsunterstützung in der SDK-Laufzeit

Die Vermittlung ist eine gängige Methode für Sell-Side-Anzeigenplattformen, um Ertragsmanagement anzubieten. Bei der Vermittlung ruft das Vermittlungs-SDK („Mediator“) mehrere Werbenetzwerke („Mediatee“ oder „Mediatees“) auf, um die beste Anzeige für einen bestimmten Slot zu erhalten. In einigen Fällen müssen sowohl das Vermittler- als auch die aufgerufenen Werbenetzwerke ihre SDKs auf dem Gerät haben und interagieren.

In diesem Dokument werden die wichtigsten Änderungen an den Vermittlungsworkflows in der SDK-Laufzeit beschrieben. Es deckt folgende Themenbereiche ab:

• Unterschiede zwischen den bisherigen Vermittlungsabläufen und der aktuellen SDK Runtime-Vermittlungsunterstützung
• Aktionen für Vermittlungsworkflows in der SDK-Laufzeit und die verschiedenen Übergangsphasen einrichten
• Anleitung zum Umgang mit Szenarien, in denen nicht alle SDKs zur Laufzeit migriert wurden

Die Unterstützung für vermittelte Anzeigen in der SDK-Laufzeit ist ab AGP 8.5 und ab den folgenden Versionen der SDK-Laufzeit-Jetpack-Bibliotheken verfügbar:

AndroidX-Bibliothek	Version
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

Glossar

Die folgenden Begriffe sind wichtig, um die Vermittlung in der SDK-Laufzeit zu verstehen:

• Laufzeitfähiges SDK (RE SDK): Ein SDK, das für die Ausführung in der SDK Runtime-Umgebung entwickelt wurde und über die Interprozesskommunikation (IPC) mit der App kommuniziert.
• Laufzeitfähiges SDK (RA-SDK): Ein nicht laufzeitfähiges SDK, das statisch mit der App verknüpft ist und das Ihren vorhandenen SDK-Code sowie neuen Code zum Aufrufen Ihres laufzeitfähigen SDKs enthalten kann.
• In-App-SDK:Ein SDK, das statisch mit der App verknüpft ist und keine Informationen zur SDK-Laufzeit hat. Das kann ein Anzeigennetzwerk sein, das noch nicht auf SDK Runtime umgestellt wurde, oder ein benutzerdefinierter Adapter eines Publishers.
• Mediator:SDK für die Anzeigenvermittlung, das auf dem Gerät einen Vermittlungsdienst bereitstellt, indem es mit anderen SDKs von Werbenetzwerken interagiert.
• Vermittlungsnetzwerk:SDK des Werbenetzwerks, das vom Vermittler aufgerufen wird, um eine Anzeige bereitzustellen und zu rendern.
• Mediationsadapter:SDKs, die vom Mediator-SDK verwendet werden, um die API-Schnittstelle für die Zusammenarbeit mit verschiedenen Mediatee-SDKs bereitzustellen. Sie werden in der Regel vom Mediator bereitgestellt. Diese können laufzeitbezogen oder laufzeitunabhängig sein.

Typische Vermittlungsabläufe

Wenn Ihr SDK Vermittlungsanwendungsfälle in der SDK-Laufzeit unterstützen muss, sind einige Änderungen erforderlich. In diesem Abschnitt werden die wichtigsten Elemente von Vermittlungsabläufen erläutert, damit wir die erforderlichen Änderungen für Vermittler und Vermittelte berücksichtigen können.

Die von uns beschriebenen Abläufe stellen eine vereinfachte Version der On-Device-Vermittlung mit mehreren SDKs von Werbenetzwerken dar und dienen als Grundlage für die Diskussion über die Änderungen, die erforderlich sind, um Vermittlungsvorgänge mit der SDK-Laufzeitumgebung kompatibel zu machen.

Angesichts der unterschiedlichen Implementierungen des Vermittlungsablaufs konzentrieren wir uns auf die folgenden beiden Hauptabläufe:

• Initialisierung (einschließlich der Ermittlung von Werbenetzwerken und der Kommunikation)
• Darstellung der Benutzeroberfläche für Anzeigen

Initialisierung

Das Folgende zeigt eine Standardinitialisierung, die Erkennung von Werbenetzwerken und den Kommunikationsablauf:

1. Die Client-App initiiert den Mediator.
2. Der Mediator ermittelt und initialisiert die relevanten Mediatees und Adapter.
3. Der Mediator verwendet seine Adapter, um mit jedem Mediatee zu kommunizieren.
4. Die Client-App fordert den Mediator auf, eine Anzeige zu laden.
5. Die Client-App fordert den Mediator auf, diese Anzeige zu präsentieren.

Anzeigen-UI-Präsentation

Beim Rendern der Anzeige nach der letzten Anfrage im vorherigen Schritt hängt der Ablauf vom Anzeigentyp ab:

Banneranzeigen	Vollbildanzeigen	Native Anzeigen
Das Mediator-SDK erstellt eine Anzeigenansicht, die die Anzeigenansicht des Gewinner-Mediatee umschließt. Es kann auch Listener für diese View festlegen oder die Anzeige automatisch aktualisieren (mit demselben oder einem anderen Mediatree).	Das Mediator-SDK fordert eine Vollbildanzeige vom Mediatee an, der wiederum eine Aktivität startet.	Der Publisher verwaltet die Ansichtshandhabung und das Einblenden mithilfe von Komponenten, die vom Mediator-SDK zurückgegeben werden.

Vermittlungsabläufe in der SDK-Laufzeit

Die Funktionsweise der Vermittlung in der SDK-Laufzeit hängt davon ab, ob das zu vermittelnde SDK für die Laufzeit aktiviert ist oder nicht. Daraus ergeben sich die folgenden Szenarien:

• Sowohl Mediator als auch Mediatee befinden sich in der SDK-Laufzeit: RE-Mediatee
• Der Mediator befindet sich in der SDK Runtime und das Mediatee in der App: In-App-Mediatee

RE Mediatee

Das folgende Architekturdiagramm bietet einen allgemeinen Überblick über die Interaktion der Laufzeit-fähigen (RE) und Laufzeit-kompatiblen (RA) SDKs des Vermittlers, der RE-Vermittlungsadapter und der RE-SDKs der Mediatees.

Mediationsadapter müssen sich im selben Prozess wie das Mediatee befinden, mit dem sie interagieren. Daher müssen sie auch zur SDK-Laufzeit migriert werden.

Initialisierung

Bei der Initialisierung, Erkennung und Kommunikation sowohl des Mediator- als auch des Mediatee-Moduls, die zur Laufzeit aktiviert werden, wird der folgende Ablauf durchlaufen:

1. Die App (oder das RA SDK) lädt und initialisiert das Mediator-SDK mit SdkSandboxManager#loadSdk.
2. Bei der Initialisierung lädt und initialisiert das Mediator-SDK alle erforderlichen Mediatees in der SDK-Laufzeit mit SdkSandboxController#loadSdk.
3. Mit dem RE SDK können alle geladenen SDKs in der Laufzeit durch Aufrufen von SdkSandboxController#getSandboxedSdks ermittelt werden.

Anzeigen-UI-Präsentation

Im folgenden Abschnitt wird beschrieben, wie Banner und Vollbildanzeigen von einem RE-Mediatee geladen werden.

RE Mediatee-Banneranzeigen

Wenn in der App eine Banneranzeige geladen werden soll, läuft der Rendering-Vorgang so ab:

1. Der Vermittler wählt den Gewinner-Mediatee für diese Anzeige aus.
2. Der Mediator erhält ein SandboxedUiAdapter vom Mediatee.
3. Der Mediator leitet den UiAdapter an die App weiter.

Weitere Informationen zur Verwendung von SandboxedUiAdapter und der SDK-Laufzeit-UI-Bibliothek

Overlays für Banneranzeigen

Wenn Vermittler der Anzeige ein Overlay hinzufügen möchten, müssen sie den Ablauf so ändern:

1. Der Mediator erstellt ein Layout mit seinem Overlay und einem SandboxedSdkView.
2. Der Vermittler wählt den Gewinner-Mediatee für diese Anzeige aus.
3. Der Mediator ruft ein SandboxedUiAdapter vom Mediatee ab.
4. Der Mediator legt die UiAdapter des Mediatee auf die SandboxedSdkView fest.
5. Der Vermittler gibt die Ansicht mit den Daten an die App weiter.

RE Mediatee-Vollbildanzeigen

Wenn die App eine Anfrage zum Laden einer Vollbildanzeige sendet, wird der folgende Ablauf ausgeführt:

1. Die App (oder das RA SDK) übergibt ein SdkActivityLauncher an den Vermittler mit der Anfrage, eine Anzeige zu laden.
   1. Der Client kann die Erstellung von Aktivitäten mit einem Prädikat einschränken.
2. Der Vermittler wählt den Gewinner-Mediatee für diese Anzeige aus.
3. Der Mediator fordert den Mediatee auf, eine Anzeige zu laden, und übergibt dabei die SdkActivityLauncher aus der App.
4. Der Mediatee registriert einen Aktivitätshandler und erhält ein ID-Token für die registrierte Aktivität.
5. Der Mediatee verwendet den SdkActivityLauncher, um den Start einer Aktivität mit diesem Token anzufordern.
6. Wenn das Prädikat der Client-App dies zulässt, startet die SDK-Laufzeit diese Aktivität im dedizierten Prozess.

Weitere Informationen zur Unterstützung von Aktivitäten für Vollbildanzeigen in der SDK-Laufzeit

In-App-Mediatee

Das folgende Architekturdiagramm bietet einen allgemeinen Überblick über die Interaktion der RE- und RA-SDKs des Vermittlers, der Vermittlungsadapter, die die SDK-Laufzeit nicht kennen, und der SDKs der Mediatees, die statisch mit der App verknüpft sind (ebenfalls laufzeitunabhängig).

Initialisierung

Da in diesem Szenario die zu vermittelnden SDKs statisch mit der App verknüpft sind und noch nicht zur SDK-Laufzeit migriert wurden, sollte das laufzeitfähige SDK des Vermittlers einen Prozess zur Registrierung enthalten.

Diese Registrierung sollte über die API des Vermittlers zugänglich sein. Die Implementierungsdetails liegen jedoch im Ermessen des jeweiligen Vermittlers. Diese API wird als MediationSandboxedSdk#registerInAppMediatee bezeichnet.

Bei der Initialisierung, Erkennung und Kommunikation eines RE-Mediator-SDK und von In-App-Mediatee-SDKs wird der folgende Ablauf durchlaufen:

1. Die App lädt und initialisiert das Mediator-SDK, das die Laufzeit berücksichtigt.
2. RA-SDK des Vermittlers:
   1. Initialisiert das RE SDK des Vermittlers mit SdkSandboxManager#loadSdk.
   2. Initialisiert alle In-App-Mediatee-SDKs.
   3. Ermittelt und registriert die In-App-Mediatee-SDKs über die API, die vom RE SDK bereitgestellt wird: MediationSandboxedSdk#registerInAppMediate.

Neben der Registrierung aller In-App-Mediation-SDKs kann das RE-SDK des Vermittlers alle in der SDK Runtime geladenen SDKs mit SdkSandboxController#getSandboxedSdks erkennen.

Anzeigen-UI-Präsentation

Im folgenden Abschnitt wird beschrieben, wie Banner und Vollbildanzeigen aus einem In‑App-Mediation-Partner geladen werden.

Banneranzeigen von Media-Mediatoren in Apps

Wenn in der App eine Banneranzeige geladen werden soll, läuft der Rendering-Vorgang so ab:

1. Das laufzeitfähige SDK des Vermittlers leitet die Anfrage der App an sein laufzeitfähiges SDK weiter.
2. Das RE SDK des Vermittlers wählt den relevanten Mediatie aus.
3. Das RE SDK des Vermittlers ruft den Verweis auf das Mediatee ab und fordert das Laden einer Anzeige über das RA SDK an.
4. Das RA SDK ruft eine View vom In-App-Mediatee ab.
5. Das RA SDK erstellt ein SandboxedUiAdapter für die empfangene View.
6. Das RA SDK leitet UiAdapter an das RE SDK weiter.
7. Das RE SDK leitet UiAdapter an die App weiter.

Vollbildanzeigen für In-App-Mediatee

Wenn die App eine Anfrage zum Laden einer Vollbildanzeige sendet, wird der folgende Ablauf ausgeführt:

1. Die App übergibt ein SdkActivityLauncher an das RA SDK des Vermittlers mit der Anfrage, eine Anzeige zu laden.
   1. Der Client kann die Erstellung von Aktivitäten mit einem Prädikat einschränken.
2. Das RA SDK des Vermittlers leitet die Anfrage der App an sein RE SDK weiter.
3. RE SDK des Vermittlers:
   1. Wählt den relevanten Rechtssubjekt aus.
   2. Ruft die Referenz zum In-App-Mediatee ab.
   3. Anfragen zum Laden einer Anzeige über das RA SDK.
4. Das RA SDK fordert das Mediatee auf, eine Anzeige zu laden.
5. Der Nutzer startet die Aktivität direkt. Das Prädikat der App wird nicht berücksichtigt.

Feedback geben

Die Privacy Sandbox für Android ist ein laufendes Projekt und dieses Dokument spiegelt das aktuelle Design wider. Ihr Feedback ist uns wichtig, damit wir die Funktionen weiterentwickeln und verbessern können. Reichen Sie einen Fehlerbericht ein, um Feedback zu geben.