Private Aggregation API – Übersicht

Generieren Sie Berichte mit aggregierten Daten anhand von Daten aus Protected Audience und websiteübergreifender Daten aus freigegebenem Speicher.

Die Private Aggregation API wurde entwickelt, um websiteübergreifende Daten unter Einhaltung des Datenschutzes datenschutzkonform zu aggregieren und Berichte dazu zu erstellen, um wichtige Funktionen bereitzustellen, auf die sich das Web stützt.

Implementierungsstatus

Vorschlag Status
Ungültige Private Aggregation API-Berichte mit Berichtsüberprüfung für freigegebenen Speicher verhindern
Erläuterung		 In Chrome verfügbar
Verfügbarkeit des Debug-Modus für private Aggregation je nach Berechtigung für Drittanbieter
GitHub-Problem		 Verfügbar in Chrome M119
Weniger Berichtsverzögerungen
Erläuterung		 Verfügbar in Chrome M119
Unterstützung für die Private Aggregation API und den Aggregation Service für Google Cloud
Erläuterung		 Verfügbar in Chrome M121
Padding für Nutzlasten von aggregierten Berichten
Erläuterung		 Verfügbar in Chrome M119
Debug-Modus für private Aggregationen für AuktionsBerichte zu Authorized Buyers-Berichten verfügbar
Erläuterung		 Voraussichtlich in Chrome M123
Unterstützung von Filter-IDs
Erläuterung		 Erste Chrome-Einführung wird im 2. Quartal 2024 erwartet.

Was ist die Private Aggregation API?

Mit der Private Aggregation API können Entwickler aggregierte Datenberichte mit Daten aus der Protected Audience API und websiteübergreifenden Daten aus freigegebenem Speicher generieren.

Diese API bietet derzeit den Vorgang sendHistogramReport(), aber in Zukunft werden möglicherweise weitere unterstützt. Mit dem Histogrammvorgang können Sie Daten von Nutzern in jedem Bucket (in der API als Aggregationsschlüssel bezeichnet) aggregieren, den Sie definieren. In Ihrem Histogrammaufruf werden Werte akkumuliert und ein verrauschtes aggregiertes Ergebnis in Form eines Zusammenfassungsberichts zurückgegeben. Der Bericht kann beispielsweise die Anzahl der Websites enthalten, auf denen jeder Nutzer Ihre Inhalte gesehen hat, oder es ist ein Fehler in Ihrem Drittanbieterskript aufgetreten. 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 standortü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 „Shared Storage“ 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.

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 „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 einer 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 ein Bericht über die private Zusammenfassung 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 sendHistogramReport() aggregieren und Ihre Daten anhand eines Triggers mit der reportContributionForEvent(), 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.reportContributionForEvent(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, und ein Klickbericht, wenn im Fenced-Frame, in dem die Anzeige gerendert wurde, ein click-Ereignis ausgelöst wird. 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 Fehlerbehebungsmodus ist nur für Aufrufer verfügbar, die auf Cookies von Drittanbietern zugreifen dürfen. Wenn der Aufrufer keinen Zugriff auf Drittanbieter-Cookies hat, schlägt enableDebugMode() ohne Meldung fehl. Das bedeutet, dass der Debug-Modus nicht mehr verfügbar ist, wenn Drittanbieter-Cookies eingestellt werden.

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.

Die Funktion ist zum Testen in Chrome M114+ verfügbar. Die Berichtsüberprüfung für die Protected Audience API ist noch nicht zum Testen verfügbar.

Weitere Informationen

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.