Generieren Sie Berichte mit aggregierten Daten anhand von Daten aus Protected Audience und websiteübergreifender Daten aus freigegebenem Speicher.
Um wichtige Funktionen bereitzustellen, auf die sich das Web stützt, Die API wurde für die Zusammenfassung und Berichterstellung für websiteübergreifende Daten in einer die datenschutzfreundlich sind.
Implementierungsstatus
Vorschlag | Status |
---|---|
Ungültige Berichte der Private Aggregation API durch Berichtsüberprüfung für freigegebenen Speicher verhindern Erläuterung |
In Chrome verfügbar |
Verfügbarkeit des Debug-Modus der privaten Aggregation hängt von den Voraussetzungen für Drittanbieter ab GitHub-Problem |
Verfügbar in Chrome M119 |
Verzögerung bei Berichten reduzieren Erklärung |
Verfügbar in Chrome M119 |
Unterstützung für die Private Aggregation API und den Aggregationsdienst für Google Cloud Erklärung |
Verfügbar in Chrome M121 |
Padding für aggregierbare Berichtsnutzlasten Erklärung |
Verfügbar in Chrome M119 |
Der Fehlerbehebungsmodus für die private Aggregation ist für die Berichte von „auktionReportBuyers“ verfügbar Erklärung |
Voraussichtlich in Chrome M123 |
ID-Unterstützung filtern Erklärung |
Voraussichtlich in Chrome M128 |
Was ist die Private Aggregation API?
Mit der Private Aggregation API können Entwickler aggregierte Datenberichte generieren mit Daten aus der Protected Audience API und websiteübergreifenden Daten aus freigegebenem Speicher.
Die Hauptfunktion dieser API ist als contributeToHistogram()
bekannt. Mit dem Histogrammvorgang aggregieren Sie Daten
für alle Nutzer in den von Ihnen definierten Buckets (in der API als Aggregationsschlüssel bezeichnet).
Ihr Histogrammaufruf sammelt Werte und gibt ein verrauschtes aggregiertes Ergebnis in
zusammenfassen. Beispielsweise kann der Bericht die Anzahl der
Websites, auf denen alle Nutzer Ihre Inhalte gesehen haben, oder auf einen Fehler in Ihrem Drittanbieter-Skript gestoßen sind. Dieser Vorgang wird im Worklet einer anderen API ausgeführt.
Wenn Sie beispielsweise zuvor demografische und geografische Daten im freigegebenen Speicher aufgezeichnet haben, können Sie mit der Private Aggregation API ein Histogramm erstellen, das aussagt, wie viele Nutzer in New York City Ihre Inhalte websiteübergreifend gesehen haben. Zum Aggregieren für diese Messung können Sie die geografische Dimension im Aggregationsschlüssel codieren und die Nutzer im aggregierten Wert zählen.
Wichtige Konzepte
Wenn Sie die Private Aggregation API mit einem Aggregationsschlüssel und einem aggregierbaren Wert aufrufen, generiert der Browser einen aggregierten Bericht.
Aggregierte Berichte werden zur Erfassung und Batchverarbeitung an Ihren Server gesendet. Die zusammengefassten Berichte werden später vom Aggregationsdienst verarbeitet und ein Zusammenfassungsbericht erstellt.
Weitere Informationen zu den Schlüsselkonzepten der Private Aggregation API finden Sie im Dokument Grundlagen der Private Aggregation API.
Unterschiede zu Attributionsberichten
Die Private Aggregation API hat viele Ähnlichkeiten mit der Attribution Reporting API. Attribution Reporting ist eine eigenständige API zum Erfassen von Conversions. Die private Aggregation hingegen wurde für websiteübergreifende Messungen in Verbindung mit APIs wie der Protected Audience API und freigegebenem Speicher entwickelt. Beide APIs generieren aggregierte Berichte, die vom Back-End des Aggregationsdiensts verwendet werden, um zusammenfassende Berichte zu generieren.
Attribution Reporting ordnet Daten von Impressions- und Conversion-Ereignissen zu, die zu unterschiedlichen Zeiten stattfinden. Mit der privaten Aggregation wird ein einzelnes websiteübergreifendes Ereignis erfasst.
Diese API testen
Wenn Sie die Private Aggregation API lokal testen möchten, aktivieren Sie alle Ad Privacy APIs unter chrome://settings/adPrivacy
.
Weitere Informationen zu Tests und zur Teilnahme
Demo verwenden
Die Demo der Private Aggregation API für freigegebenen Speicher ist unter goo.gle/shared-storage-demo verfügbar und der Code ist auf GitHub verfügbar. In der Demo werden die clientseitigen Vorgänge implementiert und ein aggregierter Bericht erstellt, der an Ihren Server gesendet wird.
Eine Demo der Private Aggregation API für die Protected Audience API wird in Zukunft veröffentlicht.
Anwendungsfälle
Die private Aggregation ist eine universelle API für die websiteübergreifende Messung. Sie kann in Shared Storage- und Protected Audience API-Worklets verwendet werden. Zunächst müssen Sie entscheiden, welche Informationen Sie sammeln möchten. Diese Datenpunkte bilden die Grundlage Ihrer Aggregationsschlüssel.
Mit gemeinsam genutztem Speicher
Mit freigegebenem Speicher können Sie websiteübergreifende Daten in einer sicheren Umgebung lesen und schreiben, um Datenlecks zu vermeiden. Mit der Private Aggregation API können Sie außerdem websiteübergreifende Daten messen, die im freigegebenen Speicher gespeichert sind.
Unique Reach-Messung
Möglicherweise möchten Sie messen, wie viele einzelne Nutzer ihre Inhalte gesehen haben. Die Private Aggregation API kann beispielsweise folgende Antworten liefern: „Etwa 317 einzelne Nutzer haben die Content ID 861 gesehen.“
Sie können in „Freigegebener Speicher“ ein Flag setzen, um anzugeben, ob der Nutzer den Inhalt bereits gesehen hat oder nicht. Beim ersten Besuch, bei dem das Flag nicht vorhanden ist, wird ein Aufruf an Private Aggregation durchgeführt und dann das Flag gesetzt. Bei nachfolgenden Besuchen des Nutzers, einschließlich websiteübergreifender Besuche, können Sie den freigegebenen Speicher überprüfen und das Senden eines Berichts an die private Aggregation überspringen, wenn das Flag gesetzt ist. Weitere Informationen zu den Methoden zur Implementierung dieser Messungen finden Sie in unserem Whitepaper zur Reichweite.
Analyse der demografischen Merkmale
Möglicherweise möchten Sie die demografischen Merkmale der Nutzer messen, die Ihren Content auf verschiedenen Websites gesehen haben.
Die private Aggregation liefert beispielsweise folgende Antwort: „Etwa 317 einzelne Nutzer sind zwischen 18 und 45 Jahre alt und stammen aus Deutschland.“ Über Shared Storage können Sie auf demografische Daten aus Drittanbieterkontexten zugreifen. Später können Sie einen Bericht mit der privaten Zusammenfassung erstellen, indem Sie die Dimensionen für Altersgruppe und Land im Zusammenfassungsschlüssel codieren.
Messung der Häufigkeit von K+
Sie können die Anzahl der Nutzer messen, die einen Inhalt oder eine Anzeige mindestens K-mal in einem bestimmten Browser gesehen haben, und zwar für den vorab ausgewählten Wert K.
Mit der privaten Zusammenfassung können Sie beispielsweise folgende Antworten erhalten: „Etwa 89 Nutzer haben die Content ID 581 mindestens dreimal gesehen.“ Ein Zähler kann im freigegebenen Speicher von verschiedenen Websites aus erhöht und innerhalb eines Worklets gelesen werden. Wenn die Anzahl K erreicht hat, kann über die private Zusammenfassung ein Bericht gesendet werden.
Mit der Protected Audience API
Die Protected Audience API ermöglicht Retargeting und benutzerdefinierte Zielgruppen. Mit der privaten Aggregation können Sie Berichte zu Ereignissen von Käufer- und Verkäufer-Worklets erstellen. Die API kann beispielsweise für das Messen der Verteilung von Auktionsgeboten verwendet werden.
Über ein Worklet der Protected Audience API können Sie Ihre Daten direkt mit contributeToHistogram()
aggregieren und Ihre Daten anhand eines Triggers mit der contributeToHistogramOnEvent()
, einer speziellen Erweiterung der Protected Audience API, melden.
Verfügbare Funktionen
Die folgenden Funktionen sind im privateAggregation
-Objekt verfügbar, das in Shared Storage- und Protected Audience API-Worklets verfügbar ist.
contributeToHistogram()
Sie können privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
aufrufen, wobei der Aggregationsschlüssel bucket
und der aggregierbare Wert value
ist. Für den Parameter bucket
ist BigInt
erforderlich. Für den Parameter value
ist eine Ganzzahl erforderlich.
Hier ist ein Beispiel dafür, wie sie zur Messung der Reichweite im freigegebenen Speicher aufgerufen werden können:
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await this.sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
Das obige Codebeispiel ruft die private Zusammenfassung immer dann auf, wenn der websiteübergreifende iFrame-Content geladen wird. Der iFrame-Code lädt das Worklet und das Worklet ruft die Private Aggregation API mit der in einen Aggregationsschlüssel (Bucket) konvertierten Content ID auf.
contributeToHistogramOnEvent()
Nur innerhalb der Protected Audience API-Worklets bieten wir einen Trigger-basierten Mechanismus, mit dem ein Bericht nur gesendet wird, wenn ein bestimmtes Ereignis eintritt. Mit dieser Funktion können außerdem die Gruppe und der Wert von Signalen abhängen, die zu diesem Zeitpunkt in der Auktion noch nicht verfügbar sind.
Die Methode privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
verwendet eine eventType
, die das auslösende Ereignis angibt, sowie die contribution
, die gesendet werden, wenn das Ereignis ausgelöst wird. Das auslösende Ereignis kann von der Auktion selbst nach dem Ende der Auktion stammen, z. B. einem Sieg oder einem Verlust, oder von einem abgezäunten Frame, in dem die Anzeige gerendert wurde.
Wenn Sie einen Bericht zu Auktionsereignissen senden möchten, können Sie die beiden reservierten Keywords reserved.win
, reserved.loss
und reserved.always
verwenden. Definieren Sie einen benutzerdefinierten Ereignistyp, um einen Bericht zu senden, der durch ein Ereignis in einem Fencing Frame ausgelöst wurde. Wenn Sie das Ereignis über einen Fenced Frame auslösen möchten, verwenden Sie die Methode fence.reportEvent()
, die in der Fenced Frames Ads Reporting API verfügbar ist.
Im folgenden Beispiel wird ein Impressionsbericht gesendet, wenn das Ereignis „Auktionsgewinn“ ausgelöst wird. Ein Klickbericht wird gesendet, wenn ein click
-Ereignis über den Fenced-Frame ausgelöst wird, in dem die Anzeige gerendert wurde. Anhand dieser beiden Werte kann die Klickrate berechnet werden.
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
Weitere Informationen finden Sie unter Erweiterte Berichte zu privaten Zusammenfassungen.
enableDebugMode()
Drittanbieter-Cookies sind zwar weiterhin verfügbar, wir stellen jedoch einen temporären Mechanismus bereit, der das Debugging und Testen erleichtert, indem wir den Debug-Modus aktivieren. Mit einem Debug-Bericht können Sie Ihre cookiebasierten Messungen mit den Messungen der privaten Aggregation vergleichen. Außerdem können Sie damit die API-Integration schnell prüfen.
Durch den Aufruf von privateAggregation.enableDebugMode()
im Worklet wird der Debug-Modus aktiviert. Aggregierbare Berichte enthalten dann die unverschlüsselte Nutzlast (Klartext). Sie können diese Nutzlasten dann mit dem lokalen Testtool des Aggregationsdienstes verarbeiten.
Der Debug-Modus ist nur für Aufrufer verfügbar, die Zugriff haben
Drittanbieter-Cookies. Wenn der Aufrufer keinen Zugriff auf Drittanbieter-Cookies hat,
enableDebugMode()
schlägt ohne Meldung fehl. Das bedeutet, wenn Drittanbieter
Cookies eingestellt werden, ist der Debug-Modus nicht mehr verfügbar.
Du kannst den Fehlerbehebungsschlüssel auch festlegen, indem du privateAggregation.enableDebugMode({ <debugKey: debugKey> })
aufrufst. Dabei kann ein BigInt
als Schlüssel für die Fehlerbehebung verwendet werden. Mit dem Schlüssel zur Fehlerbehebung können Daten aus einer cookiebasierten Messung und Daten aus der privaten Aggregation verknüpft werden.
Diese können nur einmal pro Kontext aufgerufen werden. Alle nachfolgenden Aufrufe lösen eine Ausnahme aus.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Bestätigung melden
Bei freigegebenem Speicher können Sie überprüfen, ob die aggregierten Berichte, die Sie erhalten haben, berechtigt sind, indem Sie dem Vorgangsaufruf für den freigegebenen Speicher eine Kontext-ID hinzufügen. Die ID wird an den gesendeten Bericht angehängt. Später können Sie anhand dieser ID überprüfen, ob der Bericht über den freigegebenen Speicher gesendet wurde.
Interagieren und Feedback geben
Die Private Aggregation API wird derzeit diskutiert und kann sich in Zukunft ändern. Wir würden uns freuen, wenn Sie diese API ausprobieren und uns Feedback geben.
- GitHub: Lesen Sie die Erläuterung, stellen Sie Fragen und nehmen Sie an Diskussionen teil.
- Entwicklersupport: Im Privacy Sandbox-Repository für Entwicklersupport können Sie Fragen stellen und sich an Diskussionen beteiligen.
- Treten Sie der Shared Storage API-Gruppe und der Protected Audience API-Gruppe bei, um die neuesten Ankündigungen zur privaten Aggregation zu erhalten.