Registrieren für die Anzeigenauswahl-API

Die Anzeigenauswahl-API stellt benutzerrelevante Werbung auf Ihrer Website bereit, ohne Cookies von Drittanbietern zu verwenden. Weitere Informationen finden Sie unter Übersicht über die Anzeigenauswahl im privacy-preserving-ads Repository.

Die Anzeigenauswahl-API kann verwendet werden von:

• Verkäufer , die eine angebotsseitige Plattform (Supply-Side Platform, SSP) ausführen, die die API verwenden können, um ihren Herausgebern qualitativ hochwertigere Anzeigen bereitzustellen.
• Käufer , die eine nachfrageseitige Plattform (Demand-Side Platform, DSP) betreiben, die die API verwenden können, um die Effektivität von Werbekampagnen zu verbessern.

Um mit der Verwendung der Anzeigenauswahl-API zu beginnen und den End-to-End-Flow zu testen, registrieren Sie sich für die eingeschränkte Vorschau der Anzeigenauswahl-API.

Als Verkäufer, der eine angebotsseitige Plattform betreibt, oder ein Käufer, der eine nachfrageseitige Plattform betreibt, verwenden Sie diesen Leitfaden für:

• Registrieren Sie sich für die eingeschränkte Vorschauversion der Ad Selection-API, indem Sie sich für die Ursprungstestversion registrieren.
• Schließen Sie den API-Nachweis ab, indem Sie ihre JSON-Datei für Nachweise veröffentlichen.
• Richten Sie eine Evaluierungsumgebung mit einem unterstützten Cloudanbieter ein.
• Sehen Sie sich die Dokumentation zur Anzeigenauswahl-API an.
• Bereiten Sie Ihre User-Defined Functions (UDFs) vor.
• Stellen Sie Ihre Dienste in Azure bereit.
• Testen Sie die Anzeigenauswahl-API auf Ihrer Website.

Nachweisregistrierung und Alpharegistrierung

Wann und wo ist die Vorschau verfügbar?

Microsoft Edge-Versionen ab 130.0.2808.0 unterstützen die Anzeigenauswahl-API in einer eingeschränkten Vorschauversion für Entwickler außerhalb des Europäischen Wirtschaftsraums (EWR) und des Vereinigten Königreichs (UK).

Flags für Tests

Um die Features der Ad Selection-API-Plattform auf Ihrem Entwicklercomputer zu ändern, verwenden Sie die Testflags der Ad Selection-API unter edge://flags#edge-ad-selection-api:

Das Api-Flag "Anzeigenauswahl" aktiviert die Anzeigenauswahl-API und die zugehörigen Features, z. B.:

• Zuordnungsberichte.
• Eingezäunte Rahmen.
• Freigegebener Speicher.
• Private Aggregation.

Registrierungs- und Nachweisanforderungen und -prozess

Entwickler, die an Alphatests interessiert sind, können an der Ursprungstestversion für die Anzeigenauswahl-API teilnehmen. Diese Ursprungstestversion ermöglicht end-to-End-Tests von Ad Selection-API-Features, die sowohl die API-Nutzung als auch die Bereitstellung sicherer Containerimages abdecken.

Füllen Sie für jede Domäne der obersten Ebene, die Sie mit der Anzeigenauswahl-API verwenden möchten, das Registrierungsformular für die Ursprungstestregistrierung für diese Domäne aus, und senden Sie dann das Formular.

So registrieren Sie sich für die Ad Selection-API-Ursprungstest für eine Domäne:

1. Öffnen Sie die Registrierung der Ad Selection API Origin Trial Registration in Microsoft Edge in einem neuen Fenster oder einer neuen Registerkarte.

2. Klicken Sie auf die Schaltfläche Jetzt starten .

3. Lesen Sie die Nutzungsbedingungen, stimmen Sie diesen zu, und klicken Sie dann auf die Schaltfläche Weiter . Das Formular für die Registrierung der Ad Selection API Origin Trial wird geöffnet:

   

4. Geben Sie im Textfeld Domäne eine einzelne Domäne der obersten Ebene ein:

   Sie können die Ursprungstestversion so konfigurieren, dass eine der folgenden Optionen unterstützt wird:

   • Eine einzelne Domäne, z https://example.com. B. , ohne die zugehörigen Unterdomänen zu unterstützen.
   • Eine einzelne Unterdomäne, z https://beta.example.com. B. .
   • Eine Domäne, z https://example.com. B. , und ihre Unterdomänen, z https://beta.example.com. B. .

   Nachfolgende Pfade und Abfrageparameter werden nicht unterstützt. Wenn ein URI eingegeben wird, der einen nachgestellten Pfad oder abfrageparameter wie https://example.com/path/new-featureaufweist, wird die Stammdomäne (z https://example.com. B. ) oder die Unterdomäne registriert, wobei nachfolgende Pfad- oder Abfrageparameter ignoriert werden.

5. Wählen Sie im Abschnitt Unterdomänenunterstützung die Optionsschaltfläche Ja oder Nein aus:

   • Wenn Sie die Ursprungstestversion in einer Domäne (z https://example.com. B. ) verwenden möchten, ohne deren Unterdomänen (z https://beta.example.com. B. ) zu unterstützen, wählen Sie Nein aus.
   • Wenn Sie die Ursprungstestversion nur für eine bestimmte Unterdomäne (z https://beta.example.com. B. ) verwenden möchten, wählen Sie Nein aus.
   • Wenn Sie die Ursprungstestversion in einer Domäne (z https://example.com. B. ) und der zugehörigen Unterdomänen (z https://beta.example.com. B. ) verwenden möchten, wählen Sie Ja aus.

6. Geben Sie im Textfeld Email Adresse einen gültigen Entwicklerkontakt für die Domäne an.

7. Klicken Sie auf die Schaltfläche Senden .

   Ein Ursprungstesttoken wird für die Domäne der obersten Ebene generiert und an Sie gesendet.

8. Erstellen Sie eine Datei mit dem Namen ad-selection-attestations.json, und hosten Sie die Datei in der Domäne der /.well-known/ obersten Ebene im Verzeichnis. Zum Beispiel:

   https://contoso.example/.well-known/ad-selection-attestations.json

   Die ad-selection-attestations.json Datei muss innerhalb von 30 Tagen nach Erhalt des OT-Tokens veröffentlicht werden. Das Hosten dieser JSON-Datei ist erforderlich, um den Nachweis abzuschließen und Ihrem Code den Zugriff auf die Anzeigenauswahl-API zu ermöglichen, um die Anzeigenauswahl-API mit unterstützten Microsoft Edge-Clients zu testen.

JSON-Beispieldatei

Die JSON-Datei des Nachweises muss den Namen haben ad-selection-attestations.jsonund den folgenden Standards entsprechen. Es folgt ein Beispiel für eine ad-selection-attestations.json Datei:

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}

Wichtige Felder und Werte

• Die ad-selection-attestations.json Datei muss das Ursprungstesttoken enthalten, das für diese Domäne der obersten Ebene generiert und an Sie gesendet wurde. "ownership_token": ist das Ursprungstesttoken, das beim Registrieren dieser Domäne für die Testversion des Ad Selection-API-Ursprungs generiert wurde.

• "platform_attestations": Im Abschnitt "platform": muss oder "android"sein"edge".

• Die Datei muss eine Liste von APIs (Features, die der Ad Services-API zugeordnet sind) enthalten. "platform_attestations": Im Abschnitt sind die folgenden gültigen Elemente von"attestations"::

  • "ad_selection_api":– Die Standard-API für private Auktionslogik.
  • "attribution_reporting_api": – Zuordnungsberichte.
  • "shared_storage_api": – Freigegebener Speicher.
  • "private_aggregation_api": – Private Aggregation.
  • Voraussetzungen:
    • Jeder "..._api": Eintrag muss ein einzelnes Feld ( "ServiceNotUsedForIdentifyingUserAcrossSites":) mit einem - oder false -trueWert aufweisen. true bedeutet, dass dieser Dienst nicht für die standortübergreifende Identifizierung des Benutzers verwendet wird. false bedeutet, dass dieser Dienst verwendet wird, um den Benutzer websiteübergreifend zu identifizieren.

Bereitstellen der Ad Selection-API-Dienste

Die Ad Selection-API verwendet eine vertrauenswürdige Ausführungsumgebung (Trusted Execution Environment, TEE), um ein Maß an Sicherheit für Datenintegrität, Datengeheimnis und Codeintegrität bereitzustellen. Siehe Confidential Computing: Hardware-Based Vertrauenswürdige Ausführung für Anwendungen und Daten. Dienste, die von der Anzeigenauswahl-API bereitgestellt werden, müssen in einer TEE ausgeführt werden, um die von diesen Diensten verwendeten Daten zu schützen.

Ad Selection Services, die in einer TEE ausgeführt werden, sollten auf einer Cloudplattform bereitgestellt werden, die die erforderlichen Sicherheitsfeatures unterstützt. Anfänglich können Dienste in Azure mithilfe vertraulicher ACI-Container bereitgestellt werden. Weitere Informationen finden Sie unter Vertrauliche Container auf Azure Container Instances.

Die Anzeigenauswahl-API bietet verschiedene Dienste, die von Verkäufern oder Käufern bereitgestellt werden müssen.

Images für die Bereitstellung von Diensten

Fügen Sie Ihre User-Defined Functions (UDFs) innerhalb der bereitgestellten Images von Diensten hinzu. Die User-Defined Functions kann benutzerdefinierte Geschäftslogik ausführen. Die User-Defined Functions werden in privaten Containern innerhalb der bereitgestellten Dienste ausgeführt.

Jedes Image definiert einen Dienst. Einige Bilder enthalten keine UDFs und bestehen vollständig aus vordefiniertem Code. Einige Bilder enthalten UDFs als Funktionen mit einem leeren Text oder Startercode, die die relevanten User-Defined Functions für diesen Dienst sind. Füllen Sie die Textkörper der User-Defined Functions in diesen Bildern mit Ihrem eigenen benutzerdefinierten Code aus.

Microsoft stellt für jeden Dienst ein Image bereit, das auf einem Cloudanbieter bereitgestellt werden kann. Dies sind die öffentlichen Images, die für die Bereitstellung verwendet werden müssen. Nur offizielle Bilder von Microsoft können private Auktionen durchführen.

Images für die Bereitstellung:

• Verkäufer
  • Front-End-Dienst für Den Verkäufer für die Anzeigenauswahl
  • Anzeigenauswahl-Auktionsdienst
• Käufer
  • Ad Selection Buyer Front-End-Service
  • Anzeigenauswahl-Gebotsdienst
  • Anzeigenauswahl K-Anonymitätsdienst
• Verkäufer und Käufer
  • Schlüsselwertdienst für die Anzeigenauswahl

Dienstleistungen für Verkäufer

Dienst	Beschreibung
SellerFrontEnd	Stellt einen /SelectAd HTTPS-Endpunkt bereit, der Anforderungen vom nicht vertrauenswürdigen Anzeigendienst des Verkäufers empfängt, um den Auktionsablauf für geschützte Zielgruppen zu initiieren.
Versteigerung	Stellt einen /ScoreAds Endpunkt bereit, der Anforderungen vom SellerFrontEnd-Dienst empfängt und Gebote enthält, die an der Auktion teilnehmen. Antwortet mit einem Bewertungswert, den der SellerFrontEnd-Dienst verwendet, um den Gewinner auszuwählen.
Schlüssel/Wert	Empfängt Anforderungen vom SellerFrontEnd-Dienst , die Nachschlageschlüssel aus Käufergeboten enthalten (z ad_render_urls. B. ). Gibt Echtzeitbewertungssignale zurück, die für die Auktion erforderlich sind. Wird im BYOS-Modus (Bring Your Own Service) ausgeführt, sodass der Verkäufer diesen Dienst nicht in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) bereitstellen muss und stattdessen das von Microsoft bereitgestellte Image verwenden kann.

Dienstleistungen für Käufer

Dienst	Beschreibung
BuyerFrontEnd	Stellt einen /GetBids Endpunkt bereit, der Anforderungen vom SellerFrontEnd-Dienst empfängt, um den Gebotsfluss zu initiieren.
Gebot	Stellt einen /GenerateBids Endpunkt bereit, der Anforderungen vom BuyerFrontEnd-Dienst empfängt, um das Gebot zu verarbeiten und ein Gebot zu generieren. Generiert ein Gebot, wählt den Gewinner aus und wählt das banner aus, das gerendert werden soll.
Schlüssel/Wert	Empfängt Anforderungen vom BuyerFrontEnd-Dienst und gibt Echtzeit-Käuferdaten zurück, die für das Gebot erforderlich sind, die Suchschlüsseln von Interest Gruppen entsprechen. Eine solche Anforderung erfolgt einmal pro Workflow. Wird im BYOS-Modus (Bring Your Own Service) ausgeführt.
Gebotsauswahl & Schlüssel/Wert	Empfängt Anforderungen vom Gebotsdienst , zusätzliche Werbebanner (Kandidaten) auszuwählen und zurückzugeben, die an Geboten teilnehmen können. Die Gebotsauswahl & Schlüssel-Wert-Dienst kann auch zusätzliche Signale zurückgeben, die für das Gebot erforderlich sind. Der Gebotsdienst kann mehrere Anforderungen an den Angebotsauswahl-& Schlüssel-Wert-Dienst senden oder keine Anforderungen senden, da die Gebotsauswahl & Schlüssel-Wert-Dienst optional ist. Die Gebotsauswahl & Schlüssel-Wert-Dienst muss in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) bereitgestellt werden.
K-Anonymität	Sammelt k-Anonymitätszähler und überprüft, ob das werbefinanzierte Werbemittel die k-Anonymitätsprüfung besteht.

Benutzerdefinierte Funktionen

Verkäufer und Käufer müssen ihren eigenen benutzerdefinierten Code als User-Defined Functions (UDFs) bereitstellen, die in privaten Containern innerhalb der bereitgestellten Dienste ausgeführt werden. Diese User-Defined Functions können benutzerdefinierte Geschäftslogik ausführen.

Jeder Käufer oder Verkäufer kann mehrere Instanzen eines bestimmten Diensts bereitstellen, z. B.:

• SellerFrontEnd und Auction.
• BuyerFrontend, Gebot und K-Anonymität.

Einige dieser Dienste verwenden eine Eingabe, bei der es sich um ein JavaScript-Worklet handelt, das User-Defined Functions definiert.

User-Defined-Funktionen für Verkäufer

UDF	Dienst, in dem die UDF ausgeführt wird	Beschreibung
scoreAd()	Versteigerung	Generiert eine Bewertung für das Gebot jedes Käufers oder lehnt das Gebot ab. Diese Bewertung wird dann vom SellerFrontEnd-Dienst verwendet, um unter allen Käufern einen Gewinner auszuwählen.
reportResult()	SellerFrontEnd	Für Die Berichterstellung auf Ereignisebene. Wird im SellerFrontEnd-Dienst ausgeführt, nachdem der endgültige Gewinner ausgewählt wurde. Benachrichtigt den Verkäufer über den gewinnenden Bieter und gibt den Gebotswert an.

User-Defined-Funktionen für Käufer

UDF	Dienst, in dem die UDF ausgeführt wird	Beschreibung
generateBids()	Gebot	Generiert ein Gebot und wählt das Banner aus, das angezeigt wird.
reportWin()	SellerFrontEnd	Für Die Berichterstellung auf Ereignisebene. Wird im SellerFrontEnd-Dienst ausgeführt, wenn das Gebot des Käufers die Auktion gewinnt. Benachrichtigt den Käufer, dass er die Auktion gewonnen hat, und generiert Benachrichtigungs-URLs, die später ausgelöst werden, z. B. beim Rendern von Bannern oder anderen Clientereignissen.
getValues()	Gebotsauswahl & Schlüssel/Wert	Wird im & Schlüssel-Wert-Dienst ausgeführt, wenn der Käufer diesen Dienst verwendet. Ermöglicht die Ausführung von benutzerdefiniertem Code für die Datensuche und -auswahl.

Bereitstellungshandbuch

So stellen Sie den Ad Selection-API-Dienst in Azure bereit:

1. Erstellen Sie ein Azure-Konto, und erstellen Sie ein Abonnement bei Microsoft Azure.

2. Wählen Sie die Option Vertrauliche ACO-Container aus .

3. Wechseln Sie in einem neuen Fenster oder einer neuen Registerkarte zu Terraform-Bereitstellungsskripts , laden Sie die Terraform-Bereitstellungsskripts herunter, und zeigen Sie die Bereitstellungsdokumentation an. Anmerkung: Stellen Sie sicher, dass der Hash des heruntergeladenen Images mit dem Hash im heruntergeladenen Skript übereinstimmt.

4. Die Terraform-Skripts enthalten bereits Links zu öffentlichen Images, die von Microsoft bereitgestellt werden. Wählen Sie die erforderlichen Dienste aus, und stellen Sie sie bereit, indem Sie die Schritte im enthaltenen readme.mdausführen.

   1. Legen Sie bestimmte Flags für Ihre Umgebung fest, einschließlich der Speicherorte von Auktionsarbeitslets.

   2. Konfigurieren Sie alle Voraussetzungen, und bereiten Sie alle Tools für die Bereitstellung vor.

   3. Erstellen Sie Azure-Ressourcen, und führen Sie das Terraform-Skript aus, das die Bereitstellung abgeschlossen hat.

5. Entwickeln Sie Worklets einschließlich user-defined-function (UDF), und starten Sie Ad Selection API-Dienste.

Verwenden der Anzeigenauswahl-API auf Ihrer Website

Um mit der Verwendung der Anzeigenauswahl-API zu beginnen, müssen Verkäufer und Käufer den JavaScript-Code ihrer Websites ändern, der ausgeführt wird, wenn der Browser Microsoft Edge ist.

• Verkäufer: Um private Auktionen durchzuführen, Interessengruppen abzurufen und Berichte zu erstellen, aktualisieren Sie Ihren Code auf den Websites der Herausgeber.

• Käufer: Um Interessengruppen zu erstellen und im Browser zu speichern, aktualisieren Sie den Code auf den Websites Ihrer Werbepartner. Sie können den Delegierungsmechanismus verwenden, um die Erstellung von Interessensgruppen in Domänen von Drittanbietern einzuschränken und zuzulassen.

Weitere Informationen zu den verfügbaren API-Methoden und zum Anzeigen von Beispielcode finden Sie unter Details zur Anzeigenauswahl-API.

Bereitstellen von Feedback zur Ursprungstestphase

Um Feedback zur Testversion der Ad Selection-API zu geben, erstellen Sie ein neues Issue im WICG/privacy-preserving-ads-GitHub-Repository:

• Um vorhandene Probleme anzuzeigen, wechseln Sie zur Registerkarte Probleme des WICG/privacy-preserving-ads-Repositorys.

• Um ein neues Issue zu übermitteln, wechseln Sie zum Formular für das neue Problem.

Siehe auch

Ursprungstests:

• Registrierung der Ad Selection-API-Ursprungstestversion in Microsoft Edge
• Verwenden von Ursprungstests in Microsoft Edge

Entwurfs- und technische Dokumente:

• Übersicht über die Anzeigenauswahl
• Api-Vorschlag für die Anzeigenauswahl
• Details zur Anzeigenauswahl-API

Images für die Bereitstellung:

• Verkäufer
  • Front-End-Dienst für Den Verkäufer für die Anzeigenauswahl
  • Anzeigenauswahl-Auktionsdienst
• Käufer
  • Ad Selection Buyer Front-End-Service
  • Anzeigenauswahl-Gebotsdienst
  • Anzeigenauswahl K-Anonymitätsdienst
• Verkäufer und Käufer
  • Schlüsselwertdienst für die Anzeigenauswahl

Bereitstellungsskripts:

• Terraform-Bereitstellungsskripts

Vertrauenswürdige Ausführungsumgebung (Trusted Execution Environment, TEE):

• Confidential Computing: Hardware-Based vertrauenswürdige Ausführung für Anwendungen und Daten

Azurblau:

• Microsoft Azure
• Vertrauliche Container auf Azure Container Instances