Entwicklerleitfaden für die FLEDGE API

An wen richtet sich dieser Artikel?

Dieser Beitrag ist eine technische Referenz für die aktuelle Version der experimentellen Protected Audience API.

Was ist Protected Audience?

Die Protected Audience API ist eine Privacy Sandbox-Lösung, Remarketing und benutzerdefinierte Zielgruppen, die so konzipiert sind, dass sie nicht von um das Surfverhalten von Nutzern websiteübergreifend nachzuverfolgen. Die API ermöglicht On-Device-Auktionen den Browser, um relevante Anzeigen für bereits besuchte Websites auszuwählen.

Protected Audience ist der erste Test, der in Chromium im TURTLEDOVE-Angebotsfamilie.

Das folgende Diagramm bietet einen Überblick über den FLEDGE-Lebenszyklus:

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder"></ph> Darstellung der einzelnen Phasen des FLEDGE-Lebenszyklus
FLEDGE-Lebenszyklus

Wie kann ich Protected Audience ausprobieren?

Protected Audience-Demo

Eine Schritt-für-Schritt-Anleitung für die grundlegende Implementierung von Protected Audience auf Werbetreibenden- und Publisher-Websites finden Sie unter protected-audience-demo.web.app.

Demovideo wird erläutert, wie der Democode funktioniert und wie Sie die Chrome-Entwicklertools zum Debugging von Protected Audience verwenden.

An einem Protected Audience-Ursprungstest teilnehmen

Ein Ursprungstest für Relevanz und Messung der Privacy Sandbox wurde die ab Chrome Beta 101.0.4951.26 auf Computern für Protected Audience zur Verfügung stehen. Topics Attribution Reporting API

Wenn Sie teilnehmen möchten, registrieren Sie sich für ein Ursprungstesttoken.

Nachdem Sie sich für den Test registriert haben, können Sie die Protected Audience JavaScript API auf Seiten testen die ein gültiges Testtoken bereitstellen, z. B. um den Browser aufzufordern, einer oder mehreren Interessengruppen beizutreten, und anschließend eine Anzeigenauktion durchführen, um eine Anzeige auszuwählen und auszuliefern.

Die Protected Audience-Demo ist ein einfaches Beispiel für eine End-to-End-Bereitstellung von Protected Audience.

Geben Sie für jede Seite, auf der Sie den Code der Protected Audience API ausführen möchten, ein Testtoken an:

  • Als Meta-Tag im <head>-Abschnitt:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • Als HTTP-Header:

    Origin-Trial: TOKEN_GOES_HERE

  • Wenn Sie ein Token programmatisch bereitstellen, geschieht Folgendes:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Einen iFrame, in dem Protected Audience-Code ausgeführt wird, z. B. navigator.joinAdInterestGroup() von einem Interessengruppen-Inhaber aufgerufen werden, muss ein Token bereitstellen, das mit seinem Ursprung übereinstimmt.

Details des vorgeschlagenen Ursprungstests für die erste Protected Audience API enthält weitere Informationen zu den Zielen des ersten Tests und erläutert, welche Funktionen unterstützt werden.

Diese API testen

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

  • Durch Aktivieren aller APIs zum Datenschutz bei Werbung unter chrome://settings/adPrivacy
  • Durch Festlegen von Flags über die Befehlszeile

Anzeigen in iFrames oder Fenced Frames rendern

Anzeigen können in folgenden Formaten gerendert werden: <iframe> oder <fencedframe> je nachdem, welche 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

Fügen Sie das Flag BiddingAndScoringDebugReportingAPI ein, um die Methoden zur temporären Fehlerbehebung für Verluste/Gewinne zu aktivieren.

Chromium mit Flags ausführen erklärt, wie Sie beim Ausführen von Chrome und anderen Chromium-basierten Browsern über den Befehl Zeile. Die vollständige Liste der Protected Audience-Flags finden Sie hier: Chromium-Codesuche

Welche Funktionen werden in der neuesten Version von Chrome unterstützt?

Protected Audience wird hinter Funktions-Flags in Chromium testen, um die folgenden Funktionen des Protected Audience-Angebots zu testen:

  • Interessengruppen: werden vom Browser gespeichert, zusammen mit den zugehörigen Metadaten, um Anzeigengebote zu konfigurieren. und Rendering.
  • On-Device-Gebote von Käufern (DSP oder Werbetreibender): basierend auf gespeicherten Interessengruppen und Signalen vom Verkäufer.
  • Anzeigenauswahl auf dem Gerät durch den Verkäufer (SSP oder Publisher): basierend auf Auktionsgeboten und von Käufern.
  • Anzeigen-Rendering in einer vorübergehend lockeren Version von Fenced Frames: mit Netzwerkzugriff und -Logging für das Anzeigen-Rendering zugelassen ist.

Weitere Informationen finden Sie in der erklärenden API. zu Funktionsunterstützung und Einschränkungen.

Berechtigungen für Interessengruppen

In der aktuellen Implementierung von Protected Audience ist es standardmäßig erlaubt, joinAdInterestGroup() von auch von domainübergreifenden iFrames aus. Wenn Websiteinhaber in Zukunft Zeit hatten, zur Anpassung der domainübergreifenden Richtlinien für iFrame-Berechtigungen sollen Aufrufe von domainübergreifenden iFrames nutzen, wie in der Erklärung beschrieben.

Dienst für Schlüssel/Wert-Paare

Im Rahmen einer Protected Audience-Anzeigenauktion kann der Browser auf eine Schlüssel/Wert-Paar-Dienst die einfache Schlüssel/Wert-Paare zurückgibt, um Informationen für einen Anzeigenkäufer bereitzustellen, z. B. verbleibende Kampagnenbudget. Die Vorgaben für das Protected Audience-Angebot dass dieser Server „keine Protokollierung auf Ereignisebene durchführt und keine weiteren Nebeneffekte hat. Anfragen“.

Der Dienstcode für Protected Audience-Schlüssel/Wert-Paare ist jetzt in einem GitHub-Repository für die Privacy Sandbox verfügbar. Dieser Dienst kann von Chrome- und Android-Entwicklern verwendet werden. Das Statusupdate finden Sie in diesem Blogpost. Weitere Informationen zum Protected Audience-Schlüssel/Wert-Dienst finden Sie in der Erklärung zur API und der Erklärung zum Vertrauensmodell.

Für erste Tests wird das Modell Bring Your Own Server (Bring Your Own Server) verwendet. Langfristig müssen AdTech-Unternehmen die Open-Source-Dienste für Protected Audience-Schlüssel/Wert-Paare nutzen, die in vertrauenswürdigen Ausführungsumgebungen ausgeführt werden, um Echtzeitdaten abzurufen.

Um sicherzustellen, dass das System über genügend Zeit für Tests verfügt, gehen wir davon aus, dass die Nutzung der Open-Source-Schlüssel/Wert-Dienste oder TEEs erst irgendwann nach der Einstellung von Drittanbieter-Cookies erforderlich ist. Vor der Umstellung werden wir die Entwickler rechtzeitig darüber informieren, dass sie mit den Tests und der Einführung beginnen können.

Funktionsunterstützung erkennen

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 kann ich Protected Audience deaktivieren?

Sie können den Zugriff auf die Protected Audience API entweder als Websiteinhaber oder als einzelner Nutzer blockieren.

Wie können Websites den Zugriff steuern?

Für Protected Audience müssen Websites schließlich eine Berechtigungsrichtlinie festlegen. damit die Protected Audience-Funktionen verfügbar sind. Dies trägt dazu bei, dass willkürliche Dritte die API nicht ohne das Attribut Wissen. Um jedoch die Tests während des ersten Ursprungstests zu erleichtern, Diese Anforderung wird standardmäßig erlassen. Websites, die Protected Audience-Funktionen während des Testzeitraums explizit deaktivieren möchten, können die entsprechende Berechtigungsrichtlinie, um den Zugriff zu blockieren.

Es gibt zwei Berechtigungsrichtlinien für Protected Audience, die unabhängig voneinander festgelegt werden können:

  • join-ad-interest-group aktiviert bzw. deaktiviert Funktionen zum Hinzufügen eines Browsers zu Interessengruppen.
  • run-ad-auction aktiviert bzw. deaktiviert Funktionen zur Durchführung einer On-Device-Auktion

Der Zugriff auf Protected Audience APIs kann in eigenen Kontexten vollständig deaktiviert werden. Geben Sie dazu Folgendes an: Berechtigungsrichtlinie in einem HTTP-Antwortheader:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Sie können die Nutzung der APIs in einem iFrame deaktivieren, indem Sie das folgende allow-Attribut einem iFrame-Element:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

Weitere Informationen finden Sie im Abschnitt Vorgeschlagene Berechtigungsrichtlinie für den Test der ersten Protected Audience-Quelle.

Nutzerwiderspruch

Nutzer können den Zugriff auf die Protected Audience API und andere Privacy Sandbox-Funktionen blockieren, indem sie eine der folgende Mechanismen:

  • Deaktivieren Sie die Privacy Sandbox-Tests in den Chrome-Einstellungen: Einstellungen > Sicherheit und Datenschutz > Privacy Sandbox: Sie können auch unter chrome://settings/adPrivacy darauf zugreifen.
  • Deaktivieren Sie Cookies von Drittanbietern in den Chrome-Einstellungen: Einstellungen > Sicherheit und Datenschutz.
  • Wählen Sie unter Cookies und andere Websitedaten die Option „Drittanbieter-Cookies blockieren“ aus. oder „Alle Cookies blockieren“ von chrome://settings/cookies.
  • Verwenden Sie den Inkognitomodus.

In der Erläuterung zu Protected Audience finden Sie weitere Details zu den API-Designelementen und erfahren, wie die API dazu dient, Datenschutzziele zu erreichen.

Fehler in Protected Audience-Worklets beheben

Ab Chrome Canary 98.0.4718.0 ist es möglich, Protected Audience-Worklets in den Chrome-Entwicklertools zu debuggen.

Der erste Schritt besteht darin, Haltepunkte über eine neue Kategorie im Bereich Ereignis-Listener-Haltepunkte festzulegen. im Bereich Quellen.

Screenshot von Entwicklertools in Chrome Canary; im Bereich „Quellen“ ist der Bereich „Event Listener Breakpoints“ markiert. Der Beginn der Gebotsphase des Bieters ist unter dem Auktions-Worklet ausgewählt.

Wenn ein Haltepunkt ausgelöst wird, wird die Ausführung vor der ersten Anweisung auf der obersten Ebene der Worklet-Skript. Sie können reguläre Haltepunkte oder Schrittbefehle verwenden, um zu den Geboten, zur Bewertung oder zum Bericht zu gelangen. die Funktion selbst.

Aktive Worklet-Skripts werden ebenfalls im Thread-Bereich angezeigt.

Screenshot von DevTools in Chrome Canary. Im Bereich „Quellen“ ist der Bereich „Threads“ markiert, in dem die aktuellen Worklet-Skript, das pausiert wurde.

Da einige Worklets parallel ausgeführt werden können, können mehrere Threads in den „pausierten“ dort angeben. können Sie mithilfe der Threadliste zwischen Threads wechseln und sie fortsetzen oder genauer untersuchen, angemessen sein.

Protected Audience-Ereignisse beobachten

Im Bereich „Anwendung“ in den Chrome-Entwicklertools können Sie sich die Protected Audience-Interessengruppe und -auktion ansehen. Ereignisse.

Wenn Sie die Demo-Shopping-Website für Protected Audience aufrufen In einem Browser mit aktivierter Protected Audience API werden in den Entwicklertools Informationen zum join-Ereignis angezeigt.

Die Anwendungsbereich der Entwicklertools in Chrome Canary mit Informationen zu einer Protected Audience-Interessengruppe teilnehmen.

Wenn Sie jetzt die Publisher-Website der Protected Audience-Demo aufrufen, In einem Browser mit aktivierter Protected Audience API werden in den Entwicklertools Informationen zu den Ereignissen bid und win angezeigt.

<ph type="x-smartling-placeholder">
</ph> Die Anwendungsbereich der Entwicklertools in Chrome Canary mit Informationen zum Protected Audience-Auktionsgebot und gewinnen.

Wie funktioniert die Protected Audience API?

In diesem Beispiel surft eine nutzende Person auf der Website eines Fahrradherstellers und besucht später eine Nachrichtenwebsite. und sieht eine Anzeige für ein neues Fahrrad des Fahrradherstellers.

1. Ein Nutzer besucht die Website eines Werbetreibenden.

Abbildung, die zeigt Eine Person, die in einem Browser auf ihrem Laptop die Website eines Fahrradherstellers aufruft

Angenommen, ein Nutzer besucht die Website eines Fahrradherstellers (der Werbetreibende in dieses Beispiel) und verbringt Zeit auf der Produktseite für ein handgefertigtes Stahlrad. So erhalten Sie die Fahrradhersteller mit einer Remarketing-Option.

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

Abbildung einer Person, die sich eine Website in einem Browser auf ihrem Laptop ansieht JavaScript Code joinAdInterestGroup() wird im Browser ausgeführt.

Erklärungsbereich:Interessengruppen für Browsereinträge

Die Demand-Side-Plattform (DSP) des Werbetreibenden oder der Werbetreibende navigator.joinAdInterestGroup() aufgerufen und den Browser aufgefordert wird, der Gruppe Liste der Gruppen, in denen der Browser Mitglied ist. In diesem Beispiel heißt die Gruppe custom-bikes. Der Inhaber ist dsp.example. Der Inhaber der Interessengruppe (in diesem Fall die DSP) ist Käufer in der in Schritt 4 beschriebenen Anzeigenauktion Die Mitgliedschaft in einer Interessengruppe wird vom Browser auf dem Gerät des Nutzers gespeichert und nicht mit dem Nutzer geteilt. Browseranbieter oder irgendjemand anderem.

joinAdInterestGroup() benötigt die Berechtigung von:

  • Die besuchte Website
  • Inhaber der Interessengruppe

Beispiel: malicious.example darf nicht aufrufen, joinAdInterestGroup() mit dsp.example als Inhaber ohne Erlaubnis von dsp.example

Berechtigung der besuchten Website

Gleicher Ursprung: Standardmäßig wird die Berechtigung für joinAdInterestGroup()-Aufrufe von denselben Ursprung haben wie die besuchte Website, d.h. von demselben Ursprung wie der Frame der obersten Ebene des aktuellen Seite angezeigt. Websites dürfen den Header für die Berechtigungen von Protected Audience verwenden. join-ad-interest-group-Anweisung zum Deaktivieren von joinAdInterestGroup()-Aufrufen.

Cross origin: joinAdInterestGroup() wird von Ursprüngen aus aufgerufen, die sich vom aktuellen Ursprung unterscheiden. kann nur erfolgreich sein, wenn für die besuchte Website eine Berechtigungsrichtlinie festgelegt ist, die Aufrufe an joinAdInterestGroup() aus ursprungsübergreifenden iFrames.

Erlaubnis des Inhabers der Interessengruppe

Die Inhaberberechtigung für eine Interessengruppe wird implizit durch den Aufruf von joinAdInterestGroup() erteilt. aus einem iFrame mit demselben Ursprung entfernt wie der des Interessengruppen-Inhabers. Beispiel: dsp.example iFrame kann joinAdInterestGroup() für Interessengruppen von dsp.example aufrufen.

Laut Vorschlag kann joinAdInterestGroup() auf einer Seite oder in einem iFrame in der Domain des Inhabers ausgeführt werden. kann an andere Domains delegiert werden, die über eine Liste unter einer .well-known-URL bereitgestellt werden.

navigator.joinAdInterestGroup() verwenden

Beispiel für die Verwendung der API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Das an die Funktion übergebene interestGroup-Objekt darf nicht größer als 50 KiB sein. Andernfalls schlägt fehl. Der zweite Parameter gibt die Dauer der Interessengruppe an, begrenzt auf 30 Tage. Aufeinanderfolgende Aufrufe überschreiben zuvor gespeicherte Werte.

Eigenschaften für Interessengruppen

Attribut Erforderlich Beispiel Rolle
owner Erforderlich 'https://dsp.example' Der Ursprung des Interessengruppeninhabers.
name Erforderlich 'custom-bikes' Name der Interessengruppe.
biddingLogicUrl** Optional* 'https://dsp.example/bid/custom-bikes/bid.js' URL für das Bidding-JavaScript, das im Worklet ausgeführt wird.
biddingWasmHelperUrl** Optional* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL für WebAssembly-Code, gesteuert von biddingLogicUrl.
dailyUpdateUrl** Optional 'https://dsp.example/bid/custom-bikes/update' URL, die JSON zurückgibt, um Interessengruppenattribute zu aktualisieren. Weitere Informationen finden Sie unter Interessengruppe aktualisieren.
trustedBiddingSignalsUrl** Optional 'https://dsp.example/trusted/bidding-signals' Basis-URL für Anfragen mit Schlüssel/Wert-Paaren an den vertrauenswürdigen Server des Bieters.
trustedBiddingSignalsKeys Optional ['key1', 'key2' ...] Schlüssel für Anfragen an einen vertrauenswürdigen Server mit Schlüssel/Wert-Paaren.
userBiddingSignals Optional {...} Zusätzliche Metadaten, die der Inhaber bei der Gebotsabgabe verwenden kann.
ads Optional* [bikeAd1, bikeAd2, bikeAd3] Anzeigen, die für diese Interessengruppe gerendert werden könnten.
adComponents Optional [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Komponenten für Anzeigen, die aus mehreren Teilen bestehen

* Alle Properties sind optional, mit Ausnahme von owner und name. biddingLogicUrl und ads Properties sind optional, für die Teilnahme an einer Auktion jedoch erforderlich. Es kann Anwendungsfälle geben, Eine Interessengruppe ohne diese Eigenschaften wird erstellt. Ein Inhaber einer Interessengruppe könnte beispielsweise Sie möchten einen Browser einer Interessengruppe für eine Kampagne hinzufügen, die noch nicht läuft, oder anderweitig verwendet wird oder ihr Werbebudget vorübergehend aufgebraucht ist.

** Die URLs biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl und trustedBiddingSignalsUrl müssen denselben Ursprung haben wie der Inhaber. Bei den URLs ads und adComponents besteht keine solche Einschränkung.

Interessengruppenattribute aktualisieren

dailyUpdateUrl gibt einen Webserver an, der im JSON-Format die Eigenschaften von Interessengruppen zurückgibt. dem an navigator.joinAdInterestGroup() übergebenen Interessengruppenobjekt entspricht. Dieses stellt einen Mechanismus bereit, mit dem der Gruppeneigentümer die Attribute der Gruppe Interessengruppe. Bei der aktuellen Implementierung können folgende Attribute geändert werden:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Felder, die nicht in der JSON-Datei angegeben sind, werden nicht überschrieben. Nur Felder, die im JSON-Format angegeben sind, werden abgerufen. aktualisiert werden, während beim Aufrufen von navigator.joinAdInterestGroup() alle vorhandenen Interessengruppen überschrieben werden.

Updates erfolgen bestmöglich und können unter den folgenden Bedingungen fehlschlagen:

  • Zeitüberschreitung bei Netzwerkanfrage (derzeit 30 Sekunden).
  • Anderer Netzwerkfehler.
  • JSON-Parsing fehlgeschlagen.

Aktualisierungen können auch abgebrochen werden, wenn zu viel zusammenhängende Zeit damit verbracht wurde. Dies ist jedoch gilt keine Ratenbegrenzung für abgebrochene (verbleibende) Updates. Aktualisierungen sind begrenzt auf maximal ein Mal pro Tag ein. Updates, die aufgrund von Netzwerkfehlern fehlschlagen, werden nach einer Stunde wiederholt. Updates, die aufgrund der Unterbrechung der Internetverbindung fehlschlagen, werden sofort nach Wiederherstellung der Verbindung wiederholt.

Manuelle Updates

Aktualisierungen von Interessengruppen, die dem Ursprung des aktuellen Frames gehören, können manuell ausgelöst werden über navigator.updateAdInterestGroups() Die Ratenbegrenzung verhindert, dass zu häufig Updates durchgeführt werden: Wiederholte Aufrufe von navigator.updateAdInterestGroups() führen bis zum Erreichen der Ratenbegrenzung nichts (derzeit ein Tag) ist verstrichen. Die Ratenbegrenzung wird zurückgesetzt, wenn navigator.joinAdInterestGroup() wird noch einmal für dieselbe Interessengruppe owner und name aufgerufen.

Automatische Updates

Alle für eine Auktion geladenen Interessengruppen werden nach Abschluss einer Auktion automatisch aktualisiert. unterliegen denselben Ratenbegrenzungen wie manuelle Aktualisierungen. Für jeden Inhaber mit mindestens einer Interessengruppe an einer Auktion teilnehmen, ist das so, als ob navigator.updateAdInterestGroups() von einer iFrame, dessen Ursprung mit diesem Inhaber übereinstimmt.

Anzeigen für eine Interessengruppe festlegen

Die Objekte ads und adComponents enthalten eine URL für ein Anzeigen-Creative und optional eine beliebige Angabe. 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?

Das Skript unter biddingLogicUrl, das von einem Interessengruppeninhaber bereitgestellt wird, muss einen generateBid() enthalten . Wenn ein Anzeigenflächen-Verkäufer navigator.runAdAuction() anruft, wird die generatedBid() wird für jede Interessengruppe, der der Browser angehört, einmal aufgerufen, der Gruppeneigentümer eingeladen wurde, ein Gebot abzugeben. Mit anderen Worten: generateBid() wird für jeden Kandidaten einmal aufgerufen. Anzeige. Der Verkäufer stellt eine decisionLogicUrl-Eigenschaft für den übergebenen Auktionskonfigurationsparameter bereit. an navigator.runAdAuction(). Der Code unter dieser URL muss eine scoreAd()-Funktion enthalten, die für jeden Bieter in der Auktion durchgeführt, um jedes der zurückgegebenen Gebote von generateBid() zu bewerten.

Das von einem Käufer der Werbeflächen bereitgestellte Skript unter biddingLogicUrl muss eine generateBid()-Funktion enthalten. Diese Funktion wird für jede mögliche Anzeige einmal aufgerufen. runAdAuction() überprüft jede Anzeige einzeln samt Gebot und Metadaten und weist der Anzeige dann ein numerische Erwünschtheit.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() verwendet die folgenden Argumente:

  • interestGroup
    Das Objekt, das vom Anzeigenkäufer an joinAdInterestGroup() übergeben wurde (Die Interessengruppe kann über dailyUpdateUrl aktualisiert werden.)

  • auctionSignals
    Eine Property des Arguments auction config, das an navigator.runAdAuction() vom Verkäufer der Werbefläche. So erhalten Sie Informationen zum Seitenkontext (z. B. die Anzeigengröße und die Publisher-ID), die Art der Auktion (Erst- oder Zweitpreis) und andere Metadaten.

  • perBuyerSignals
    Wie bei auctionSignals ist eine Eigenschaft der Auktionskonfiguration. -Argument, das vom Verkäufer an navigator.runAdAuction() übergeben wurde. So können Sie kontextbezogene Signale vom Server des Käufers über die Seite, wenn der Verkäufer eine SSP ist, einen Echtzeitgebotsaufruf an die Käuferserver durchführt und die Antwort zurücksendet, oder wenn der Publisher kontaktiert den Server des Käufers direkt. In diesem Fall kann der Käufer eine kryptografische Signatur dieser Signale ingenerateBid() als Schutz vor Manipulationen.

  • trustedBiddingSignals
    Objekt, dessen Schlüssel die trustedBiddingSignalsKeys für den und deren Werte in der trustedBiddingSignals-Anfrage zurückgegeben werden.

  • browserSignals
    Ein vom Browser erstelltes Objekt, das Informationen zur Seite enthalten kann Kontext (z. B. hostname der aktuellen Seite, den der Verkäufer andernfalls fälschen könnte) und Daten für die Interessengruppe selbst, z. B. eine Aufzeichnung darüber, wann die Gruppe zuvor eine Auktion gewonnen hat, um On-Device-Frequency Capping).

Das browserSignals-Objekt hat die folgenden Eigenschaften:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Zur Berechnung eines bid-Werts kann Code in generateBid() die Attribute der Funktion Parameter. Beispiel:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() gibt ein Objekt mit vier Eigenschaften zurück:

  • ad
    Beliebige Metadaten zur Anzeige, z. B. Informationen, die der Verkäufer voraussichtlich über dieses Gebot erhält, oder Anzeigen-Creative. Der Verkäufer](/privacy-sandbox/resources/glossary#ssp) verwendet diese Informationen bei seiner Auktion und Entscheidung Anzeigen-Creative. Der Verkäufer verwendet diese Informationen bei der Auktion und bei seiner Entscheidung. Logik.

  • bid
    Ein numerisches Gebot, das an der Auktion teilnimmt. Der Verkäufer muss in der Lage sein, einen Vergleich anzustellen. von verschiedenen Käufern abgegeben werden. Die Gebote müssen daher in einer vom Verkäufer gewählten Einheit liegen (z. B. "USD pro .000“). Wenn das Gebot null oder negativ ist, nimmt diese Interessengruppe nicht am überhaupt nicht berücksichtigt. Mit diesem Mechanismus kann der Käufer beliebige Regeln für Werbetreibende einrichten, die angeben, wo können ihre Anzeigen erscheinen oder auch nicht.

  • render
    Eine URL oder eine Liste von URLs, die zum Rendern des Creatives verwendet wird, wenn dieses Gebot die Auktion gewinnt. (Siehe Anzeigen bestehend aus mehreren Teilen in der Erläuterung der API.) Der Wert muss mit dem renderUrl eines der für die Interessengruppe definierte Anzeigen.

  • adComponents
    Eine optionale Liste mit bis zu 20 Komponenten für Anzeigen, die aus mehreren Teilen bestehen, Aus der Eigenschaft adComponents des Interessengruppenarguments entnommen an navigator.joinAdInterestGroup() übergeben.

Einen Browser bitten, eine Interessengruppe zu verlassen

Der Inhaber der Interessengruppe kann beantragen, dass ein Browser aus einer Interessengruppe entfernt wird. In anderen wird der Browser aufgefordert, die Interessengruppe aus der Liste der Mitglieder zu entfernen.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Wenn ein Nutzer zu der Website zurückkehrt, auf der vom Browser eine Interessengruppe hinzugefügt werden soll, hat der Inhaber der Interessengruppe kann die Funktion navigator.leaveAdInterestGroup() aufrufen, damit der Browser die Interessengruppe entfernt. Code für eine Anzeige kann diese Funktion auch für ihre Interessengruppe aufrufen.

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

Abbildung einer Person, die eine Nachrichtenwebsite in einem Browser auf ihrem Laptop besucht. 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 hat Anzeigeninventar, das mithilfe von Echtzeitgebote.

4. Eine Anzeigenauktion wird im Browser ausgeführt.

Abbildung einer Person, die auf ihrem Laptop in einem Browser eine Nachrichtenwebsite aufruft Eine Anzeige der Protected Audience API erfolgt.

Erklärungsbereich:Verkäufer führen Auktionen auf dem Gerät durch

Die Anzeigenauktion wird wahrscheinlich von der SSP des Publishers durchgeführt. den Herausgeber selbst. Der Zweck der Auktion besteht darin, die am besten geeignete Anzeige für eine einzelne Anzeige auszuwählen. verfügbaren Anzeigenfläche auf der aktuellen Seite. Bei der Auktion werden die Interessengruppen berücksichtigt, „browser“ gehört, zusammen mit den Daten von Anzeigenflächenkäufern und Verkäufern der Schlüssel/Wert-Dienste.

Der Verkäufer der Werbefläche sendet eine Anfrage an den Browser des Nutzers, um eine Anzeigenauktion zu starten, indem er Folgendes aufruft: navigator.runAdAuction()

Beispiel:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() gibt ein Versprechen zurück, das in eine URN (urn:uuid:<something>) aufgelöst wird, die den das Ergebnis der Anzeigenauktion. Dieser Code kann nur vom Browser decodiert werden, wenn er an einen Fenced Frame übergeben wird. Rendering: Die Publisher-Seite kann die erfolgreiche Anzeige nicht prüfen.

Das Skript decisionLogicUrl berücksichtigt jede einzelne Anzeige mit dem zugehörigen Gebot und Metadaten und weist ihm dann einen numerischen Erwünschtheitswert zu.

auctionConfig Unterkünfte

Attribut Erforderlich Beispiel Rolle
seller Erforderlich 'https://ssp.example' Herkunft des Verkäufers.
decisionLogicUrl Erforderlich 'https://ssp.example/auction-decision-logic.js' URL für JavaScript des Auktions-Worklets.
trustedScoringSignalsUrl Optional 'https://ssp.example/scoring-signals' URL des vertrauenswürdigen Servers des Verkäufers.
interestGroupBuyers* Erforderlich ['https://dsp.example', 'https://buyer2.example', ...] Herkunft aller Interessengruppeninhaber, die in der Auktion ein Gebot abgeben möchten
auctionSignals Optional {...} Verkäuferinformationen zum Seitenkontext, zur Art der Auktion usw.
sellerSignals Optional {...} Informationen, die auf den Publisher-Einstellungen, einer kontextbezogenen Anzeigenanfrage usw. basieren
sellerTimeout Optional 100 Maximale Laufzeit (ms) des scoreAd()-Skripts des Verkäufers.
perBuyerSignals Optional {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Kontextsignale zur Seite für jeden einzelnen Käufer vom jeweiligen Server
perBuyerTimeouts Optional 50 Maximale Laufzeit (ms) der generateBid()-Skripts eines bestimmten Käufers
componentAuctions Optional [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Zusätzliche Konfigurationen für Komponentenauktionen

* Der Verkäufer kann interestGroupBuyers: '*' angeben, damit alle Interessengruppen Gebote abgeben dürfen. Die Anzeigen werden dann basierend auf anderen Kriterien als der Einbeziehung des Interessengruppeninhabers angenommen oder abgelehnt. Verkäufer haben beispielsweise die Möglichkeit, ihre Creatives auf die Einhaltung der Richtlinien zu überprüfen.

** additionalBids wird in der aktuellen Implementierung von Protected Audience nicht unterstützt. Auktion lesen Teilnehmer im Erläuterung zu Protected Audience.

Wie werden Anzeigen ausgewählt?

Der Code unter decisionLogicUrl (eine Eigenschaft des Auktionskonfigurationsobjekts, das an runAdAuction()) muss eine scoreAd()-Funktion enthalten. Er wird für jede Anzeige einmal ausgeführt. um dessen Zweckmäßigkeit zu ermitteln.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() verwendet die folgenden Argumente:

  • adMetadata
    Beliebige Metadaten, die vom Käufer bereitgestellt werden.
  • bid
    Ein numerischer Gebotswert.
  • auctionConfig
    Das an navigator.runAdAuction() übergebene Auktionskonfigurationsobjekt.
  • trustedScoringSignals
    Werte, die zum Zeitpunkt der Auktion vom vertrauenswürdigen Server des Verkäufers abgerufen werden der Meinung des Verkäufers zur Anzeige.
  • browserSignals
    Ein vom Browser erstelltes Objekt, einschließlich Informationen, die der Browser enthält was das Auktionsskript des Verkäufers überprüfen sollte:
{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

Vor Beginn einer Auktion sucht der Verkäufer die am besten geeignete kontextbezogene Anzeige für die verfügbare Anzeigenfläche. Teil von Die scoreAd()-Logik besteht darin, jede Anzeige abzulehnen, die den kontextbezogenen Gewinner nicht schlagen kann.

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

Abbildung einer Person, die auf ihrem Laptop in einem Browser eine Nachrichtenwebsite aufruft Eine Anzeige bei einer Auktion mithilfe der Protected Audience API, wobei ein Teilnehmer Daten vom Schlüssel/Wert-Dienst erhält.

Erklärungsbereich:Echtzeitdaten aus dem Protected Audience-Schlüssel/Wert-Dienst abrufen.

Während einer Anzeigenauktion kann der Verkäufer für die Werbefläche Echtzeitdaten zu bestimmten Creatives abrufen, indem er: Sie stellen eine Anfrage an einen Schlüssel/Wert-Dienst mit dem Attribut trustedScoringSignalsUrl von Argument Auktionskonfiguration wird zusammen mit den Schlüsseln an navigator.runAdAuction() übergeben. aus den renderUrl-Eigenschaften aller Einträge in den Feldern ads und adComponents aller Interessengruppen in der Auktion auswählen.

Ebenso kann ein Käufer für Werbeflächen Echtzeitdaten vom Schlüssel/Wert-Dienst über die Methode Eigenschaften trustedBiddingSignalsUrl und trustedBiddingSignalsKeys des Interessengruppenarguments an navigator.joinAdInterestGroup() übergeben.

Wenn runAdAuction() aufgerufen wird, sendet der Browser eine Anfrage an den vertrauenswürdigen Server jedes Käufers. Die 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.

Abbildung einer Person, die auf ihrem Laptop in einem Browser eine Nachrichtenwebsite aufruft Eine Anzeige für ein Fahrrad (20% Rabatt) ist zu sehen – mit einem Schloss oben, das darauf hinweist, dass die Anzeige in einem Fenced Frame.

Erläuterung:Browser rendern die erfolgreiche Anzeige

Wie bereits beschrieben, wird das von runAdAuction() zurückgegebene Promise in eine URN aufgelöst. Dieser wird zum Rendern an einen Fencing Frame übergeben. Die Website zeigt dann Anzeige, die den Zuschlag erhält.

7. Das Auktionsergebnis wird im Bericht

Erläuterung:Berichte auf Ereignisebene (derzeit)

Ergebnis der Verkäuferberichte

Erklärungsbereich: Verkäuferberichte zum Rendering

Über den unter decisionLogicUrl bereitgestellten JavaScript-Code des Verkäufers, der auch scoreAd() bereitgestellt hat, kann eine reportResult()-Funktion enthalten, um das Auktionsergebnis zu melden.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Folgende Argumente werden an diese Funktion übergeben:

  • auctionConfig
    Das an navigator.runAdAuction() übergebene Auktionskonfigurationsobjekt.

  • browserSignals
    Ein Objekt, das vom Browser erstellt wird und Informationen zur Auktion liefert. Beispiel:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Der Rückgabewert dieser Funktion wird als sellerSignals-Argument für das erfolgreiche Gebot des Bieters verwendet, das den Zuschlag erhält. reportWin().

Ergebnis der Berichte des erfolgreichen Bieters

Erklärungsbereich: Käuferberichte zu Rendering und Anzeigenereignissen

Der JavaScript-Code des erfolgreichen Bieters, der auch generateBid() bereitgestellt hat, kann Folgendes enthalten: reportWin(), um das Auktionsergebnis zu melden.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Folgende Argumente werden an diese Funktion übergeben:

  • auctionSignals und perBuyerSignals
    Dieselben Werte, die für den erfolgreichen Bieter an generateBid() übergeben werden
  • sellerSignals
    Der Rückgabewert von reportResult(), der dem Verkäufer eine Informationen an den Käufer weiterzugeben.

  • browserSignals
    Ein Objekt, das vom Browser erstellt wird und Informationen zur Auktion liefert. Beispiel:

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Implementierung von Berichten zu vorübergehenden Verlusten und Gewinnen

In Chrome stehen vorübergehend zwei Methoden für Auktionsberichte zur Verfügung:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Diese Methoden verwenden jeweils ein einzelnes Argument: eine URL, die nach Abschluss der Auktion abgerufen wird. Sie können mehrmals aufgerufen werden, sowohl in scoreAd() als auch in generateBid(), mit unterschiedlichen URL-Argumenten.

Chrome sendet nur dann Berichte zu Verlusten und Gewinnen zur Fehlerbehebung, wenn eine Auktion abgeschlossen ist. Wenn eine Auktion abgebrochen (z. B. aufgrund einer neuen Navigation), werden keine Berichte erstellt.

Diese Methoden sind in Chrome standardmäßig verfügbar. Wenn Sie die Methoden testen möchten, müssen Sie unter chrome://settings/adPrivacy alle APIs zum Datenschutz bei Werbung aktivieren. Wenn Sie Chrome mit Befehlszeilen-Flags zum Aktivieren von Protected Audience verwenden, müssen Sie die Methoden explizit durch Einfügen des Flags BiddingAndScoringDebugReportingAPI aktivieren. Wenn die nicht aktiviert ist, sind die Methoden zwar verfügbar, führen aber nichts aus.

8. Ein Anzeigenklick wird erfasst

Abbildung, die zeigt Eine Person, die auf einer Nachrichtenwebsite auf eine Anzeige für ein Fahrrad in einem umzäunten Rahmen klickt, sowie einen Bericht an Verkäufer und Käufer.

Es wird ein Klick auf eine Anzeige erfasst, die in einem abgegrenzten Frame gerendert wird. Weitere Informationen zur Funktionsweise Siehe Berichte zu Fenced Frames-Anzeigen.


Im folgenden Diagramm werden die einzelnen Phasen einer Protected Audience-Anzeigenauktion dargestellt:

Abbildung mit einem Überblick über die einzelnen Phasen einer Protected Audience-Anzeigenauktion


Was ist der Unterschied zwischen Protected Audience und TURTLEDOVE?

Protected Audience ist das erste Experiment, das in Chromium innerhalb der TURTLEDOVE-Angebotsfamilie implementiert wird.

Protected Audience folgt den allgemeinen Prinzipien von TURTLEDOVE. Einige Online-Werbung basiert darauf, dass eine Anzeige einer potenziell interessierten Person gezeigt wurde, die zuvor mit dem Werbetreibenden oder dem Werbenetzwerk interagiert hat. In der Vergangenheit hat der Werbetreibende damit eine bestimmte Person beim Surfen auf Websites erkannt. Dies ist ein grundlegendes Anliegen im Hinblick auf den Datenschutz im Internet.

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

  • Die Informationen darüber, was ein Werbetreibender denkt, werden im Browser gespeichert. Person interessiert sind.
  • Werbetreibende können Anzeigen auf Grundlage von Interessen schalten, diese Interessen jedoch nicht mit anderen Informationen über eine Person – insbesondere darüber, wer diese Person ist oder welche Seite sie besucht.

Protected Audience entstand aus TURTLEDOVE und einer Sammlung zugehöriger Änderungsvorschläge für Entwickler, die die API verwenden würden:

  • Gehen Sie in SPARROW so vor: Criteo hat die Hinzufügung eines Dienstmodell („Gatekeeper“), das in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt wird. Protected Audience umfasst eine eingeschränktere Nutzung von TEEs für die Echtzeitdatensuche und aggregierte Berichterstellung.
  • TERN von NextRoll und Magnite PAARROT wurden die unterschiedlichen Rollen beschrieben, die Käufer und Verkäufer in der On-Device-Auktion einnehmen. Der Ablauf für Gebote und die Bewertung von Anzeigen in Protected Audience basiert auf dieser Arbeit.
  • Die RTB House-Funktionen Ergebnisbasierte und TURTLEDOVE auf Produktebene verbesserten das Anonymitätsmodell und die Personalisierungsfunktionen der On-Device-Auktion
  • PARAKEET ist Der Vorschlag von Microsoft für einen TURTLEDOVE-ähnlichen Anzeigendienst, der auf einem Proxyserver basiert, der in einem TEE ausgeführt wird zwischen dem Browser und den AdTech-Anbietern, um Anzeigenanfragen zu anonymisieren und den Datenschutz durchzusetzen Eigenschaften. Protected Audience hat dieses Proxying-Modell nicht verwendet. Die JavaScript APIs werden jetzt damit PARAKEET und Protected Audience sich aufeinander abstimmen können, um die beste Kombination Funktionen beider Vorschläge.

Protected Audience verhindert noch nicht, dass das Werbenetzwerk einer Website lernt, welche Anzeigen einem Nutzer präsentiert werden. Wir erwarten um die API zu modifizieren, sodass sie im Laufe der Zeit immer privater wird.

Welche Browserkonfiguration ist verfügbar?

Nutzer können ihre Teilnahme an Privacy Sandbox-Tests in Chrome anpassen, indem sie die Funktion aktivieren oder deaktivieren die Einstellung auf oberster Ebene in chrome://settings/adPrivacy. Bei den ersten Tests können Sie Protected Audience mit dieser allgemeinen Privacy Sandbox-Einstellung deaktivieren. Zulassung für Chrome geplant Nutzer können die Liste der Interessengruppen, denen sie im Web hinzugefügt wurden, abrufen und verwalten. Websites, die sie besucht haben. Wie bei der Privacy Sandbox selbst können auch die Nutzereinstellungen und sich mit dem Feedback von Nutzenden, Aufsichtsbehörden und anderen Beteiligten weiterentwickeln.

Die in Chrome verfügbaren Einstellungen werden laufend aktualisiert, während wir das Angebot für Protected Audience bearbeiten, basierend auf zu 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 und die Mitgliedschaft wenn Nutzer ihre Websitedaten löschen.



Interagieren und Feedback geben

Support kontaktieren

Wenn Sie eine Frage zu Ihrer Implementierung, zur Demo oder zur Dokumentation stellen möchten:

Bei Programmfehlern und Problemen bei der Implementierung der Protected Audience API in Chrome: * Vorhandene Probleme ansehen die für die API gemeldet wurden. * Melden Sie ein neues Problem unter crbug.com/new.

Immer auf dem neuesten Stand bleiben

Weitere Informationen

Foto von Ray Hennessy auf Unsplash.