Entwicklerleitfaden für On-Device-Auktionen für Anzeigen zur Auslieferung von Remarketing- und benutzerdefinierten Zielgruppen ohne websiteübergreifendes Drittanbieter-Tracking.
Wenn Sie die Protected Audience API zum ersten Mal verwenden, finden Sie unter Protected Audience API – Übersicht eine allgemeine Erläuterung der API.
Dieser Beitrag richtet sich an Entwickler als technische Referenz für die neueste Version der experimentellen Protected Audience API. Es ist eine Demo einer einfachen Protected Audience API-Bereitstellung sowie API-Referenzen für Anzeigenkäufer und ‐verkäufer verfügbar.
Implementierungsstatus
- Das Protected Audience API-Angebot ist jetzt allgemein verfügbar. Fragen stellen und Diskussionen verfolgen
- Der Status der Protected Audience API mit ausstehenden Funktionen enthält Informationen zu Änderungen und Verbesserungen der Protected Audience API und deren Funktionen.
- Blink status
- Chrome-Plattformstatus der Protected Audience API: Dieser Status bezieht sich auf die Protected Audience API in Chrome.
- Ads API-Status der Chrome-Plattform: Eine Sammlung von APIs zur Vereinfachung von Werbung: Protected Audience API, Topics, Fenced Frames und Attributionsberichte.
Tragen Sie sich in die Mailingliste für Entwickler ein, um über Statusänderungen in der API informiert zu werden.
Was ist die Protected Audience API?
Die Protected Audience API ist eine Privacy Sandbox-API, die für Remarketing und benutzerdefinierte Zielgruppen entwickelt wurde. Sie wurde so konzipiert, dass sie nicht von Dritten verwendet werden kann, um das Surfverhalten von Nutzern websiteübergreifend nachzuverfolgen. Die API ermöglicht On-Device-Auktionen im Browser, um relevante Anzeigen für Websites auszuwählen, die der Nutzer zuvor besucht hat.
Die Protected Audience API ist der erste Test, der in Chromium innerhalb der Vorschlagsfamilie TURTLEDOVE implementiert wird.
Protected Audience API testen
Verfügbare API-Referenz
Dieses Dokument bietet einen Überblick über die Protected Audience API. Wenn Sie nach bestimmten API-Methoden und -Parametern suchen:
- Käuferleitfaden für
joinAdInterestGroup()
undgenerateBid()
- Verkäuferleitfaden für die Protected Audience API
runAdAuction()
- Käuferleitfaden für
reportWin()
und Verkäuferleitfaden fürreportResult()
- Fehler bei der Protected Audience API beheben
Weitere Informationen finden Sie unter Best Practices zur Latenz bei Anzeigenauktionen der Protected Audience API.
Demo der Protected Audience API
Eine Anleitung für die grundlegende Bereitstellung der Protected Audience API auf Werbetreibenden- und Publisher-Websites finden Sie unter Protected-audience-demo.web.app/.
Diese API testen
Sie können die Protected Audience API für einen einzelnen Nutzer in Chrome Beta 101.0.4951.26 und höher auf einem Computer testen:
- Alle APIs zum Datenschutz bei Werbung unter
chrome://settings/adPrivacy
aktivieren. - Flags über die Befehlszeile festlegen Die vollständige Liste der verfügbaren Protected Audience API-Flags finden Sie in der Chromium-Codesuche.
Anzeigen in iFrames oder Fenced Frames rendern
Je nachdem, welche Flags festgelegt sind, können Anzeigen in einem <iframe>
- oder <fencedframe>
-Element gerendert werden.
So verwenden Sie <fencedframe>
zum Rendern von Anzeigen:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
So verwenden Sie <iframe>
zum Rendern von Anzeigen:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
Fügen Sie das Flag BiddingAndScoringDebugReportingAPI
ein, um Methoden zur temporären Fehlerbehebung für Verluste/Gewinne zu aktivieren.
Unterstützte Funktionen
Die Protected Audience API hinter Funktions-Flags in Chromium ist ein erster Test, bei dem die folgenden Funktionen der Protected Audience API getestet werden:
- Interessengruppen: werden vom Browser gespeichert, zusammen mit den zugehörigen Metadaten, um Gebote für Anzeigen und das Rendering zu konfigurieren.
- On-Device-Gebote von Käufern (DSP oder Werbetreibender): basierend auf gespeicherten Interessengruppen und Signalen des Verkäufers.
- Anzeigenauswahl auf dem Gerät durch den Verkäufer (SSP oder Publisher): basierend auf Auktionsgeboten und Metadaten der Käufer.
- Anzeigen-Rendering in einer vorübergehend gelockerten Version von Fenced Frames: Netzwerkzugriff und Logging für das Anzeigen-Rendering sind zulässig.
Weitere Informationen zur Unterstützung von Funktionen und zu Einschränkungen finden Sie in der Erläuterung der Protected Audience API.
Berechtigungen für Interessengruppen
In der aktuellen Implementierung der Protected Audience API ist es standardmäßig erlaubt, joinAdInterestGroup()
von überall auf einer Seite aus aufzurufen, auch von domainübergreifenden iFrames aus.
Wenn Websiteinhaber ihre Berechtigungsrichtlinien für domainübergreifende iFrames aktualisieren konnten, sollen Aufrufe von domainübergreifenden iFrames künftig nicht mehr zugelassen werden.
Dienst für Schlüssel/Wert-Paare
Zur Unterstützung der Protected Audience API-Anzeigenauktion kann der Browser auf einen Schlüssel/Wert-Dienst zugreifen, um Echtzeitinformationen abzurufen, die die Protected Audience API-Anzeigenauktion unterstützen. Diese Informationen können auf verschiedene Arten verwendet werden:
- Käufer können das verbleibende Budget für eine Kampagne berechnen.
- Verkäufer müssen unter Umständen Anzeigen-Creatives auf Einhaltung der Richtlinien des Publishers prüfen.
Der Schlüssel/Wert-Dienstcode der Protected Audience API ist jetzt verfügbar. Das Statusupdate finden Sie in diesem Blogpost.
Für erste Tests wurde ein Bring Your Own Server-Modell eingeführt. Langfristig müssen Anzeigentechnologie-Anbieter die Open-Source-Schlüssel-/Wert-Dienste der Protected Audience API verwenden, die in vertrauenswürdigen Ausführungsumgebungen ausgeführt werden.
Weitere Informationen zu Aktualisierungen des Zeitplans finden Sie im Blogpost zu Protected Audience API-Diensten. Vor der Umstellung werden wir die Entwickler rechtzeitig informieren, damit sie mit den Tests und der Einführung beginnen können.
Funktionsunterstützung erkennen
Prüfen Sie vor der Verwendung der API, ob sie vom Browser unterstützt wird und im Dokument verfügbar ist:
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
Wie funktioniert die Protected Audience API?
In diesem Beispiel surft ein Nutzer auf der Website eines Fahrradherstellers, besucht später eine Nachrichtenwebsite und sieht eine Anzeige für ein neues Fahrrad des Herstellers.
Im Laufe der Zeit werden die Funktionen der Protected Audience API hinzugefügt.
1. Ein Nutzer besucht die Website eines Werbetreibenden.
![Eine Person, die in einem Browser auf ihrem Laptop die Website eines Fahrradherstellers aufruft](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visiting-custom-2ca7094e57259.png?authuser=6&hl=de)
Angenommen, ein Nutzer besucht die Website eines Herstellers von maßgefertigten Fahrrädern (dem Werbetreibenden) und verbringt einige Zeit auf der Produktseite eines handgefertigten Stahlrads. Dadurch erhält der Fahrradhersteller eine Remarketing-Möglichkeit.
2. Der Browser des Nutzers wird aufgefordert, eine Interessengruppe hinzuzufügen.
![Ein Nutzer öffnet einen Browser auf seinem Laptop und besucht eine Website. Im Browser wird JavaScript-Code zum Verbinden von Anzeigengruppen mit Anzeigen ausgeführt.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-user-opens-browser-th-6c2a4e6d97af7.png?authuser=6&hl=de)
Die Demand-Side-Plattform (DSP) des Werbetreibenden (oder der Werbetreibende selbst) ruft navigator.joinAdInterestGroup()
auf, um den Browser aufzufordern, der Liste der Gruppen, in denen der Browser Mitglied ist, eine Interessengruppe hinzuzufügen.
In diesem Beispiel heißt die Gruppe custom-bikes
und der Inhaber ist dsp.example
. Der Inhaber der Interessengruppe (in diesem Fall die DSP) ist ein Käufer in der Protected Audience API-Anzeigenauktion. Die Mitgliedschaft in einer Interessengruppe wird vom Browser auf dem Gerät des Nutzers gespeichert und nicht mit dem Anbieter des Browsers oder anderen Nutzern geteilt.
- Erläuterung der Protected Audience API: Interessengruppen für Browsereinträge.
- API-Leitfaden lesen: Für Käufer und DSPs wird erläutert, wie Sie
joinAdInterestGroup()
erstellen und Gebote generieren.
Anzeigen für eine Interessengruppe festlegen
ads
- und adComponents
-Objekte enthalten eine URL für ein Anzeigen-Creative und optional beliebige Metadaten, die bei der Gebotsabgabe verwendet werden können. Beispiel:
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // optional
}
Wie geben Käufer Gebote ab?
generateBid()
wird für jede Interessengruppe aufgerufen, in der der Browser Mitglied ist, sofern der Inhaber der Interessengruppe dazu eingeladen wird, ein Gebot abzugeben.
Lesen Sie die Entwicklerdokumentation zu generatedBid()
.
3. Der Nutzer besucht eine Website, auf der Werbefläche verkauft wird.
![Eine Person besucht eine Nachrichtenwebsite in einem Browser auf ihrem Laptop. Auf der Website ist eine leere Anzeigenfläche vorhanden.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=6&hl=de)
Später besucht der Nutzer eine Website, auf der Werbeflächen verkauft werden, in diesem Beispiel eine Nachrichtenwebsite. Auf der Website gibt es Anzeigeninventar, das programmatisch mit Echtzeitgeboten verkauft wird.
4. Eine Anzeigenauktion wird im Browser ausgeführt.
![Eine Person ruft eine Nachrichtenwebsite in einem Browser auf ihrem Laptop auf. Eine Anzeigenauktion der Protected Audience API wird durchgeführt, um eine Anzeige für die verfügbare Werbefläche auszuwählen.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-32cbfd93dc442.png?authuser=6&hl=de)
Die Anzeigenauktion wird wahrscheinlich vom Supply-Side-Anbieter (SSP) des Publishers oder vom Publisher selbst durchgeführt. Der Zweck der Auktion besteht darin, die am besten geeignete Anzeige für eine einzelne verfügbare Anzeigenfläche auf der aktuellen Seite auszuwählen. Bei der Auktion werden die Interessengruppen, denen der Browser angehört, sowie Daten von Käufern und Verkäufern der Schlüssel/Wert-Paare berücksichtigt.
- Erläuterung der Protected Audience API: Verkäufer führen Auktionen auf Geräten durch
- API-Leitfaden lesen: Verkäufer erhalten weitere Informationen zu
runAdAuction()
und den Best Practices für die Latenz bei Anzeigenauktionen.
5. Der Verkäufer und die teilnehmenden Käufer fordern Echtzeitdaten vom Schlüssel/Wert-Dienst an
![Die Nutzenden sehen sich eine Nachrichtenwebsite in einem Browser auf ihrem Laptop an. Es findet eine Anzeigenauktion mit der Protected Audience API statt, bei der ein Teilnehmer Daten vom Schlüssel/Wert-Dienst erhält.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=6&hl=de)
Während einer Anzeigenauktion kann der Verkäufer Echtzeitdaten zu bestimmten Creatives anfordern, indem er eine Anfrage an seinen Schlüssel/Wert-Dienst stellt.
Der Verkäufer kann diese Informationen während runAdAuction()
mit dem Attribut trustedScoringSignalsUrl
zusammen mit den Schlüsseln aus den renderUrl
-Attributen aller Einträge in den Feldern ads
und adComponents
aller Interessengruppen in der Auktion anfordern.
Ein Käufer kann mit den Attributen trustedBiddingSignalsUrl
und trustedBiddingSignalsKeys
des an navigator.joinAdInterestGroup()
übergebenen Interessengruppenarguments Echtzeitdaten von seinem Schlüssel/Wert-Dienst anfordern.
Wenn runAdAuction()
aufgerufen wird, sendet der Browser eine Anfrage an den vertrauenswürdigen Server jedes Käufers. Die URL für die Anfrage könnte wie folgt aussehen:
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
- Die Basis-URL stammt von
trustedBiddingSignalsUrl
. hostname
wird vom Browser bereitgestellt.- Der Wert
keys
wird vontrustedBiddingSignalsKeys
übernommen.
Die Antwort auf diese Anfrage ist ein JSON-Objekt, das Werte für jeden der Schlüssel bereitstellt.
- Erläuterung zur Protected Audience API: Echtzeitdaten aus dem Schlüssel/Wert-Dienst der Protected Audience API abrufen.
- Weitere Informationen finden Sie im Hilfeartikel Open-Source-Bereitstellung für den Schlüssel-/Wert-Dienst der Protected Audience API.
6. Die erfolgreiche Anzeige wird ausgeliefert.
![Eine Person ruft eine Nachrichtenwebsite in einem Browser auf ihrem Laptop auf. Eine Anzeige für 20% Rabatt auf ein Fahrrad wird in einem sicheren umzäunten Rahmen präsentiert.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=6&hl=de)
Das von runAdAuction() zurückgegebene Promise wird in ein Fenced-Frame-Konfigurationsobjekt (FencedFrameConfig
) aufgelöst, wenn das resolveToConfig
-Flag in der Auktionskonfiguration auf true
gesetzt ist. Die Frame-Konfiguration wird von einem abgegrenzten Frame verwendet, um den Frame zur erfolgreichen Anzeige zu navigieren. Die URL der Anzeige ist jedoch für den Frame-Einbettungscode nicht sichtbar.
Konfigurationsobjekt für abgegrenzte Frames ist ab M114 verfügbar. Weitere Informationen zum Objekt FencedFrameConfig
findest du in diesem Chrome-Blogartikel.
- Erläuterung zur Protected Audience API: Browser rendern die erfolgreiche Anzeige
7. Das Auktionsergebnis wird im Bericht
Langfristig planen Sie, dass der Browser über die Private Aggregation APIs Berichte zu Auktionsergebnissen für den Verkäufer und Käufer erstellen kann.
Als temporäres Berichtsmechanismus auf Ereignisebene kann der Code, der reportResult()
für den Verkäufer und reportWin()
für den erfolgreichen Bieter implementiert, die sendReportTo()
-Funktion aufrufen. Dafür wird ein einzelnes Argument verwendet: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird und die Informationen auf Ereignisebene codiert, die gemeldet werden sollen.
- API-Leitfaden lesen: Informationen zu Verkäufer- und Käuferberichten
8. Ein Anzeigenklick wird erfasst
![Ein Nutzer klickt auf einer Nachrichtenwebsite auf eine Anzeige für ein Fahrrad, die in einen eingezäunten Rahmen eingebettet ist. Die Berichtsdaten werden an Verkäufer und Käufer gesendet.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-clicks-an-ad-a-be2111724646f.png?authuser=6&hl=de)
Es wird ein Klick auf eine Anzeige erfasst, die in einem abgegrenzten Frame gerendert wird. Weitere Informationen dazu finden Sie unter Berichte zu Fenced Frames-Anzeigen.
![Eine Übersicht über die einzelnen Phasen einer Protected Audience API-Anzeigenauktion](https://developers.google.cn/static/privacy-sandbox/assets/images/an-overview-each-stage-c8bac3c2c070f.png?authuser=6&hl=de)
Was ist der Unterschied zwischen der Protected Audience API und TURTLEDOVE?
Die Protected Audience API ist das erste Experiment, das in Chromium innerhalb der TURTLEDOVE-Angebotsfamilie implementiert wird.
Die Protected Audience API entspricht den allgemeinen Prinzipien von TURTLEDOVE. Manche Onlinewerbung basierte darauf, dass die Anzeige einer potenziell interessierten Person präsentiert wurde, die zuvor mit dem Werbetreibenden oder Werbenetzwerk interagiert hat. In der Vergangenheit hat der Werbetreibende damit eine bestimmte Person beim Surfen auf Websites erkannt. Dies ist ein grundlegendes Thema des Datenschutzes im heutigen Web.
Bei TURTLEDOVE geht es darum, eine neue API für diesen Anwendungsfall anzubieten und gleichzeitig einige wichtige datenschutzbezogene Fortschritte anzubieten:
- Die Informationen zu den Inhalten, an denen die Person interessiert ist, werden nicht vom Werbetreibenden, sondern im Browser gespeichert.
- Werbetreibende können Anzeigen auf Grundlage von Interessen schalten, aber nicht mit anderen Informationen über eine Person kombinieren, insbesondere nicht darüber, wer sie sind oder welche Seite sie besuchen.
Die Protected Audience API entstand aus TURTLEDOVE und einer Sammlung zugehöriger Änderungsvorschläge, um Entwickler, die die API verwenden würden, besser zu unterstützen:
- In SPARROW hat Criteo das Hinzufügen eines Dienstmodells („Gatekeeper“) vorgeschlagen, das in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt wird. Die Protected Audience API verwendet eine eingeschränktere Nutzung von TEEs für die Echtzeitdatensuche und aggregierte Berichterstellung.
- In den Angeboten TERN von NextRoll und PARRROT von Magnite wurden die verschiedenen Rollen beschrieben, die Käufer und Verkäufer in der On-Device-Auktion einnehmen. Der Ablauf für Gebote/Bewertung von Anzeigen der Protected Audience API basiert auf dieser Arbeit.
- Die TURTLEDOVE-Änderungen auf ergebnisbasierter und produktbezogener RTB House verbesserten das Anonymitätsmodell und die Personalisierungsfunktionen der On-Device-Auktion.
- PARAKEET ist der Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst. Dieser basiert auf einem Proxyserver, der in einem TEE zwischen dem Browser und den Anzeigentechnologie-Anbietern ausgeführt wird, um Anzeigenanfragen zu anonymisieren und Datenschutzeigenschaften durchzusetzen. Die Protected Audience API verwendet dieses Proxying-Modell nicht. Wir passen die JavaScript APIs für PARAKEET und die Protected Audience API an, um zukünftige Arbeitsschritte zu ermöglichen und die besten Funktionen beider Vorschläge weiter zu kombinieren.
Die Protected Audience API verhindert noch nicht, dass das Werbenetzwerk einer Website lernt, welche Anzeigen ein Nutzer sieht. Wir gehen davon aus, dass die API im Laufe der Zeit angepasst wird, um sie sicherer zu machen.
Kann die Topics API mit der Protected Audience API verwendet werden?
Ja. Ein beobachtetes Thema für den aktuellen Nutzer, das von der Topics API bereitgestellt wird, kann von einem Verkäufer oder Bieter als Kontextinformationen verwendet werden. Ein Thema kann in die folgenden Attribute aufgenommen werden:
auctionSignals
, eine Eigenschaft des Auktionskonfigurationsobjekts, das annavigator.runAdAuction()
übergeben wirduserBiddingSignals
, ein Attribut des Interessengruppen-Konfigurationsobjekts, das annavigator.joinAdInterestGroup()
übergeben wird
Verfügbare Browserkonfiguration
Nutzer können ihre Teilnahme an Privacy Sandbox-Tests in Chrome anpassen, indem sie die Einstellung für die oberste Ebene in chrome://settings/adPrivacy
aktivieren oder deaktivieren.
Während der ersten Tests können Nutzer diese allgemeine Privacy Sandbox-Einstellung verwenden, um die Protected Audience API zu deaktivieren. Für Chrome ist geplant, dass Nutzer die Liste der Interessengruppen, denen sie auf den von ihnen besuchten Websites hinzugefügt wurden, ansehen und verwalten können. Wie bei den Privacy Sandbox-Technologien selbst können sich auch die Nutzereinstellungen durch das Feedback von Nutzern, Aufsichtsbehörden und anderen Quellen ändern.
Wir aktualisieren die verfügbaren Einstellungen in Chrome weiterhin auf der Grundlage von Tests und Feedback. Für die Zukunft planen wir, detailliertere Einstellungen zur Verwaltung der Protected Audience API und der zugehörigen Daten anzubieten.
API-Aufrufer können nicht auf die Gruppenmitgliedschaft zugreifen, wenn Nutzer im Inkognitomodus surfen. Die Mitgliedschaft wird entfernt, wenn Nutzer ihre Websitedaten löschen.
Werden die Protected Audience-Worklets vom Browser im Cache gespeichert?
Die Ressourcen, die die Protected Audience-Worklets enthalten – die Worklets zur Gebotserstellung und Berichterstellung des Käufers sowie die Anzeigenbewertungs- und Berichterstellungs-Worklets des Verkäufers – werden vom Browser im Cache gespeichert. Mit dem Header Cache-Control
können Sie das Caching-Verhalten steuern.
Interagieren und Feedback geben
Support kontaktieren
So stellen Sie Fragen und erhalten Unterstützung bei der Implementierung, der Demo oder der Dokumentation:
- GitHub: Lesen Sie die Erläuterung, stellen Sie Fragen und folgen Sie Diskussionen.
- Demo: Melde ein Problem im Democode-Repository.
- Entwicklersupport: Im Privacy Sandbox-Support-Repository für Entwickler können Sie Fragen stellen und sich an Diskussionen beteiligen. Wählen Sie die Problemvorlage für die Protected Audience API aus.
- Chrome-Implementierung: Bei Fehlern oder Problemen mit der Implementierung der Protected Audience API in Chrome kannst du bestehende Probleme ansehen oder ein neues Problem melden.
Bei allgemeineren Fragen zur Erfüllung Ihrer Anforderungen mit der Protected Audience API melden Sie ein Problem im API-Repository. Außerdem können Sie in der Improving Web Advertising Business Group des W3C über Anwendungsfälle der Branche sprechen.
Über das Feedbackformular der Privacy Sandbox können Sie dem Chrome-Team außerhalb von öffentlichen Foren privat Feedback geben.
Deaktivieren
Möchten Sie die Protected Audience API deaktivieren? Erfahren Sie, wie Sie als Websiteinhaber oder einzelner Nutzer den Zugriff auf die Protected Audience API blockieren.
Immer auf dem neuesten Stand bleiben
- Benachrichtigungen über API-Statusänderungen erhalten Sie auf der Mailingliste für Entwickler.
- Wenn du alle aktuellen Diskussionen zur API verfolgen möchtest, kannst du auf der API-Seite auf GitHub auf die Schaltfläche Ansehen klicken. Dazu müssen Sie ein GitHub-Konto haben oder erstellen.
- Wenn Sie allgemeine Updates zur Privacy Sandbox erhalten möchten, abonnieren Sie den RSS-Feed [Progress in the Privacy Sandbox].
- Nehmen Sie an den geplanten Aufrufen für die Protected Audience API teil (alle zwei Wochen). Jeder ist herzlich willkommen. Wenn Sie teilnehmen möchten, müssen Sie sich zuerst der WICG anschließen. Sie können sich aktiv einbringen oder einfach zuhören.