Protected Audience API: Entwicklerleitfaden

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

Wenn Sie die Protected Audience API noch nicht kennen, erhalten Sie in der Protected Audience API-Übersicht eine allgemeine Erläuterung der API.

Dieser Beitrag richtet sich an Entwickler als technische Referenz für die neueste Iteration der experimentellen Protected Audience API. Es sind eine Demo einer einfachen Protected Audience API-Bereitstellung sowie API-Referenzen für Anzeigenkäufer und ‐verkäufer verfügbar.

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 Remarketing und benutzerdefinierte Zielgruppen. Sie ist so konzipiert, dass sie von Drittanbietern nicht verwendet werden kann, um das Browserverhalten von Nutzern websiteübergreifend zu verfolgen. 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 TURTLEDOVE-Angebote 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:

Weitere Informationen finden Sie in den Best Practices zur Latenz bei Anzeigenauktionen der Protected Audience API.

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 protection-audience-demo.web.app/.

In diesem End-to-End-Deployment erfahren Sie, wie der Democode für die Protected Audience API funktioniert und wie Sie die Chrome-Entwicklertools für die Fehlerbehebung verwenden.

Mit chrome://flags oder Funktions-Flags testen

Sie können die Protected Audience API für einen einzelnen Nutzer in Chrome Beta 101.0.4951.26 und höher auf Computern testen:

Anzeigen in iFrames oder Fence Frames rendern

Anzeigen können in einem <iframe>- oder <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 Flag BiddingAndScoringDebugReportingAPI ein, um temporäre Methoden zum Melden von Verlusten/Gewinnen bei der Fehlerbehebung zu aktivieren.

Unterstützte Features

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

  • Interessengruppen: werden vom Browser zusammen mit zugehörigen Metadaten gespeichert, um Gebote und das Rendering von Anzeigen zu konfigurieren.
  • On-Device-Gebote von Käufern (DSP oder Werbetreibenden): basieren auf gespeicherten Interessengruppen und Signalen vom Verkäufer.
  • 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

Bei der aktuellen Implementierung der Protected Audience API ist der Aufruf von joinAdInterestGroup() standardmäßig von überall auf der Seite möglich, selbst über domainübergreifende iFrames.

Wenn Websiteinhaber in Zukunft ihre Berechtigungsrichtlinien für domainübergreifende iFrames aktualisieren konnten, sollen Aufrufe von domainübergreifenden iFrames nicht mehr zulässig sein.

Schlüssel/Wert-Dienst

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 Weise verwendet werden:

  • Käufer möchten vielleicht das verbleibende Budget in einer Werbekampagne berechnen.
  • Unter Umständen müssen Verkäufer ihre Creatives auf Einhaltung der Publisher-Richtlinien überprüfen.

Der Schlüssel/Wert-Dienstcode der Protected Audience API ist jetzt verfügbar. Den aktuellen Status finden Sie im Blogpost zu Ankündigungen.

Für erste Tests wurde das Modell Nutzung eigener Server 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.

Informationen zum Zeitplan finden Sie im Blogpost zu den Protected Audience API-Diensten. Wir informieren Entwickler rechtzeitig, damit sie schon vor der Umstellung mit dem Testen und der Akzeptanz beginnen können.

Erkennung von Featureunterstützung

Bevor Sie die API verwenden, prüfen Sie, 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 sieht sich ein Nutzer die Website eines Fahrradherstellers an, besucht später eine Nachrichtenwebsite und sieht dort eine Anzeige für ein neues Fahrrad des Fahrradherstellers.

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

1. Ein Nutzer besucht die Website eines Werbetreibenden.

Eine Person besucht die Website eines Herstellers von Fahrrädern in einem Browser auf ihrem Laptop.

Angenommen, ein Nutzer besucht die Website eines kundenspezifischen Fahrradherstellers (in diesem Beispiel des Werbetreibenden) und verbringt einige Zeit auf der Produktseite für ein handgefertigtes Stahlfahrrad. 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 ausgeführt, mit dem Interessengruppen für Anzeigen zusammengeführt werden.

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 Anzeigenauktion der Protected Audience API. Die Mitgliedschaft in einer Interessengruppe wird vom Browser auf dem Gerät des Nutzers gespeichert und weder an den Browseranbieter noch an Dritte weitergegeben.

Anzeigen für eine Interessengruppe angeben

Die Objekte ads und adComponents enthalten eine URL für ein Anzeigen-Creative und optional beliebige Metadaten, die zum Zeitpunkt der Gebotseinstellung 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, zu der der Browser gehört, wenn der Inhaber der Interessengruppe eingeladen wird, ein Gebot abzugeben.

Lesen Sie die generatedBid()-Entwicklerdokumentation.

3. Der Nutzer besucht eine Website, auf der Werbefläche verkauft wird.

Eine Person besucht in einem Browser auf ihrem Laptop eine Nachrichtenwebsite. Die Anzeigenfläche auf der Website ist leer.

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 mit Echtzeitgeboten verkauft wird.

4. Eine Anzeigenauktion wird im Browser ausgeführt.

Ein Nutzer ruft eine Nachrichtenwebsite in einem Browser auf seinem Laptop auf. Bei einer Protected Audience API-Anzeigenauktion wird eine Anzeige für die verfügbare Werbefläche ausgewählt.

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. Die Auktion berücksichtigt die Interessengruppen, denen der Browser angehört, sowie Daten von Käufern von Werbeflächen und von Verkäufern aus den Schlüssel/Wert-Diensten.

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

Die nutzende Person sieht sich eine Nachrichtenwebsite in einem Browser auf ihrem Laptop an. Es findet eine Anzeigenauktion mit der Protected Audience API statt. Dabei erhält ein Teilnehmer Daten aus dem Schlüssel/Wert-Dienst.

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 in runAdAuction() mit der Property trustedScoringSignalsUrl zusammen mit den Schlüsseln aus den renderUrl-Eigenschaften aller Einträge in den Feldern ads und adComponents aller Interessengruppen in der Auktion anfordern.

Käufer können Echtzeitdaten von ihrem Schlüssel/Wert-Dienst anfordern, indem sie die Attribute trustedBiddingSignalsUrl und trustedBiddingSignalsKeys des Interessengruppenarguments verwenden, das an navigator.joinAdInterestGroup() übergeben wird.

Wenn runAdAuction() aufgerufen wird, sendet 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.
  • 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 bereitstellt.

6. Die erfolgreiche Anzeige wird ausgeliefert.

Ein Nutzer ruft eine Nachrichtenwebsite in einem Browser auf seinem Laptop auf. In einem sicheren, eingezäunten Rahmen ist eine Anzeige für einen Rabatt von 20% auf ein Fahrrad zu sehen.

Das von runAdAuction() zurückgegebene Promise wird in ein Fence-Frame-Konfigurationsobjekt (FencedFrameConfig) aufgelöst, wenn das Flag resolveToConfig in der Auktionskonfiguration auf true festgelegt ist. Die Frame-Konfiguration wird von einem Fenced Frame verwendet, um den Frame zur erfolgreichen Anzeige zu bewegen, aber die URL der Anzeige ist für den Frame-Einbettunger nicht sichtbar.

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

7. Das Auktionsergebnis wird erfasst

Langfristig ist geplant, dass der Browser über die Private Aggregation APIs Auktionsergebnisse für Verkäufer und Käufer erstellen kann.

Als vorübergehender Mechanismus für die Berichterstellung 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 einziges Argument benötigt: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird. Dieser String codiert die Informationen auf Ereignisebene, die gemeldet werden sollen.

8. Ein Anzeigenklick wird erfasst.

Eine Person klickt auf einer Nachrichtenwebsite auf eine Anzeige für ein Fahrrad, eingebettet mit einem eingezäunten Rahmen. Die Berichtsdaten werden an Verkäufer und Käufer gesendet.

Ein Klick auf eine Anzeige, die in einem Fenced Frame gerendert wurde, wird erfasst. Weitere Informationen zur möglichen Funktionsweise finden Sie unter Berichte zu Anzeigen mit Fenced Frames.

Eine Übersicht über die einzelnen Phasen einer Protected Audience API-Anzeigenauktion
In diesem Diagramm werden die einzelnen Phasen einer Protected Audience API-Auktion veranschaulicht.

Was ist der Unterschied zwischen der Protected Audience API und TURTLEDOVE?

Die Protected Audience API ist der erste Test, der in Chromium innerhalb der TURTLEDOVE-Angebote implementiert wird.

Die Protected Audience API entspricht den allgemeinen Prinzipien von TURTLEDOVE. Ein Teil der Onlinewerbung basiert darauf, eine Anzeige einer potenziell interessierten Person zu präsentieren, die bereits mit dem Werbetreibenden oder dem Werbenetzwerk interagiert hat. In der Vergangenheit hat das so getan, dass Werbetreibende beim Surfen auf Websites eine bestimmte Person anerkennen. Dies ist ein zentrales Thema des Datenschutzes im heutigen Web.

Bei TURTLEDOVE geht es darum, eine neue API für diesen Anwendungsfall anzubieten und gleichzeitig einige wichtige Verbesserungen beim Datenschutz zu bieten:

  • Die Informationen darüber, was nach Ansicht des Werbetreibenden eine Person interessiert, enthält der Browser, nicht der Werbetreibende.
  • Werbetreibende können Anzeigen auf Grundlage ihrer Interessen schalten, aber diese Interessen nicht mit anderen Informationen über eine Person kombinieren, insbesondere darüber, wer sie sind oder welche Seite sie besucht.

Die Protected Audience API entstand aus TURTLEDOVE und einer Reihe ähnlicher Änderungsvorschläge für Entwickler, die die API verwenden würden:

  • In SPARROW hat Criteo das Hinzufügen eines „Gatekeeper“-Dienstmodells vorgeschlagen, das in einer Trusted Execution Environment (TEE) ausgeführt wird. Die Protected Audience API umfasst eine eingeschränktere Nutzung von TEEs, um Daten in Echtzeit abzurufen und aggregierte Berichte zu erstellen.
  • In den PARRROT-Angeboten von NextRoll wurden die Rollen TERN und Magnite beschrieben, die Käufer und Verkäufer bei der On-Device-Auktion hatten. Der Ablauf der Gebotsabgabe/Bewertung bei Anzeigen der Protected Audience API basiert auf dieser Arbeit.
  • Durch die TURTLEDOVE-Änderungen auf Ergebnis- und Produktebene wurden das Anonymitätsmodell und die Personalisierungsfunktionen der On-Device-Auktion verbessert.
  • PARAKEET ist ein Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst, der einen Proxyserver verwendet, der in einem TEE zwischen dem Browser und den Anzeigentechnologie-Anbietern ausgeführt wird, um Anzeigenanfragen zu anonymisieren und Datenschutzeigenschaften zu erzwingen. Die Protected Audience API hat dieses Proxying-Modell nicht übernommen. Wir werden die JavaScript APIs für PARAKEET und die Protected Audience API aufeinander abstimmen, um die besten Funktionen beider Vorschläge weiter zu kombinieren.

Die Protected Audience API hindert das Werbenetzwerk einer Website noch nicht daran, zu erkennen, welche Anzeigen ein Nutzer sieht. Wir gehen davon aus, dass durch Änderungen an der API der Datenschutz im Laufe der Zeit verbessert wird.

Kann die Topics API mit der Protected Audience API verwendet werden?

Ja. Ein von der Topics API bereitgestelltes Thema für den aktuellen Nutzer könnte von einem Verkäufer oder Bieter als Kontextinformationen verwendet werden. Ein Thema kann in die folgenden Properties aufgenommen werden:

  • auctionSignals, ein Attribut des Auktionskonfigurationsobjekts, das an navigator.runAdAuction() übergeben wird
  • userBiddingSignals, eine Eigenschaft des Interessengruppenkonfigurationsobjekts, 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 die Protected Audience API mit dieser Einstellung der Privacy Sandbox auf hoher Ebene deaktivieren. In Chrome ist geplant, Nutzern zu ermöglichen, die Liste der Interessengruppen, denen sie auf den von ihnen besuchten Websites hinzugefügt wurden, aufzurufen und zu verwalten. Wie bei den Privacy Sandbox-Technologien selbst können sich die Nutzereinstellungen mit dem Feedback von Nutzern, Aufsichtsbehörden und anderen ändern.

Wir aktualisieren die verfügbaren Einstellungen in Chrome weiterhin auf 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, also die Worklets zur Gebotserstellung und Berichterstellung des Käufers sowie die Worklets für Anzeigenbewertung und -berichte des Verkäufers, werden vom Browser im Cache gespeichert. Mit dem Header Cache-Control können Sie das Caching-Verhalten steuern.

Reagieren und Feedback geben

Support kontaktieren

Wenn Sie Fragen stellen und Unterstützung bei der Implementierung, Demo oder Dokumentation erhalten möchten:

Wenn Sie allgemeinere Fragen zur Erfüllung Ihrer Anforderungen mit der Protected Audience API haben, melden Sie ein Problem im API-Repository. Sie können auch branchenübliche Anwendungsfälle in der Improving Web Advertising Business Group des W3C besprechen.

Über das Feedback-Formular für die Privacy Sandbox können Sie dem Chrome-Team außerhalb öffentlicher Foren privat Feedback geben.

Deaktivieren

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

Immer auf dem neuesten Stand bleiben