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, lesen Sie die Übersicht über die Protected Audience API. finden Sie eine allgemeine Erläuterung der API.
Dieser Beitrag richtet sich an Entwickler als technische Referenzen für die aktuelle Version der experimentellen Protected Audience API. Demo einer einfachen Die Bereitstellung der Protected Audience API sowie API-Referenzen für Käufer und Verkäufer von Anzeigen
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 für Verwendung von Remarketing und benutzerdefinierten Zielgruppen Schutzhüllen, die so konzipiert sind, dass sie nicht von Dritten verwendet werden können, beim Surfen auf Websites. Die API ermöglicht On-Device-Auktionen den Browser, um relevante Anzeigen für bereits besuchte Websites auszuwählen.
Die Protected Audience API ist der erste Test, der in Chromium im Rahmen der TURTLEDOVE-Angebotsfamilie.
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 Leitfaden für Verkäufer zureportResult()
- 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
Schritt-für-Schritt-Anleitung für die grundlegende Bereitstellung der Protected Audience API für einen Werbetreibenden und Publisher finden Sie unter protected-audience-demo.web.app/.
<ph type="x-smartling-placeholder">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 folgenden Geräten testen: Computer:
- Alle APIs zum Datenschutz bei Werbung unter
chrome://settings/adPrivacy
aktivieren. - Flags über die Befehlszeile festlegen Eine vollständige Liste der verfügbaren Protected Audience API-Flags finden Sie unter Chromium-Codesuche
Anzeigen in iFrames oder Fenced Frames rendern
Anzeigen können in einem <iframe>
- oder einem
<fencedframe>
, je nachdem,
Flags gesetzt sind.
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
Zum Aktivieren das Flag BiddingAndScoringDebugReportingAPI
hinzufügen
Methoden zur temporären Fehlerbehebung bei Verlusten/Gewinnen.
Unterstützte Funktionen
Die Protected Audience API hinter Funktions-Flags in Chromium ist ein erster Test, bei dem die der Protected Audience API:
- Interessengruppen: werden vom Browser gespeichert, zusammen mit den zugehörigen Metadaten, Anzeigengebote und -rendering konfigurieren.
- On-Device-Gebote von Käufern (DSP oder Werbetreibender): basierend auf den gespeicherten Interessengruppen und Signale des Verkäufers.
- Anzeigenauswahl auf dem Gerät durch den Verkäufer (SSP oder Publisher): basiert auf und Metadaten der Käufer.
- Anzeigen-Rendering in einer vorübergehend entspannten Version von Fenced Frames: mit Netzwerkzugriff und Logging für das Anzeigen-Rendering zugelassen
Weitere Informationen zur Funktionsunterstützung und zu Einschränkungen finden Sie in der Erläuterung der Protected Audience API.
Berechtigungen für Interessengruppen
Standardmäßig ist bei der aktuellen Implementierung der Protected Audience API das Aufrufen von
joinAdInterestGroup()
von überall auf einer Seite aus, sogar von
domainübergreifenden iFrames aus.
Wenn Websiteinhaber in Zukunft Zeit hatten, ihre domainübergreifenden Richtlinien für iFrame-Berechtigungen Aufrufe von domainübergreifenden iFrames verboten werden sollen.
Dienst für Schlüssel/Wert-Paare
Zur Unterstützung der Anzeigenauktion der Protected Audience API kann der Browser auf eine Schlüssel/Wert-Paar-Dienst , um Echtzeitinformationen abzurufen, die die Protected Audience API-Anzeigenauktion unterstützen. Dieses Informationen können auf verschiedene Weise 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.
Schlüssel/Wert-Dienstcode der Protected Audience API ist jetzt verfügbar. Das Statusupdate finden Sie in diesem Blogpost.
Für erste Tests sollte ein Bring Your Own Server (Bring Your Own Server, BYOD) verwendet werden. eingeführt. Langfristig müssen Anzeigentechnologie-Anbieter Open-Source-Dienste für Protected Audience API-Schlüssel/Wert-Paare, die in vertrauenswürdiger Ausführung ausgeführt werden Umgebungen.
Weitere Informationen finden Sie im Blogpost zu Protected Audience API-Diensten. . Wir werden Entwickler vorab rechtzeitig darüber informieren, bevor diese Umstellung stattfindet.
Funktionsunterstützung erkennen
Bevor Sie die API verwenden, prüfen Sie, ob sie vom Browser unterstützt wird und verfügbar ist unter das Dokument:
'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 sieht sich eine nutzende Person die Website eines Fahrradherstellers an und später eine Nachrichtenwebsite besucht und ihm eine Anzeige für ein neues Fahrrad des Fahrradherstellers präsentiert wird.
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-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-visiting-custom-2ca7094e57259.png?authuser=19&hl=de)
Angenommen, ein Nutzer besucht die Website eines Fahrradherstellers (der Werbetreibende). und verbringt einige Zeit auf der Produktseite für einen handgefertigten Stahl, mit dem Fahrrad. So erhält der Fahrradhersteller eine Remarketing-Empfehlung.
2. Der Browser des Nutzers wird aufgefordert, eine Interessengruppe hinzuzufügen.
![Ein Nutzer öffnet einen Browser auf seinem Laptop und besucht eine Website. JavaScript
wird der Code zum Beitritt zu Interessengruppen im Browser ausgeführt.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-user-opens-browser-th-6c2a4e6d97af7.png?authuser=19&hl=de)
Die Demand-Side-Plattform (DSP) des Werbetreibenden (oder der Werbetreibende selbst) ruft
navigator.joinAdInterestGroup()
, um den Browser zu bitten, eine Interessengruppe hinzuzufügen
zur Liste der Gruppen hinzu, in denen der Browser Mitglied ist.
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.
der Protected Audience API-Auktionen. Die Mitgliedschaft in einer Interessengruppe wird vom Browser gespeichert,
auf dem Gerät des Nutzers und wird nicht an den Browseranbieter oder andere Personen weitergegeben.
- Erläuterung der Protected Audience API: Interessengruppen für Browsereinträge.
- API-Leitfaden lesen: Für Käufer und DSPs wird beschrieben, wie
joinAdInterestGroup()
und generieren Sie Gebote.
Anzeigen für eine Interessengruppe festlegen
Die Objekte ads
und adComponents
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, der der Browser angehört
von – wenn der Inhaber der Interessengruppe zur Gebotsabgabe eingeladen wurde.
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. Website
hat eine leere Anzeigenfläche.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=19&hl=de)
Später besucht der Nutzer eine Website, auf der Werbeflächen verkauft werden, in diesem Beispiel eine Website. Die Website verfügt über Anzeigeninventar, das über sie programmatisch verkauft wird. Echtzeitgebote nutzen.
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-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-views-news-webs-32cbfd93dc442.png?authuser=19&hl=de)
Die Anzeigenauktion wird wahrscheinlich vom Anbieter der Supply-Side-Plattform des Publishers durchgeführt. (SSP) oder den Publisher selbst. Der Zweck der Auktion besteht darin, Anzeige für eine einzelne verfügbare Anzeigenfläche auf der aktuellen Seite am besten geeignet ist. Die der Auktion die Interessengruppen, denen der Browser angehört, sowie Daten von Käufern und Verkäufern von Werbeflächen Schlüssel/Wert-Dienste.
- Erläuterung der Protected Audience API: Verkäufer führen Auktionen auf Geräten durch
- API-Leitfaden lesen: Verkäufer können sich informieren über
runAdAuction()
und die Best Practices zur 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. Eine Anzeige
bei einer Auktion mithilfe der Protected Audience API, wobei ein Teilnehmer Daten vom Schlüssel/Wert-Dienst erhält.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=19&hl=de)
Während einer Anzeigenauktion kann der Verkäufer Echtzeitdaten zu einer bestimmten Anzeige anfordern
indem Sie eine Anfrage an ihren Schlüssel/Wert-Dienst senden.
Der Verkäufer kann diese Informationen während
runAdAuction()
durch die Property trustedScoringSignalsUrl
,
zusammen mit den Schlüsseln aus den renderUrl
-Eigenschaften aller Einträge im ads
und adComponents
aller Interessengruppen in der Auktion enthält.
Käufer können mithilfe der folgenden Methode Echtzeitdaten von ihrem Schlüssel/Wert-Dienst anfordern:
die Attribute trustedBiddingSignalsUrl
und trustedBiddingSignalsKeys
von
Das Interessengruppenargument, das an navigator.joinAdInterestGroup()
übergeben wurde.
Beim Aufruf von runAdAuction()
stellt der Browser eine Anfrage an jede Anzeige
vertrauenswürdigen Server des 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 jede der Schlüssel.
- 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
in einem gesicherten umzäunten Rahmen präsentiert.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=19&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 sollte der Browser Berichte zu Auktionsergebnissen für die Verkäufer und Käufern, die die Private Aggregation APIs nutzen.
Als temporäres Meldeverfahren auf Ereignisebene
ermöglicht der Code,
reportResult()
für den Verkäufer und reportWin()
für den erfolgreichen Bieter
und rufen Sie die Funktion sendReportTo()
auf. Hierfür wird nur ein Argument verwendet: ein String
Sie stellen eine URL dar, die nach Abschluss der Auktion abgerufen wird. Dabei wird die URL
Informationen auf Ereignisebene,
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-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-clicks-an-ad-a-be2111724646f.png?authuser=19&hl=de)
Es wird ein Klick auf eine Anzeige erfasst, die in einem abgegrenzten Frame gerendert wird. Weitere Informationen über Informationen zur Funktionsweise finden Sie unter Berichte zu Fenced Frames-Anzeigen.
<ph type="x-smartling-placeholder">
![Eine Übersicht über die einzelnen Phasen einer Protected Audience API-Anzeigenauktion](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/an-overview-each-stage-c8bac3c2c070f.png?authuser=19&hl=de)
Was ist der Unterschied zwischen der Protected Audience API und TURTLEDOVE?
Die Protected Audience API ist der erste Test, der in Chromium im Rahmen der TURTLEDOVE-Angebotsfamilie.
Die Protected Audience API entspricht den allgemeinen Prinzipien von TURTLEDOVE. Einige Onlinewerbung haben Ihre Anzeige einer potenziell interessierten Person gezeigt wurde, die mit dem Werbetreibenden oder Werbenetzwerk interagiert haben. In der Vergangenheit hat wenn der Werbetreibende eine bestimmte Person erkennt, Websites, die heutzutage ein wichtiges Thema für den Datenschutz darstellen.
Bei TURTLEDOVE geht es darum, eine neue API für diesen Anwendungsfall anzubieten. und einige wichtige Verbesserungen beim Datenschutz bieten:
- Der Browser, nicht der Werbetreibende, enthält die Informationen der Werbetreibende glaubt, dass ein Nutzer interessiert ist.
- Werbetreibende können Anzeigen basierend auf Interessen schalten, dies jedoch nicht kombinieren. Interessen mit anderen Informationen über eine Person vergleichen, insbesondere auf die Person, welche Seite sie besuchen.
Die Protected Audience API entstand aus TURTLEDOVE und einer Sammlung zugehöriger Vorschläge für Änderungen, um Entwicklern, die das API verwenden würden, besser zu unterstützen:
- Gehen Sie in SPARROW so vor: Criteo hat die Hinzufügung vorgeschlagen eines Dienstmodells („Gatekeeper“), 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.
- TERN und von NextRoll PARRROT von Magnite Angeboten wurden die unterschiedlichen Rollen beschrieben, die Käufer und Verkäufer im On-Device-Auktion ab. Der Ablauf für Gebote/Bewertung von Anzeigen der Protected Audience API basiert auf dieser Arbeit.
- Ergebnisbasiert des RTB House und Produktebene TURTLEDOVE-Änderungen verbesserten das Anonymitätsmodell und die Personalisierung. Funktionen der On-Device-Auktion
- PARAKEET ist Der Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst, der auf einem Proxy beruht in einem TEE zwischen dem Browser und den Anzeigentechnologie-Anbietern, Anonymisierung von Anzeigenanfragen und Datenschutz Eigenschaften. Die Protected Audience API verwendet dieses Proxying-Modell nicht. Wir bringen die JavaScript APIs für PARAKEET und die Protected Audience API angleichen, um zukünftige Arbeiten, um die besten Funktionen beider Angebote 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, könnte verwendet werden als Kontextinformationen durch einen Verkäufer oder Bieter. Ein Thema könnte in folgenden Eigenschaften:
auctionSignals
, eine Eigenschaft des Auktionskonfigurationsobjekts, das annavigator.runAdAuction()
übergeben wirduserBiddingSignals
, ein Attribut der Interessengruppenkonfiguration Objekt annavigator.joinAdInterestGroup()
übergeben
Verfügbare Browserkonfiguration
Nutzer können ihre Teilnahme an Privacy Sandbox-Tests in Chrome anpassen, indem sie
Aktivieren oder Deaktivieren der Einstellung auf oberster Ebene
chrome://settings/adPrivacy
Während der ersten Tests können Nutzer diese allgemeine Datenschutzstufe Sandbox-Einstellung zum Deaktivieren der Protected Audience API. Chrome plant, Nutzern die Möglichkeit zu geben, Die Liste der Interessengruppen verwalten, denen sie im Web hinzugefügt wurden Websites, die sie besucht haben. Wie bei den Privacy Sandbox-Technologien selbst Nutzereinstellungen können sich aufgrund des Feedbacks 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 des zugehöriger Daten.
API-Aufrufer können nicht auf die Gruppenmitgliedschaft zugreifen, wenn Nutzer im Inkognitomodus surfen. und 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
Wenn Sie Fragen stellen und Unterstützung bei der Implementierung, der Demo oder der Dokumentation:
- GitHub: Lesen Sie den Erklärung, Fragen stellen und Diskussionen folgen
- Demo: Melde ein Problem im Democode-Repository.
- Support für Entwickler: Hier können Sie Fragen stellen und sich an Diskussionen zum Privacy Sandbox-Entwicklersupport Repository. Wählen Sie die Problemvorlage für die Protected Audience API aus.
- Chrome-Implementierung: Hier finden Sie Fehler oder Probleme bei der Implementierung von der Protected Audience API können Sie bestehende Probleme aufrufen, oder ein neues Problem melden.
Bei allgemeineren Fragen zur Erfüllung Ihrer Anforderungen mit der Protected Audience API ein Problem im API-Repository melden. Außerdem können Sie branchenspezifische Anwendungsfälle im W3C-Bericht Verbesserung der Geschäftsgruppe für Webwerbung:
Verwenden Sie das Feedbackformular der Privacy Sandbox um Feedback privat mit dem Chrome-Team außerhalb von öffentlichen Foren zu teilen.
Deaktivieren
Möchten Sie die Protected Audience API deaktivieren? Hier erfahren Sie, wie Sie den Zugriff auf die Protected Audience API zu blockieren, als Website-Inhaber oder einzelner Nutzer.
Immer auf dem neuesten Stand bleiben
- Für Benachrichtigungen über API-Statusänderungen nutzen Sie die Mailingliste für Entwickler.
- Wenn Sie alle aktuellen Diskussionen zur API verfolgen möchten, klicken Sie auf der API-Seite auf die Schaltfläche Ansehen GitHub Dazu müssen Sie über einen GitHub-Artikel Konto.
- Wenn du allgemeine Updates zur Privacy Sandbox erhalten möchtest, abonniere den RSS-Feed [Fortschritt bei der Privacy Sandbox].
- An geplanten Aufrufen für die Protected Audience API teilnehmen (in jeder zweiten Woche). Alle sind willkommen – um sich zu beteiligen, müssen Sie der WICG beitreten. Ich aktiv mitmachen oder einfach zuhören können!