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, finden Sie unter Protected Audience API – Übersicht eine allgemeine Erläuterung der API.

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

Implementierungsstatus

To be notified of status changes in the API, join the mailing list for developers.

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 wurde so konzipiert, dass sie nicht von Dritten verwendet werden kann, um das Surfverhalten von Nutzern websiteübergreifend nachzuverfolgen. 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 Vorschlagsfamilie TURTLEDOVE 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 unter Best Practices zur Latenz bei Anzeigenauktionen der Protected Audience API.

Demo der Protected Audience API

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

In dieser End-to-End-Bereitstellung erfährst du, wie der Democode der Protected Audience API funktioniert und wie du die Chrome-Entwicklertools für die Fehlerbehebung verwenden kannst.

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 einem Computer testen:

Anzeigen in iFrames oder Fenced Frames rendern

Je nachdem, welche Flags festgelegt sind, können Anzeigen in einem <iframe>- oder <fencedframe>-Element 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 Flag BiddingAndScoringDebugReportingAPI ein, um Methoden zur temporären Fehlerbehebung für Verluste/Gewinne 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 gespeichert, zusammen mit den zugehörigen Metadaten, um Gebote für Anzeigen und das Rendering zu konfigurieren.
  • On-Device-Gebote von Käufern (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 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

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

Wenn Websiteinhaber ihre Berechtigungsrichtlinien für domainübergreifende iFrames aktualisieren konnten, sollen Aufrufe von domainübergreifenden iFrames künftig nicht mehr zugelassen werden.

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

Der Schlüssel/Wert-Dienstcode der Protected Audience API ist jetzt verfügbar. Das Statusupdate finden Sie in diesem Blogpost.

Für erste Tests wurde ein Bring Your Own Server-Modell 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.

Weitere Informationen zu Aktualisierungen des Zeitplans finden Sie im Blogpost zu Protected Audience API-Diensten. Vor der Umstellung werden wir die Entwickler rechtzeitig informieren, damit sie mit den 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 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 surft ein Nutzer auf der Website eines Fahrradherstellers, besucht später eine Nachrichtenwebsite und sieht eine Anzeige für ein neues Fahrrad des Herstellers.

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 Herstellers von maßgefertigten Fahrrädern (dem Werbetreibenden) und verbringt einige Zeit auf der Produktseite eines handgefertigten Stahlrads. 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 zum Verbinden von Anzeigengruppen mit Anzeigen ausgeführt.

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 Protected Audience API-Anzeigenauktion. Die Mitgliedschaft in einer Interessengruppe wird vom Browser auf dem Gerät des Nutzers gespeichert und nicht mit dem Anbieter des Browsers oder anderen Nutzern geteilt.

Anzeigen für eine Interessengruppe festlegen

ads- und adComponents-Objekte 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, in der der Browser Mitglied ist, sofern der Inhaber der Interessengruppe dazu eingeladen wird, ein Gebot abzugeben.

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. Auf der Website ist eine leere Anzeigenfläche vorhanden.

Später besucht der Nutzer eine Website, auf der Werbeflächen verkauft werden, in diesem Beispiel eine Nachrichtenwebsite. Auf der Website gibt es 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. 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 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. Bei der Auktion werden die Interessengruppen, denen der Browser angehört, sowie Daten von Käufern und Verkäufern der Schlüssel/Wert-Paare berücksichtigt.

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. 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 stellt. Der Verkäufer kann diese Informationen während runAdAuction() mit dem Attribut trustedScoringSignalsUrl zusammen mit den Schlüsseln aus den renderUrl-Attributen aller Einträge in den Feldern ads und adComponents aller Interessengruppen in der Auktion anfordern.

Ein Käufer kann mit den Attributen trustedBiddingSignalsUrl und trustedBiddingSignalsKeys des an navigator.joinAdInterestGroup() übergebenen Interessengruppenarguments Echtzeitdaten von seinem Schlüssel/Wert-Dienst anfordern.

Wenn runAdAuction() aufgerufen wird, sendet der Browser eine Anfrage an den vertrauenswürdigen Server jedes 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 jeden der Schlüssel bereitstellt.

6. Die erfolgreiche Anzeige wird ausgeliefert.

Eine Person ruft eine Nachrichtenwebsite in einem Browser auf ihrem Laptop auf. Eine Anzeige für 20% Rabatt auf ein Fahrrad wird in einem sicheren 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 planen Sie, dass der Browser über die Private Aggregation APIs Berichte zu Auktionsergebnissen für den Verkäufer und Käufer erstellen kann.

Als temporäres Berichtsmechanismus 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 einzelnes Argument verwendet: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird und die Informationen auf Ereignisebene codiert, 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 dazu finden Sie unter Berichte zu Fenced Frames-Anzeigen.

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 das erste Experiment, das in Chromium innerhalb der TURTLEDOVE-Angebotsfamilie implementiert wird.

Die Protected Audience API entspricht den allgemeinen Prinzipien von TURTLEDOVE. Manche Onlinewerbung basierte darauf, dass die Anzeige einer potenziell interessierten Person präsentiert wurde, die zuvor mit dem Werbetreibenden oder Werbenetzwerk interagiert hat. In der Vergangenheit hat der Werbetreibende damit eine bestimmte Person beim Surfen auf Websites erkannt. Dies ist ein grundlegendes Thema des Datenschutzes im heutigen Web.

Bei TURTLEDOVE geht es darum, eine neue API für diesen Anwendungsfall anzubieten und gleichzeitig einige wichtige datenschutzbezogene Fortschritte anzubieten:

  • Die Informationen zu den Inhalten, an denen die Person interessiert ist, werden nicht vom Werbetreibenden, sondern im Browser gespeichert.
  • Werbetreibende können Anzeigen auf Grundlage von Interessen schalten, aber nicht mit anderen Informationen über eine Person kombinieren, insbesondere nicht darüber, wer sie sind oder welche Seite sie besuchen.

Die Protected Audience API entstand aus TURTLEDOVE und einer Sammlung zugehöriger Änderungsvorschläge, um Entwickler, die die API verwenden würden, besser zu unterstützen:

  • In SPARROW hat Criteo das Hinzufügen eines Dienstmodells („Gatekeeper“) vorgeschlagen, 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.
  • In den Angeboten TERN von NextRoll und PARRROT von Magnite wurden die verschiedenen Rollen beschrieben, die Käufer und Verkäufer in der On-Device-Auktion einnehmen. Der Ablauf für Gebote/Bewertung von Anzeigen der Protected Audience API basiert auf dieser Arbeit.
  • Die TURTLEDOVE-Änderungen auf ergebnisbasierter und produktbezogener RTB House verbesserten das Anonymitätsmodell und die Personalisierungsfunktionen der On-Device-Auktion.
  • PARAKEET ist der Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst. Dieser basiert auf einem Proxyserver, der in einem TEE zwischen dem Browser und den Anzeigentechnologie-Anbietern ausgeführt wird, um Anzeigenanfragen zu anonymisieren und Datenschutzeigenschaften durchzusetzen. Die Protected Audience API verwendet dieses Proxying-Modell nicht. Wir passen die JavaScript APIs für PARAKEET und die Protected Audience API an, um zukünftige Arbeitsschritte zu ermöglichen und die besten Funktionen beider Vorschläge 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, kann von einem Verkäufer oder Bieter als Kontextinformationen verwendet werden. Ein Thema kann in die folgenden Attribute aufgenommen werden:

  • auctionSignals, eine Eigenschaft des Auktionskonfigurationsobjekts, das an navigator.runAdAuction() übergeben wird
  • userBiddingSignals, ein Attribut des Interessengruppen-Konfigurationsobjekts, 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 für die oberste 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. Für Chrome ist geplant, dass Nutzer die Liste der Interessengruppen, denen sie auf den von ihnen besuchten Websites hinzugefügt wurden, ansehen und verwalten können. Wie bei den Privacy Sandbox-Technologien selbst können sich auch die Nutzereinstellungen durch das Feedback 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 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 – 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

So stellen Sie Fragen und erhalten Unterstützung bei der Implementierung, der Demo oder der Dokumentation:

Bei allgemeineren Fragen zur Erfüllung Ihrer Anforderungen mit der Protected Audience API melden Sie ein Problem im API-Repository. Außerdem können Sie in der Improving Web Advertising Business Group des W3C über Anwendungsfälle der Branche sprechen.

Über das Feedbackformular der Privacy Sandbox können Sie dem Chrome-Team außerhalb von öffentlichen Foren privat Feedback geben.

Deaktivieren

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

Immer auf dem neuesten Stand bleiben