Protected Audience API: Entwicklerleitfaden

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

Wenn Sie die Protected Audience API noch nicht kennen, lesen Sie den Hilfeartikel Protected Audience API – Übersicht. Dort finden Sie eine allgemeine Erklärung der API.

Dieser Beitrag richtet sich an Entwickler und dient als technische Referenz für die neueste Version der experimentellen Protected Audience API. Es gibt eine Demo für eine grundlegende 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, die für Remarketing und benutzerdefinierte Zielgruppen entwickelt wurde. Sie kann nicht von Dritten verwendet werden, um das Browserverhalten von Nutzern über Websites hinweg zu verfolgen. 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 der erste Test, der in Chromium im Rahmen der TURTLEDOVE-Angebotsfamilie implementiert wird.

Protected Audience API testen

Verfügbare API-Referenz

Dieses Dokument dient als Übersicht über die Protected Audience API. Wenn Sie nach bestimmten API-Methoden und ‑Parametern suchen:

Weitere Informationen finden Sie unter Best Practices für die Latenz bei Protected Audience API-Anzeigenauktionen.

Protected Audience API – Demo

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

In dieser End-to-End-Bereitstellung erfahren Sie, wie der Democode der 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 Computer testen:

Anzeigen in iFrames oder abgegrenzten Frames rendern

Anzeigen können je nach festgelegten Flags in einem <iframe> oder einem <fencedframe> 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 BiddingAndScoringDebugReportingAPI-Flag hinzu, um vorübergehende Methoden zur Berichterstellung zu Verlusten/Gewinnen bei der Fehlerbehebung 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 mit zugehörigen Metadaten gespeichert, um die Gebotsabgabe und das Rendering von Anzeigen zu konfigurieren.
  • On-Device-Gebote von Käufern (DSP oder Werbetreibender): basierend auf gespeicherten Interessengruppen und Signalen des Verkäufers.
  • On-Device-Anzeigenauswahl durch den Verkäufer (SSP oder Publisher): Basierend auf Auktionsgeboten und Metadaten von Käufern.
  • Anzeigen-Rendering in einer vorübergehend gelockerten Version von Fenced Frames: Netzwerkzugriff und Logging sind für das Anzeigen-Rendering zulässig.

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

Berechtigungen für Interessengruppen

Standardmäßig ist bei der aktuellen Implementierung der Protected Audience API der Aufruf von joinAdInterestGroup() von überall auf einer Seite zulässig, auch von domainübergreifenden iFrames.

Sobald Websiteinhaber Zeit hatten, ihre Berechtigungsrichtlinien für domainübergreifende iFrames zu aktualisieren, werden Aufrufe von domainübergreifenden iFrames nicht mehr zugelassen.

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 prüfen, ob Anzeigen-Creatives den Publisher-Richtlinien entsprechen.

Der Schlüssel/Wert-Dienstcode der Protected Audience API ist jetzt verfügbar. Aktuelle Informationen zum Status finden Sie im Blogpost zur Ankündigung.

Für die ersten Tests wurde ein Bring Your Own Server-Modell eingeführt. Langfristig müssen Anbieter von Anzeigentechnologien die Open-Source-API-Schlüssel/Wert-Dienste von Protected Audience verwenden, die in vertrauenswürdigen Ausführungsumgebungen ausgeführt werden.

Aktuelle Informationen zum Zeitplan finden Sie im Blogpost zu Protected Audience API-Diensten. Wir informieren Entwickler rechtzeitig, damit sie vor der Umstellung mit 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 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 sieht sich ein Nutzer die Website eines Herstellers von individuellen Fahrrädern an und besucht später eine Nachrichtenwebsite. Dort wird ihm eine Anzeige für ein neues Fahrrad des Herstellers präsentiert.

Im Laufe der Zeit werden der Protected Audience API weitere Funktionen hinzugefügt.

1. Ein Nutzer besucht die Website eines Werbetreibenden

Eine Person besucht die Website eines Herstellers von Sonderanfertigungen für Fahrräder in einem Browser auf ihrem Laptop.

Angenommen, ein Nutzer besucht die Website eines Herstellers von individuell gefertigten Fahrrädern (in diesem Beispiel der Werbetreibende) und verbringt einige Zeit auf der Produktseite für ein handgefertigtes Stahlfahrrad. Das bietet dem 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. Der JavaScript-Code für die Teilnahme an Anzeigeninteressengruppen wird im Browser ausgeführt.

Die Demand-Side-Platform (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 Eigentümer ist dsp.example. Der Inhaber der Interessengruppe (in diesem Fall die DSP) ist ein Käufer in der Protected Audience API-Anzeigenauktion. 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 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, deren Mitglied der Browser ist, wenn der Inhaber der Interessengruppe zum Gebotsabgeben eingeladen wird.

Weitere Informationen finden Sie in der generatedBid()-Entwicklerdokumentation.

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

Eine Person besucht eine Nachrichtenwebsite in einem Browser auf ihrem Laptop. Auf der Website gibt es einen leeren Anzeigenblock.

Später besucht der Nutzer eine Website, auf der Anzeigenflächen verkauft werden, in diesem Beispiel eine Nachrichtenwebsite. Die Website hat 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. Es wird eine Protected Audience API-Anzeigenauktion durchgeführt, um eine Anzeige für die verfügbare Anzeigenfläche auszuwählen.

Die Anzeigenauktion wird wahrscheinlich vom Supply-Side-Anbieter (SSP) des Publishers oder vom Publisher selbst durchgeführt. Ziel der Auktion ist es, die am besten geeignete Anzeige für einen einzelnen verfügbaren Anzeigenblock auf der aktuellen Seite auszuwählen. Bei der Auktion werden die Interessengruppen berücksichtigt, zu denen der Browser gehört, sowie Daten von Käufern und Verkäufern von Anzeigenflä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. Es findet eine Anzeigenauktion mit der Protected Audience API statt, bei der ein Teilnehmer Daten vom Schlüssel/Wert-Dienst erhält.

Während einer Anzeigenauktion kann der Verkäufer Echtzeitdaten zu bestimmten 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, zusammen mit den Schlüsseln aus den renderUrl-Properties aller Einträge in den Feldern ads und adComponents aller Interessengruppen in der Auktion.

Ein Käufer kann Echtzeitdaten von seinem Schlüssel/Wert-Dienst anfordern, indem er die Eigenschaften trustedBiddingSignalsUrl und trustedBiddingSignalsKeys des an navigator.joinAdInterestGroup() übergebenen Interessengruppenarguments verwendet.

Wenn runAdAuction() aufgerufen wird, stellt der Browser eine Anfrage an den vertrauenswürdigen Server jedes Anzeigenkäufers. 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.
  • Die hostname wird vom Browser bereitgestellt.
  • Der Wert keys wird aus trustedBiddingSignalsKeys übernommen.

Die Antwort auf diese Anfrage ist ein JSON-Objekt mit Werten für jeden der Schlüssel.

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 Rahmen angezeigt.

Das von runAdAuction() zurückgegebene Versprechen wird in ein Objekt für die Konfiguration von eingezäunten Frames (FencedFrameConfig) aufgelöst, wenn das Flag resolveToConfig in der Auktionskonfiguration auf true festgelegt ist. Die Frame-Konfiguration wird von einem eingegrenzten Frame verwendet, um den Frame zur Gewinneranzeige zu steuern. Die URL der Anzeige ist für den Einbettungs-Frame jedoch nicht sichtbar.

Das Konfigurationsobjekt für eingezäunte Frames ist ab M114 verfügbar. Weitere Informationen zum FencedFrameConfig-Objekt finden Sie im Chrome-Blogartikel.

7. Das Auktionsergebnis wird erfasst

Langfristig soll der Browser mithilfe der Private Aggregation APIs Auktionsergebnisse für Verkäufer und 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. Es nimmt ein einziges Argument an: einen String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird. Diese URL enthält Informationen auf Ereignisebene, die erfasst werden sollen.

8. Ein Anzeigenklick wird erfasst

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

Ein Klick auf eine Anzeige, die in einem abgegrenzten Frame gerendert wird, wird erfasst. Weitere Informationen dazu finden Sie im Hilfeartikel Berichte zu Anzeigen in abgegrenzten Frames.

Übersicht über die einzelnen Phasen einer Protected Audience API-Anzeigenauktion
In diesem Diagramm sind 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-Angebote implementiert wird.

Die Protected Audience API folgt den allgemeinen Prinzipien von TURTLEDOVE. Bei einigen Onlineanzeigen wurde eine Anzeige einer potenziell interessierten Person präsentiert, die zuvor mit dem Werbetreibenden oder dem Werbenetzwerk interagiert hat. Bisher wurde dies dadurch erreicht, dass der Werbetreibende eine bestimmte Person erkannte, während sie im Web surfte. Dies ist ein zentrales Datenschutzproblem im heutigen Web.

Das TURTLEDOVE-Projekt zielt darauf ab, eine neue API für diesen Anwendungsfall anzubieten und gleichzeitig einige wichtige Fortschritte im Datenschutz zu erzielen:

  • Der Browser, nicht der Werbetreibende, speichert die Informationen dazu, woran der Werbetreibende glaubt, dass eine Person interessiert ist.
  • Werbetreibende können Anzeigen basierend auf einem Interesse schalten, dieses Interesse jedoch nicht mit anderen Informationen über eine Person kombinieren, insbesondere nicht mit Informationen dazu, wer die Person ist oder welche Seite sie besucht.

Die Protected Audience API wurde aus TURTLEDOVE und einer Reihe von Vorschlägen für Änderungen entwickelt, um die API für die Entwickler, die sie verwenden, besser zu machen:

  • In SPARROW: Criteo schlug vor, ein Dienstmodell („Gatekeeper“) hinzuzufügen, das in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt wird. Die Protected Audience API umfasst eine eingeschränktere Nutzung von TEEs für die Echtzeitdatenabfrage und aggregierte Berichte.
  • In den Vorschlägen von NextRoll (TERN) und Magnite (PARRROT) wurden die verschiedenen Rollen von Käufern und Verkäufern in der On-Device-Auktion beschrieben. Der Ablauf für Gebote und Bewertungen bei der Protected Audience API basiert auf dieser Arbeit.
  • Durch die ergebnisbasierten und produktspezifischen TURTLEDOVE-Änderungen von RTB House wurden das Anonymitätsmodell und die Personalisierungsmöglichkeiten der On-Device-Auktion verbessert.
  • PARAKEET ist der Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst, der auf einem Proxyserver basiert, der in einem TEE zwischen dem Browser und den Anbietern von Anzeigentechnologien ausgeführt wird, um Anzeigenanfragen zu anonymisieren und Datenschutzeigenschaften durchzusetzen. Bei der Protected Audience API wird dieses Proxy-Modell nicht verwendet. Wir bringen die JavaScript APIs für PARAKEET und die Protected Audience API in Einklang, 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 werden die API voraussichtlich im Laufe der Zeit so ändern, dass sie datenschutzfreundlicher wird.

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 kontextbezogene Information verwendet werden. Ein Thema kann in den folgenden Properties enthalten sein:

  • auctionSignals, eine Eigenschaft des Auktionskonfigurationsobjekts, die an navigator.runAdAuction() übergeben wird
  • userBiddingSignals, ein Attribut des Konfigurationsobjekts für Interessengruppen, 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 der obersten 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. In Chrome sollen Nutzer künftig die Liste der Interessengruppen einsehen und verwalten können, denen sie auf den von ihnen besuchten Websites hinzugefügt wurden. Wie bei den Privacy Sandbox-Technologien selbst können sich die Nutzereinstellungen auch anhand von Feedback von Nutzern, Regulierungsbehörden und anderen entwickeln.

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

API-Caller 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 Worklets zur 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 und erhalten

Support anfordern

So stellen Sie Fragen und erhalten Support bei der Implementierung, der Demo oder der Dokumentation:

Wenn Sie allgemeinere Fragen dazu haben, ob die Protected Audience API Ihre Anforderungen erfüllt, erstellen Sie bitte ein Problem im API-Repository. Sie können auch Anwendungsfälle aus der Branche in der Improving Web Advertising Business Group des W3C besprechen.

Über das Feedbackformular für die Privacy Sandbox können Sie außerhalb öffentlicher Foren Feedback direkt an das Chrome-Team senden.

Deaktivieren

Möchten Sie die Protected Audience API deaktivieren? Hier erfahren Sie, wie Sie als Websiteinhaber oder einzelner Nutzer den Zugriff auf die Protected Audience API blockieren.

Immer auf dem neuesten Stand bleiben