Zielgruppendaten definieren

Zielgruppe durch Erstellen einer Interessengruppe mithilfe der Protected Audience API definieren Im Entwicklerleitfaden finden Sie Informationen zum gesamten Lebenszyklus der Protected Audience API. In der Erläuterung der Protected Audience API finden Sie detaillierte Vorschläge dazu, wie Interessengruppen in Browsern aufgezeichnet werden.

Sie sind kein Entwickler? Weitere Informationen finden Sie in der Übersicht über die Protected Audience API.

Interessengruppen der Protected Audience API

Eine Protected Audience API-Interessengruppe repräsentiert eine Gruppe von Personen mit gemeinsamen Interessen, die einer Remarketing-Liste entspricht. Jede Protected Audience API-Interessengruppe hat einen Inhaber.

Inhaber von Interessengruppen agieren als Käufer in der Protected Audience API-Anzeigenauktion. Die Mitgliedschaft in einer Interessengruppe wird vom Browser auf dem Gerät des Nutzers gespeichert und weder an den Browseranbieter noch an Dritte weitergegeben.

API-Funktionen

joinAdInterestGroup()

Die Demand-Side-Plattform (DSP) des Werbetreibenden oder der Werbetreibende selbst ruft navigator.joinAdInterestGroup() auf, um den Browser aufzufordern, eine Interessengruppe zur Mitgliederliste des Browsers hinzuzufügen.

Der Ursprung des Aufrufkontexts für joinAdInterestGroup() muss mit dem Ursprung des Interessengruppeninhabers übereinstimmen. Daher muss joinAdInterestGroup() über einen iFrame (z. B. von einer DSP) aufgerufen werden, es sei denn, der Ursprung des Inhabers der Interessengruppe stimmt mit dem Ursprung des aktuellen Dokuments überein (z. B. eine Website mit eigenen Interessengruppen).

joinAdInterestGroup() benötigt eine Berechtigung von:

• Die besuchte Website
• Inhaber der Interessengruppe

Das bedeutet, dass malicious.example joinAdInterestGroup() für eine Interessengruppe, die zu dsp.example.com gehört, nicht aufrufen kann, ohne dass dsp.example.com die Berechtigung erteilt hat.

Berechtigung von der besuchten Website

Berechtigungen können vom selben Ursprung oder ursprungsübergreifend gewährt werden. Standardmäßig wird die Berechtigung für joinAdInterestGroup()-Aufrufe erteilt, die vom selben Ursprung wie die besuchte Website stammen, d. h. vom selben Ursprung wie der Frame auf oberster Ebene der aktuellen Seite.

Anwendungsbeispiel

Hier ist ein Beispiel dafür, wie man eine Interessengruppe definieren und den Browser bitten könnte, der Gruppe beizutreten.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  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 der Aufruf fehl. Der zweite Parameter gibt die Dauer der Interessengruppe an, begrenzt auf 30 Tage. Aufeinanderfolgende Aufrufe überschreiben zuvor gespeicherte Werte.

Wichtiger Hinweis:Alle URLs, die als Parameter für Protected Audience API-Methoden verwendet werden, müssen eine sichere Quelle haben: Alle Ressourcen müssen über HTTPS-URLs bereitgestellt werden. Unter HTTPS für die lokale Entwicklung verwenden wird beschrieben, wie Sie die Protected Audience API lokal ausführen. Außerdem erfordern biddingLogicUrl, decisionLogicUrl und trustedBiddingSignals einen X-Allow-FLEDGE: true-HTTP-Antwortheader.

Erforderliche Properties

Die einzigen erforderlichen Properties für Interessengruppen sind owner und name:

Property	Beispiel	Rolle
owner	https://dsp.example	Ursprung des Inhabers der Interessengruppe
name	custom-bikes	Name der Interessengruppe.

Optionale Attribute

Die restlichen Eigenschaften sind optional:

biddingLogicUrl^{1, 2}

Beispiel: https://dsp.example/bid/custom-bikes/bid.js

Rolle: URL für Gebots-JavaScript-Ausführung in Worklet.

biddingWasmHelperUrl^{1, 2}

Beispiel: https://dsp.example/bid/custom-bikes/bid.wasm

Rolle: URL für WebAssembly-Code, der von biddingLogicUrl generiert wurde.

updateUrl²

Beispiel: https://dsp.example/bid/custom-bikes/update

Rolle: URL, die JSON zum Aktualisieren von Interessengruppenattributen zurückgibt Weitere Informationen finden Sie unter Zielgruppendaten und Anzeigen aktualisieren.

trustedBiddingSignalsUrl²

Beispiel: https://dsp.example/trusted/bidding-signals

Rolle: Basis-URL für Schlüssel/Wert-Anfragen an den vertrauenswürdigen Schlüssel/Wert-Dienst des Bieters.

trustedBiddingSignalsKeys

Beispiel: ['key1', 'key2' ...]

Rolle: Schlüssel für Anfragen an den vertrauenswürdigen Schlüssel/Wert-Dienst für Schlüssel/Wert-Paare.

userBiddingSignals

Beispiel: {...}

Rolle: Zusätzliche Metadaten, die der Inhaber beim Bieten verwenden kann

ads¹

Beispiel: [bikeAd1, bikeAd2, bikeAd3]

Rolle: Anzeigen, die für diese Interessengruppe gerendert werden können.

adComponents

Beispiel: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]

Rolle: Komponenten für aus mehreren Teilen bestehende Anzeigen

¹ Die Properties biddingLogicUrl und ads sind optional, aber für die Teilnahme an einer Auktion erforderlich. Es kann Anwendungsfälle für die Erstellung einer Interessengruppe ohne diese Properties geben. Beispielsweise kann ein Inhaber einer Interessengruppe einen Browser zu einer Interessengruppe für eine noch nicht laufende Kampagne oder für eine andere zukünftige Verwendung hinzufügen oder das Werbebudget ist vorübergehend aufgebraucht.

² In der aktuellen Implementierung der Protected Audience API müssen biddingLogicUrl, biddingWasmHelperUrl, updateUrl und trustedBiddingSignalsUrl denselben Ursprung wie der Inhaber haben. Dies stellt keine langfristige Einschränkung dar und für die URLs ads und adComponents gibt es keine solche Einschränkung.

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
}

leaveAdInterestGroup()

Der Inhaber einer Interessengruppe kann über einen Browser beantragen, dass er aus einer Interessengruppe entfernt wird. Die Interessengruppe wird aus der Mitgliederliste des Browsers entfernt.

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

Wenn ein Nutzer zu der Website zurückkehrt, auf der der Browser um das Hinzufügen einer Interessengruppe gebeten wurde, kann der Inhaber der Interessengruppe die Funktion navigator.leaveAdInterestGroup() aufrufen, um den Browser aufzufordern, die Interessengruppe zu entfernen.

Mit dem Code für eine Anzeige kann diese Funktion auch für die zugehörige Interessengruppe aufgerufen werden.

Häufig gestellte Fragen

Wie viele Interessengruppen pro Gruppeninhaber sind für einen einzelnen Nutzer maximal zulässig?

In Chrome sind bis zu 1.000 Interessengruppen pro Inhaber und bis zu 1.000 Interessengruppeninhaber zulässig. Diese Grenzwerte sind als Leitplanken gedacht und dürfen im normalen Betrieb nicht erreicht werden.

Wie kann ich auf einer Interessengruppe basierende Anzeigen maximieren, die die K-anon-Grenzwerte erfüllen?

Der öffentliche Erklärende weist darauf hin, dass eine Interessengruppe mehrere mögliche Anzeigen enthalten kann. Daher hat die Gruppe die Möglichkeit, ein neues Gebot für eine andere ihrer Anzeigen abzugeben, damit sie als „Fallback-Anzeige“ eingesetzt wird, wenn die am häufigsten gewählte Anzeige unter dem Grenzwert liegt. Das bedeutet, dass eine kleine, spezialisierte Anzeige, die noch unter dem k-Anonymitätsschwellenwert liegt, trotzdem an Auktionen teilnehmen kann. Für die Interessengruppe der Anzeige kann so lange auf eine allgemeinere Anzeige zurückgegriffen werden, bis die spezialisiertere Anzeige eine ausreichend große Zielgruppe hat.

Aus taktischer Perspektive könnten Sie Folgendes in Betracht ziehen:

• Damit eine neue Anzeige ausgeliefert wird, können Sie einfach Gebote dafür abgeben, sofern sie ausgeliefert werden sollen. Sie müssen nichts weiter tun.
• Sie können eine Fallback-Anzeige verwenden, wenn neue Anzeigen nicht k-anon sind. Es besteht das Risiko, dass die Fallback-Anzeige selbst nicht korrekt funktioniert. Daher bietet es sich an, ganz einfach Gebote mit der Fallback-Anzeige abzugeben. Das können Sie beispielsweise bei einem Prozentsatz der Zeit tun, wenn dies ein gutes Maß ist, um sicherzustellen, dass das Fallback über dem Grenzwert bleibt.

In letzter Zeit wurde darüber diskutiert, wie etwas noch funktionieren könnte. Wenn Sie also einen Anwendungsfall haben, bei dem dieser Mechanismus ein Problem darstellen würde, nehmen Sie an der öffentlichen Diskussion darüber teil, wie die API verbessert werden könnte.

Alle Protected Audience API-Referenzen

API-Referenzleitfäden sind verfügbar:

• Entwicklerleitfaden für die Protected Audience API
• Käuferleitfaden für Protected Audience zu Interessengruppen und Gebotserstellung.
• Leitfaden für Anzeigenverkäufer zu Protected Audience-Anzeigenauktionen
• Leitfaden zur Berichterstellung für Auktionsergebnisse
• Best Practices für die Latenz bei der Anzeigenauktion von Protected Audience
• Fehlerbehebung bei Protected Audience

In der Erläuterung der Protected Audience API finden Sie auch Details zur Funktionsunterstützung und zu den Einschränkungen.