Protected Audience API: Entwicklerleitfaden

Entwicklerleitfaden für On-Device-Anzeigenauktionen zur Bereitstellung von Remarketing-Anzeigen und Anzeigen mit benutzerdefinierten Zielgruppen ohne websiteübergreifendes Drittanbieter-Tracking.

Wenn Sie die Protected Audience API noch nicht kennen, lesen Sie die Übersicht über die Protected Audience API. Dort finden Sie eine allgemeine Beschreibung der API.

Dieser Beitrag ist für Entwickler als technische Referenz für die neueste Version der experimentellen Protected Audience API gedacht. Eine Demo einer einfachen Protected Audience API-Bereitstellung ist verfügbar, ebenso wie API-Referenzen für Anzeigenkäufer und ‑verkäufer.

Implementierungsstatus

Wenn Sie über Statusänderungen in der API benachrichtigt werden möchten, melden Sie sich für die Mailingliste für Entwickler an.

Was ist die Protected Audience API?

Die Protected Audience API ist eine Privacy Sandbox-API für Remarketing und benutzerdefinierte Zielgruppen. Sie ist so konzipiert, dass sie nicht von Dritten verwendet werden kann, um das Browserverhalten von Nutzern websiteübergreifend zu erfassen. Die API ermöglicht On-Device-Auktionen durch den Browser, um relevante Anzeigen für Websites auszuwählen, die der Nutzer zuvor besucht hat.

Die Protected Audience API ist das erste Experiment, das in Chromium im Rahmen der TURTLEDOVE-Vorschläge implementiert wird.

Protected Audience API testen

Verfügbare API-Referenz

Dieses Dokument bietet eine Übersicht der Protected Audience API. So suchen Sie nach bestimmten API-Methoden und ‑Parametern:

Weitere Informationen zu Best Practices für die Latenz bei Anzeigenauktionen mit der Protected Audience API

Protected Audience API – Demo

Eine Anleitung für die grundlegende Bereitstellung der Protected Audience API auf Websites von Werbetreibenden und Publishern finden Sie unter protected-audience-demo.web.app/.

In diesem Video zur End-to-End-Bereitstellung erfahren Sie, wie der Democode für die Protected Audience API funktioniert und wie Sie die Chrome-Entwicklertools zur 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 dem Desktop testen:

Anzeigen in iFrames oder Fenced Frames rendern

Anzeigen können in einem <iframe> oder einem <fencedframe> gerendert werden, je nachdem, welche Flags festgelegt 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

Fügen Sie das BiddingAndScoringDebugReportingAPI-Flag hinzu, um temporäre Methoden für die Fehlerbehebung bei Berichten zu Gewinn/Verlust zu aktivieren.

Unterstützte Funktionen

Die Protected Audience API hinter Funktions-Flags in Chromium ist ein erster Test der folgenden Funktionen der Protected Audience API:

  • Interessengruppen: Werden vom Browser gespeichert und enthalten zugehörige Metadaten zum Konfigurieren von Geboten und Rendering von Anzeigen.
  • Gebotsabgabe auf dem Gerät durch Käufer (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 von Käufern.
  • Anzeigenrendering in einer vorübergehend gelockerten Version von Fenced Frames: Netzwerkzugriff und Logging sind für das Anzeigenrendering zulässig.

Weitere Informationen zur Unterstützung von Funktionen und zu Einschränkungen finden Sie im Explainer zur Protected Audience API.

Berechtigungen für Interessengruppen

Bei der aktuellen Implementierung der Protected Audience API ist es standardmäßig zulässig, joinAdInterestGroup() von überall auf einer Seite aufzurufen, auch von domainübergreifenden iFrames.

In Zukunft, wenn Websiteinhaber Zeit hatten, ihre domainübergreifenden iFrame-Berechtigungsrichtlinien zu aktualisieren, sollen Aufrufe von domainübergreifenden iFrames nicht mehr zulässig sein.

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 möchten möglicherweise das verbleibende Budget in einer Werbekampagne berechnen.
  • Verkäufer müssen möglicherweise Anzeigen-Creatives anhand der Publisher-Richtlinien prüfen.

Der Protected Audience API-Schlüssel/Wert-Dienstcode ist jetzt verfügbar. Blogpost zur Ankündigung

Für erste Tests wurde ein Bring Your Own Server-Modell eingeführt. Langfristig müssen Ad-Tech-Unternehmen die Open-Source-Protected Audience API Key/Value-Dienste verwenden, die in vertrauenswürdigen Ausführungsumgebungen ausgeführt werden.

Aktuelle Informationen zum Zeitplan finden Sie im Blogbeitrag zu Protected Audience API-Diensten. Wir werden Entwickler rechtzeitig benachrichtigen, damit sie vor der Umstellung mit dem Testen 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 besucht ein Nutzer die Website eines Herstellers von Custom-Bikes. Später ruft er eine Nachrichtenwebsite auf und sieht dort eine Anzeige für ein neues Fahrrad des Herstellers.

Im Laufe der Zeit werden weitere Funktionen der Protected Audience API hinzugefügt, wenn die Implementierung voranschreitet.

1. Ein Nutzer besucht die Website eines Werbetreibenden.

Eine Person ruft die Website eines Herstellers von Custom-Bikes in einem Browser auf ihrem Laptop auf.

Angenommen, ein Nutzer besucht die Website eines Herstellers von Custom-Bikes (dem Werbetreibenden in diesem Beispiel) und verbringt einige Zeit auf der Produktseite für ein handgefertigtes Stahlfahrrad. So hat der Fahrradhersteller die Möglichkeit zum Remarketing.

2. Der Browser des Nutzers wird aufgefordert, eine Interessengruppe hinzuzufügen.

Ein Nutzer öffnet einen Browser auf seinem Laptop und besucht eine Website. JavaScript-Code zum Beitreten von Anzeigengruppen mit gemeinsamen Interessen wird im Browser ausgeführt.

Die Demand-Side-Plattform (DSP) des Werbetreibenden (oder der Werbetreibende selbst) ruft navigator.joinAdInterestGroup() auf, um den Browser aufzufordern, eine Interessengruppe der Liste der Gruppen hinzuzufügen, deren Mitglied der Browser 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 in der Anzeigenauktion mit der Protected Audience API. Die Zugehörigkeit zu Interessengruppen wird vom Browser auf dem Gerät des Nutzers gespeichert und nicht an den Browseranbieter oder andere weitergegeben.

Anzeigen für eine Interessengruppe angeben

ads- und adComponents-Objekte enthalten eine URL für ein Anzeigen-Creative und optional beliebige Metadaten, die bei 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, wenn der Inhaber der Interessengruppe zur Gebotsabgabe eingeladen wird.

Entwicklerdokumentation zu generatedBid()

3. Der Nutzer besucht eine Website, auf der Werbeflächen verkauft werden.

Eine Person besucht eine Nachrichtenwebsite in einem Browser auf ihrem Laptop. Die Website hat eine leere Anzeigenfläche.

Später besucht der Nutzer eine Website, auf der Werbeflächen verkauft werden, in diesem Beispiel eine Nachrichtenwebsite. Die Website verfügt über Anzeigeninventar, das programmatisch über Echtzeitgebote verkauft wird.

4. Im Browser wird eine Anzeigenauktion durchgeführt.

Eine Person ruft eine Nachrichtenwebsite in einem Browser auf ihrem Laptop auf. Es wird eine Anzeigenauktion mit der Protected Audience API durchgeführt, um eine Anzeige für die verfügbare Werbefläche auszuwählen.

Die Anzeigenauktion wird wahrscheinlich vom Supply-Side-Anbieter (SSP) des Publishers oder vom Publisher selbst durchgeführt. Bei der Auktion wird die am besten geeignete Anzeige für eine einzelne verfügbare Anzeigenfläche auf der aktuellen Seite ausgewählt. Bei der Auktion werden die Interessengruppen berücksichtigt, denen der Browser angehört, sowie Daten von Käufern und Verkäufern von Werbeflächen aus den Schlüssel/Wert-Diensten.

5. Der Verkäufer und die teilnehmenden Käufer fordern Echtzeitdaten vom Schlüssel/Wert-Dienst an.

Der Nutzer ruft eine Nachrichtenwebsite in einem Browser auf seinem Laptop auf. Eine Anzeigenauktion mit der Protected Audience API findet statt und ein Teilnehmer ruft Daten vom Schlüssel/Wert-Dienst ab.

Während einer Anzeigenauktion kann der Verkäufer Echtzeitdaten zu bestimmten Anzeigen-Creatives anfordern, indem er eine Anfrage an seinen Schlüssel/Wert-Dienst sendet. Der Verkäufer kann diese Informationen während runAdAuction() über die Property trustedScoringSignalsUrl anfordern. Außerdem werden die Schlüssel aus den renderUrl-Properties aller Einträge in den Feldern ads und adComponents aller Interessengruppen in der Auktion bereitgestellt.

Ein Käufer kann Echtzeitdaten von seinem Schlüssel/Wert-Dienst über die Eigenschaften trustedBiddingSignalsUrl und trustedBiddingSignalsKeys des Interest Group-Arguments anfordern, das an navigator.joinAdInterestGroup() übergeben wird.

Wenn runAdAuction() aufgerufen wird, sendet der Browser eine Anfrage an den vertrauenswürdigen Server jedes Werbetreibenden. Die URL für die Anfrage könnte so 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 aus trustedBiddingSignalsKeys übernommen.

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

6. Die Gewinneranzeige wird ausgeliefert

Eine Person ruft eine Nachrichtenwebsite in einem Browser auf ihrem Laptop auf. Eine Anzeige mit 20% Rabatt auf ein Fahrrad wird in einem sicheren, umzäunten Frame präsentiert.

Das von runAdAuction() zurückgegebene Promise wird in ein Fenced Frame-Konfigurationsobjekt (FencedFrameConfig) aufgelöst, wenn das Flag resolveToConfig in der Auktionskonfiguration auf true gesetzt ist. Die Frame-Konfiguration wird von einem Fenced Frame verwendet, um den Frame zur Gewinneranzeige zu navigieren. Die URL der Anzeige ist für den Frame-Einbetter jedoch nicht sichtbar.

Das Konfigurationsobjekt für den umzäunten Frame ist ab M114 verfügbar. Weitere Informationen zum FencedFrameConfig-Objekt finden Sie im Chrome-Blogartikel.

7. Das Auktionsergebnis wird gemeldet

Langfristig soll der Browser mithilfe der Private Aggregation APIs Auktionsergebnisse für den Verkäufer und die Käufer melden können.

Als temporärer Berichtsmechanismus auf Ereignisebene kann der Code, der reportResult() für den Verkäufer und reportWin() für den erfolgreichen Bieter implementiert, die Funktion sendReportTo() aufrufen. Dafür ist ein einzelnes Argument erforderlich: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird. In dieser URL sind Informationen auf Ereignisebene enthalten, die gemeldet werden sollen.

8. Ein Anzeigenklick wird erfasst

Ein Nutzer klickt auf einer Nachrichtenwebsite auf eine Anzeige für ein Fahrrad, die in einem umrandeten Frame eingebettet ist. Die Berichtsdaten werden an Verkäufer und Käufer gesendet.

Ein Klick auf eine Anzeige, die in einem Fenced Frame gerendert wird, wird erfasst. Weitere Informationen dazu, wie das funktionieren kann, finden Sie unter Berichte zu Anzeigen in Fenced Frames.

Übersicht über die einzelnen Phasen einer Anzeigenauktion mit der Protected Audience API
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 das erste Experiment, das in Chromium im Rahmen der TURTLEDOVE-Vorschläge implementiert wird.

Die Protected Audience API folgt den allgemeinen Grundsätzen von TURTLEDOVE. Bei einigen Formen der Online-Werbung wird eine Anzeige für eine Person geschaltet, die möglicherweise Interesse hat und zuvor mit dem Werbetreibenden oder dem Werbenetzwerk interagiert hat. Bisher wurde dies dadurch erreicht, dass der Werbetreibende eine bestimmte Person beim Surfen auf Websites erkannt hat. Dies ist ein zentrales Datenschutzproblem im heutigen Web.

Bei TURTLEDOVE geht es darum, eine neue API für diesen Anwendungsfall anzubieten, die einige wichtige Datenschutzverbesserungen bietet:

  • Der Browser und nicht der Werbetreibende enthält die Informationen darüber, wofür sich eine Person interessiert.
  • Werbetreibende können Anzeigen basierend auf einem Interesse schalten, dürfen dieses Interesse jedoch nicht mit anderen Informationen über eine Person kombinieren, insbesondere nicht mit Informationen darüber, wer die Person ist oder welche Seite sie besucht.

Die Protected Audience API ist aus TURTLEDOVE und einer Reihe verwandter Vorschläge für Änderungen hervorgegangen, die besser auf die Entwickler zugeschnitten sind, die die API verwenden:

  • In SPARROW: Criteo schlug die Ergänzung eines („Gatekeeper“-)Dienstmodells vor, das in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt wird. Die Protected Audience API umfasst eine eingeschränktere Verwendung von TEEs für die Echtzeit-Datensuche und aggregierte Berichte.
  • In den Vorschlägen von NextRoll TERN und Magnite PARRROT wurden die verschiedenen Rollen beschrieben, die Käufer und Verkäufer bei der On-Device-Auktion hatten. Der Ablauf für Gebote und Scoring der Protected Audience API basiert auf dieser Arbeit.
  • Die ergebnisbasierten und produktbezogenen TURTLEDOVE-Änderungen von RTB House haben das Anonymitätsmodell und die Personalisierungsfunktionen der On-Device-Auktion verbessert.
  • PARAKEET ist der Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst, der auf einem Proxyserver basiert, der in einer TEE zwischen dem Browser und den Anzeigentechnologie-Anbietern ausgeführt wird, um Anzeigenanfragen zu anonymisieren und Datenschutzfunktionen zu erzwingen. Bei der Protected Audience API wird dieses Proxying-Modell nicht verwendet. Wir gleichen die JavaScript-APIs für PARAKEET und die Protected Audience API an, um zukünftige Arbeiten zur weiteren Kombination der besten Funktionen beider Vorschläge zu unterstützen.

Die Protected Audience API verhindert noch nicht, dass das Werbenetzwerk einer Website erfährt, welche Anzeigen eine Person sieht. Wir gehen davon aus, dass wir die API im Laufe der Zeit so anpassen werden, dass sie mehr Datenschutz bietet.

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 von einem Verkäufer oder Bieter als Kontextinformationen verwendet werden. Ein Thema kann in den folgenden Properties enthalten sein:

  • auctionSignals, eine Eigenschaft des Auktionskonfigurationsobjekts, das an navigator.runAdAuction() übergeben wird
  • userBiddingSignals, eine Eigenschaft des Konfigurationsobjekts der Interessengruppe, das an navigator.joinAdInterestGroup() übergeben wird

Verfügbare Browserkonfiguration

Nutzer können ihre Teilnahme an Privacy Sandbox-Tests in Chrome anpassen, indem sie die Einstellung auf oberster Ebene in chrome://settings/adPrivacy aktivieren oder deaktivieren.

Während der ersten Testphase können Nutzer diese allgemeine Privacy Sandbox-Einstellung verwenden, um die Protected Audience API zu deaktivieren. In Chrome soll es Nutzern möglich sein, die Liste der Interessengruppen, denen sie auf den von ihnen besuchten Websites hinzugefügt wurden, anzusehen und zu verwalten. Wie bei den Privacy Sandbox-Technologien selbst können sich auch die Nutzereinstellungen durch Feedback von Nutzern, Aufsichtsbehörden und anderen ändern.

Wir werden die verfügbaren Einstellungen in Chrome basierend auf Tests und Feedback weiterhin aktualisieren. In Zukunft möchten wir detailliertere Einstellungen zur Verwaltung der Protected Audience API und der zugehörigen Daten anbieten.

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 für Gebotsgenerierung und Berichterstellung des Käufers sowie die Worklets für Anzeigenbewertung und Berichterstellung des Verkäufers), werden vom Browser im Cache gespeichert. Mit dem Header Cache-Control können Sie das Caching-Verhalten steuern.

Feedback geben

Support kontaktieren

So können Sie Fragen stellen und Support für Ihre Implementierung, die Demo oder die Dokumentation erhalten:

Bei allgemeinen Fragen zur Protected Audience API erstellen Sie ein Problem im API-Repository. Sie können Branchenanwendungsfälle auch in der Improving Web Advertising Business Group des W3C diskutieren.

Mit dem Privacy Sandbox-Feedbackformular können Sie Feedback vertraulich mit dem Chrome-Team teilen, ohne öffentliche Foren zu nutzen.

Deaktivieren

Möchten Sie die Protected Audience API deaktivieren? Weitere Informationen zum Blockieren des Zugriffs auf die Protected Audience API als Websiteinhaber oder einzelner Nutzer

Immer auf dem neuesten Stand bleiben