Vermittlungsunterstützung in der SDK-Laufzeit

Die Vermittlung ist eine gängige Methode für Anzeigenplattformen auf Verkäuferseite, um die Ertragsverwaltung anzubieten. In einem Vermittlungsworkflow 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 der Mediator als auch die von ihm aufgerufenen Werbenetzwerke ihre SDKs auf dem Gerät haben und miteinander interagieren.

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

• Unterschiede zwischen früheren Vermittlungsabläufen und der aktuellen SDK-Laufzeit-Vermittlung
• Aktionen für Vermittlungsworkflows in der SDK-Laufzeit und die verschiedenen Phasen der Umstellung einrichten
• Anleitung für Szenarien, in denen nicht alle SDKs zur Runtime migriert wurden

Die Unterstützung für vermittelte Anzeigen in der SDK-Laufzeit ist ab AGP 8.5 und in 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 für das Verständnis der Vermittlung in der SDK-Laufzeit:

• Laufzeitfähiges SDK (Runtime-enabled SDK, RE SDK): Ein SDK, das in der SDK Runtime-Umgebung ausgeführt wird und über die interprozedurale Kommunikation (Inter-Process Communication, IPC) mit der App kommuniziert.
• Laufzeitbewusstes SDK (Runtime-Aware SDK, RA SDK): Ein nicht laufzeitfähiges SDK, das statisch mit der App verknüpft ist und Ihren vorhandenen SDK-Code sowie neuen Code enthalten kann, der in Ihr laufzeitfähiges SDK aufgerufen wird.
• In-App-SDK:Ein SDK, das statisch mit der App verknüpft ausgeführt wird und die SDK-Laufzeit nicht kennt. Das kann ein Anzeigennetzwerk sein, das noch nicht auf die SDK-Laufzeit umgestellt hat, oder der benutzerdefinierte Adapter eines Publishers.
• Vermittlungsdienstleister: SDK für die Anzeigenbereitstellung, das einen Vermittlungsdienst auf dem Gerät bereitstellt, indem es mit anderen SDKs von Werbenetzwerken interagiert.
• Mediatee:SDK des Werbenetzwerks, das vom Mediator aufgerufen wird, um eine Anzeige bereitzustellen und zu rendern.
• Vermittlungsadapter: SDKs, die vom Mediator SDK verwendet werden, um eine API-Schnittstellenübersetzung für die Interkonnektivität mit verschiedenen SDKs von vermittelten Publishern bereitzustellen. Sie werden in der Regel vom Vermittler bereitgestellt. Diese können laufzeitabhängig oder laufzeitunabhängig sein.

Typische Vermittlungsabläufe

Wenn Ihr SDK Vermittlungsfälle in der SDK-Laufzeit unterstützen muss, müssen Sie einige Änderungen implementieren. In diesem Abschnitt werden die wichtigsten Elemente von Vermittlungsabläufen beschrieben, damit wir die erforderlichen Änderungen für Vermittler und vermittelte Nutzer angehen können.

Die 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 erforderlichen Änderungen, um Vermittlungsabläufe mit der SDK-Laufzeit kompatibel zu machen.

Aufgrund der unterschiedlichen Implementierungen von Vermittlungsabläufen konzentrieren wir uns auf die folgenden beiden Hauptabläufe:

• Initialisierung (einschließlich Erkennen von Werbenetzwerken und Kommunikation)
• Präsentation der Benutzeroberfläche von Anzeigen

Initialisierung

Im Folgenden wird eine Standardinitialisierung, die Erkennung von Werbenetzwerken und der Kommunikationsablauf dargestellt:

1. Die Client-App initiiert den Mediator
2. Der Mediator erkennt und initialisiert die relevanten Mediaten und Adapter.
3. Der Vermittler verwendet seine Adapter, um mit den einzelnen vermittelten Publishern zu kommunizieren.
4. Die Client-App fordert den Mediator auf, eine Anzeige zu laden.
5. Die Client-App fordert den Vermittler auf, diese Anzeige zu schalten.

Hinweis: Bei diesem Ablauf wird davon ausgegangen, dass die Client-App vom Mediator-SDK, den SDKs der vermittelten Publisher und den Vermittlungsadaptern abhängig ist und mit diesen erstellt wurde.

Präsentation der Anzeigen-UI

Wie die Anzeige nach der letzten Anfrage im vorherigen Schritt gerendert wird, hängt von der Art der Anzeige ab:

Banneranzeigen	Vollbildanzeigen	Native Anzeigen
Das Mediator-SDK erstellt eine Anzeigenansicht, die die Anzeigenansicht des ausgewählten Mediators umschließt. Es kann auch Listener für diese Datenansicht festlegen oder die Anzeige automatisch aktualisieren (mit demselben oder einem anderen Mediator).	Das Mediator-SDK fordert vom vermittelten Publisher eine Full-Screen-Anzeige an, die wiederum eine Aktivität startet.	Der Publisher verwaltet die Ansichtsverwaltung und -aufblähung mithilfe von Komponenten, die vom Mediator-SDK zurückgegeben werden.

Vermittlungsabläufe in der SDK-Laufzeit

Die Funktionsweise der Vermittlung innerhalb der SDK-Laufzeit unterscheidet sich je nachdem, ob der vermittelte Publisher die Laufzeit aktiviert hat oder nicht. Daraus ergeben sich die folgenden Szenarien:

• Sowohl der Vermittler als auch das vermittelte Element befinden sich in der SDK-Laufzeit: RE mediatee
• Der Mediator befindet sich in der SDK-Laufzeit und der Mediatee ist in der App: In-App-Mediatee

RE Mediatee

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

Vermittlungsadapter müssen sich im selben Prozess wie der vermittelte Publisher befinden, mit dem sie verbunden sind. Daher müssen sie auch zur SDK-Laufzeit migriert werden.

Abbildung 1. Sowohl der Mediator als auch der Mediatee sind RE-SDKs.

Initialisierung

Bei der Initialisierung, Erkennung und Kommunikation sowohl des runtime-fähigen Mediators als auch des Mediaten erfolgt der Ablauf in folgenden Schritten:

1. Die App (oder das RA SDK) lädt und initialisiert das Mediator SDK mit SdkSandboxManager#loadSdk.
2. Während der Initialisierung lädt und initialisiert das Mediator-SDK alle erforderlichen Mediatoren in der SDK-Laufzeit mit SdkSandboxController#loadSdk.
3. Das RE SDK kann alle geladenen SDKs in der Laufzeit ermitteln, indem es SdkSandboxController#getSandboxedSdks aufruft.

Abbildung 2: Ablauf zum Initialisieren eines RE-Mediators.

Hinweis :Verwenden Sie die Klassen „*Compat Runtime Manager“ und „Controller“, damit Ihr runtime-fähiges SDK rückwärtskompatibel ist.

Präsentation der Anzeigen-UI

Im folgenden Abschnitt wird beschrieben, wie Banner und Vollbildanzeigen aus einem RE-Media-Element geladen werden.

RE Mediatee-Banneranzeigen

Wenn die App eine Banneranzeige lädt, erfolgt das Rendering so:

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

Abbildung 3 Ablauf zum Rendern einer Banneranzeige aus einem RE-Vermittlungspartner.

Weitere Informationen zur Verwendung von SandboxedUiAdapter und der SDK Runtime UI Library

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 einem Overlay und einem SandboxedSdkView.
2. Der Vermittler wählt den Gewinner für diese Anzeige aus.
3. Der Mediator erhält eine SandboxedUiAdapter vom Mediaten.
4. Der Vermittler setzt die UiAdapter des Vermittelten auf die SandboxedSdkView.
5. Der Mediator gibt die ausgefüllte Ansicht für die App frei.

Ablauf zum Überlagern einer Ansicht über eine Banneranzeige, die von einem RE Mediatee abgerufen wurde.

RE Mediatee-Vollbildanzeigen

Wenn die App eine Vollbildanzeige lädt, erfolgt der Ablauf so:

1. Die App (oder das RA SDK) übergibt dem Vermittler die SdkActivityLauncher mit der Aufforderung, eine Anzeige zu laden.
   1. Der Kunde kann die Erstellung von Aktivitäten mithilfe eines Prädikats einschränken.
2. Der Vermittler wählt den Gewinner für diese Anzeige aus.
3. Der Vermittler fordert den Vermittelten auf, eine Anzeige zu laden, und gibt dabei die SdkActivityLauncher aus der App weiter.
4. Der Vermittler registriert einen Aktivitäts-Handler und erhält ein Kennungstoken für die registrierte Aktivität.
5. Der Vermittler verwendet 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 entsprechenden Prozess.

Abbildung 4 Flussdiagramm, das veranschaulicht, wie eine vermittelte Vollbildanzeige aus einem RE Mediatee geladen wird.

Hinweis: Alle Ereignisse des Aktivitätszyklus sind für den Mediaten über die ActivityHolder verfügbar, die er bei der Registrierung des Aktivitäts-Handlers verwendet hat.

Weitere Informationen zur Aktivitätsunterstützung 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 vermittelten Publisher, die statisch mit der App verknüpft sind (auch ohne Laufzeitinformationen).

Abbildung 5. Der Mediator ist statisch mit der App verknüpft, auch wenn er das RE SDK kennt.

Initialisierung

Da in diesem Szenario die vermittelten Produkte statisch mit der App verknüpft und noch nicht zur SDK-Laufzeit migriert sind, sollte das runtimefähige SDK des Vermittlers einen Prozess zur Registrierung dieser Produkte haben.

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

Bei der Initialisierung, Suche und Kommunikation eines RE-Mediator SDKs und In-App-Mediatee SDKs gehen Sie so vor:

1. Die App lädt und initialisiert das runtime-aware SDK des Mediators.
2. RA SDK des Vermittlers:
   1. Initialisiert das RE SDK des Vermittlers mit SdkSandboxManager#loadSdk.
   2. Initialisiert alle In-App-Mediated-SDKs.
   3. Er erkennt und registriert die In-App-Mediation-SDKs mithilfe der API, die vom RE SDK MediationSandboxedSdk#registerInAppMediate bereitgestellt wird.

Neben der Registrierung aller In-App-Mediated SDKs kann das RE SDK des Vermittlers alle SDKs erkennen, die mit SdkSandboxController#getSandboxedSdks in der SDK Runtime geladen werden.

Abbildung 6: Hinweis: Wir verwenden die API des vorgeschlagenen Vermittlers, um die Referenz auf In-App-Vermittlungen zu registrieren.

Präsentation der Anzeigen-UI

Im folgenden Abschnitt erfahren Sie, wie Sie Banner und Vollbildanzeigen aus einem In-App-Media-Tee laden.

In-App-gemittelte Banneranzeigen

Wenn die App eine Banneranzeige lädt, erfolgt das Rendering so:

1. Das runtime-fähige SDK des Vermittlers leitet die Anfrage der App an sein runtime-fähiges SDK weiter.
2. Der Mediator wählt mit seinem RE SDK den entsprechenden Mediaten aus.
3. Das RE SDK des Vermittlers ruft die Referenz auf den vermittelten Publisher ab und fordert das Laden einer Anzeige über das RA SDK an.
4. Das RA SDK ruft eine Datenansicht vom In-App-Vermittlungspartner ab.
5. Das RA SDK erstellt eine SandboxedUiAdapter für die empfangene Ansicht.
6. Das RA SDK leitet die UiAdapter an das RE SDK weiter.
7. Das RE SDK leitet die UiAdapter an die App weiter.

Achtung: Da diese SandboxedUiAdapter vom App-Prozess empfangen wird, empfehlen wir, dieser Ansicht keine Overlays hinzuzufügen, da dies zu Latenz-, Leistungs- und Verhaltensproblemen führen kann.

Abbildung 7. Der Vermittler darf keine Aufrufe auf V1 legen, wenn er sie von einem In-App-Abhängigen erhält.

In-App-gemittelte Vollbildanzeigen

Wenn die App eine Vollbildanzeige lädt, erfolgt der Ablauf so:

1. Die App übergibt dem RA SDK des Vermittlers die Zeichenfolge SdkActivityLauncher mit der Aufforderung, eine Anzeige zu laden.
   1. Der Kunde kann die Erstellung von Aktivitäten mithilfe eines Prädikats 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 die entsprechende Person aus, die vermittelt werden soll.
   2. Ruft die Referenz auf den In-App-Mediator ab.
   3. Anfragen zum Laden einer Anzeige über das RA SDK.
4. Das RA SDK fordert den vermittelten Publisher auf, eine Anzeige zu laden.
5. Der Teilnehmer startet die Aktivität direkt. Das Prädikat der App wird nicht berücksichtigt.

Abbildung 8 Das Prädikat wird vom In-App-Vermittlungspartner ignoriert.

Hinweis: Alle Ereignisse im Zusammenhang mit der Aktivität sind für den Mediaten wie vor der SDK-Laufzeit verfügbar.

Mit Nutzern interagieren und Feedback geben

Die Privacy Sandbox für Android ist ein fortlaufendes Projekt. Dieses Dokument spiegelt das aktuelle Design wider. Ihr Feedback ist uns wichtig, damit wir die Funktionen weiter entwickeln und verbessern können. Melden Sie einen Fehler, um Feedback zu geben.