Protected Audience API: Entwicklerleitfaden

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

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:

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">
</ph> <ph type="x-smartling-placeholder"></ph>
In dieser End-to-End-Bereitstellung erfahren Sie, wie der Democode der Protected Audience API funktioniert und wie Sie die Chrome-Entwicklertools für die Fehlerbehebung verwenden.

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:

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

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.

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.

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.

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.

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.

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.

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 von trustedBiddingSignalsKeys übernommen.

Die Antwort auf diese Anfrage ist ein JSON-Objekt, das Werte für jede der Schlüssel.

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.

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.

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.

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.

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">
</ph> <ph type="x-smartling-placeholder"></ph> Eine Übersicht über die einzelnen Phasen einer Protected Audience API-Anzeigenauktion
In diesem Diagramm werden die einzelnen Phasen einer Protected Audience API-Auktion dargestellt.

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 an navigator.runAdAuction() übergeben wird
  • userBiddingSignals, ein Attribut der Interessengruppenkonfiguration Objekt an navigator.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:

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