Private Aggregation API – Übersicht

Generieren Sie aggregierte Datenberichte mit Daten aus Protected Audience und websiteübergreifenden Daten aus freigegebenem Speicher.

Die Private Aggregation API wurde für die datenschutzfreundliche Zusammenfassung und Berichterstellung zu websiteübergreifenden Daten entwickelt, 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(). In Zukunft werden aber möglicherweise weitere unterstützt. Mit dem Histogrammvorgang können Sie Daten nutzerübergreifend in den von Ihnen definierten Buckets (in der API als Aggregationsschlüssel bezeichnet) aggregieren. Im Histogrammaufruf werden Werte erfasst und ein verrauschtes zusammengefasstes 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 auf einen Fehler im Drittanbieterskript gestoßen sein. 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 ungefähr aussagt, wie viele Nutzer in New York City Ihre Inhalte websiteübergreifend gesehen haben. Wenn Sie für diese Messung eine Aggregation vornehmen möchten, können Sie die geografische Dimension im Aggregationsschlüssel codieren und die Nutzer im aggregierbaren Wert zählen.

Wichtige Konzepte

Wenn Sie die Private Aggregation API mit einem Aggregationsschlüssel und einem aggregierbaren Wert aufrufen, generiert der Browser einen zusammengefasste Bericht.

Aggregierbare Berichte werden zur Erfassung und Batch-Verarbeitung an Ihren Server gesendet. Die Batch-Berichte werden später vom Aggregation Service verarbeitet und ein Zusammenfassungsbericht erstellt.

Weitere Informationen zu den wichtigsten Konzepten 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 Messen von Conversions, während die private Aggregation für websiteübergreifende Messungen in Verbindung mit APIs wie der Protected Audience API und freigegebenem Speicher entwickelt wurde. Beide APIs generieren zusammengefasste Berichte, die vom Aggregationsdienst-Backend verarbeitet werden, um zusammenfassende Berichte zu generieren.

Attribution Reporting verknüpft Daten aus einem Impressionsereignis mit einem Conversion-Ereignis, die zu unterschiedlichen Zeiten stattfinden. Bei der privaten Aggregation wird ein einzelnes, websiteübergreifendes Ereignis erfasst.

Diese API testen

Die Private Aggregation API kann lokal getestet werden. Aktivieren Sie dazu das Test-Flag für Privacy Sandbox Ads APIs unter chrome://flags/#privacy-sandbox-ads-apis.

Privacy Sandbox Ads APIs-Test aktivieren, um diese APIs zu verwenden
Privacy Sandbox Ads APIs-Test zur Verwendung dieser APIs aktivieren

Weitere Informationen zu Tests finden Sie im Artikel Tests und Teilnahme.

Demo verwenden

Die Demo der Private Aggregation API für freigegebenen Speicher finden Sie unter goo.gle/shared-storage-demo. Der Code ist auf GitHub verfügbar. In der Demo werden die clientseitigen Vorgänge implementiert und ein zusammenfassender Bericht erstellt, der an Ihren Server gesendet wird.

In Zukunft wird eine Demo der Private Aggregation API für die Protected Audience API veröffentlicht.

Anwendungsfälle

Die private Aggregation ist eine API für allgemeine Zwecke für die websiteübergreifende Messung und kann in den Worklets freigegebener Speicher und Protected Audience API verwendet werden. Der erste Schritt besteht darin, genau zu entscheiden, welche Informationen Sie sammeln möchten. Diese Datenpunkte bilden die Grundlage der Aggregationsschlüssel.

Mit gemeinsam genutztem Speicher

Freigegebener Speicher ermöglicht das Lesen und Schreiben von websiteübergreifenden Daten in einer sicheren Umgebung, um Datenlecks zu verhindern. Mit der Private Aggregation API können Sie websiteübergreifende Daten messen, die im freigegebenen Speicher gespeichert sind.

Unique Reach-Messung

Vielleicht möchten Sie messen, wie viele einzelne Nutzer ihren Content gesehen haben. Die Private Aggregation API kann eine Antwort wie etwa „Ungefähr 317 einzelne Nutzer haben den Content ID 861 gesehen“ liefern.

Sie können im freigegebenen Speicher eine Markierung setzen, um anzugeben, ob der Nutzer den Inhalt bereits gesehen hat. Beim ersten Besuch, bei dem das Flag nicht vorhanden ist, wird ein Aufruf der privaten Aggregation ausgeführt und dann das Flag gesetzt. Bei nachfolgenden Besuchen des Nutzers, einschließlich websiteübergreifender Besuche, können Sie den freigegebenen Speicher prüfen und das Senden eines Berichts an die private Aggregation überspringen, wenn das Flag gesetzt ist.

Demografische Analyse

Sie können die demografischen Merkmale der Nutzer erfassen, die Ihren Content auf verschiedenen Websites gesehen haben.

Private Aggregation kann z. B. Antworten liefern, z. B. „Etwa 317 einzelne Nutzer sind im Alter zwischen 18 und 45 Jahren und stammen aus Deutschland.“ Über freigegebenen Speicher auf demografische Daten aus Drittanbieterkontexten zugreifen Später können Sie einen Bericht mit der privaten Aggregation erstellen, indem Sie die Dimensionen „Altersgruppe“ und „Land“ im Aggregationsschlüssel codieren.

Frequenzmessung von K+

Sie können die Anzahl der Nutzer messen, die einen Inhalt oder eine Anzeige mindestens K-mal in einem bestimmten Browser für einen vorab gewählten Wert von K gesehen haben.

Private Aggregationen können Antworten wie „Ungefähr 89 Nutzer haben den Content ID 581 mindestens 3 Mal gesehen“. Ein Zähler kann im freigegebenen Speicher von verschiedenen Websites inkrementiert werden und innerhalb eines Worklets gelesen werden. Wenn die Anzahl erreicht ist, kann ein Bericht über die private Aggregation gesendet werden.

Mit der Protected Audience API

Die Protected Audience API ermöglicht das Retargeting und Anwendungsfälle für benutzerdefinierte Zielgruppen. Mit der privaten Aggregation können Sie Ereignisse von Käufer- und Verkäufer-Worklets erfassen. Sie kann unter anderem für das Messen der Verteilung von Auktionsgeboten verwendet werden.

Über ein Protected Audience API-Worklet können Sie Ihre Daten direkt mit sendHistogramReport() aggregieren und mit reportContributionForEvent() – einer speziellen Erweiterung für die Protected Audience API – Berichte basierend auf einem Trigger erstellen.

Verfügbare Funktionen

Die folgenden Funktionen sind im Objekt privateAggregation verfügbar, das in freigegebenen Speicher- 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 ein BigInt erforderlich. Für den Parameter value ist eine Ganzzahl erforderlich.

Hier ein Beispiel für den entsprechenden Aufruf im freigegebenen Speicher für die Reichweitenmessung:

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);

Im Codebeispiel oben wird immer dann die private Aggregation aufgerufen, wenn der websiteübergreifende iFrame-Inhalt geladen wird. Der iFrame-Code lädt das Worklet und ruft die Private Aggregation API auf, wobei die Content ID in einen Aggregationsschlüssel (Bucket) konvertiert wird.

contributeToHistogramOnEvent()

Nur in den Worklets der Protected Audience API gibt es einen Auslösernbasierten Mechanismus, mit dem nur dann ein Bericht gesendet wird, wenn ein bestimmtes Ereignis eintritt. Außerdem hängen Bucket und Wert mit dieser Funktion von Signalen ab, die zu diesem Zeitpunkt in der Auktion noch nicht verfügbar sind.

Bei der Methode privateAggregation.reportContributionForEvent(eventType, contribution) wird ein eventType verwendet, das das auslösende Ereignis angibt, und die contribution, die gesendet werden, wenn das Ereignis ausgelöst wird. Das auslösende Ereignis kann nach Ende der Auktion von der Auktion selbst stammen, z. B. ein Gewinn- oder Verlustereignis einer Auktion, oder aus einem abgegrenzten Frame, in dem die Anzeige gerendert wurde. Um einen Bericht zu Auktionsereignissen zu senden, können Sie die beiden reservierten Keywords reserved.win, reserved.loss und reserved.always verwenden. Wenn Sie einen Bericht senden möchten, der durch ein Ereignis aus einem Fenced Frame ausgelöst wird, müssen Sie einen benutzerdefinierten Ereignistyp definieren. Verwenden Sie zum Auslösen des Ereignisses über einen Fenced Frames Ads Reporting API die fence.reportEvent()-Methode in der Fenced Frames Ads Reporting API.

Im folgenden Beispiel wird ein Bericht zu Impressionen gesendet, wenn das Auktionsgewinnereignis ausgelöst wird. Ein Bericht zu Klicks wird gesendet, wenn ein click-Ereignis über den abgegrenzten Frame ausgelöst wird, der die Anzeige gerendert hat. Diese beiden Werte können zur Berechnung der Klickrate verwendet 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 in der Erläuterung zu erweiterten privaten Aggregationsberichten.

enableDebugMode()

Drittanbieter-Cookies sind zwar weiterhin verfügbar, aber wir werden den Debug-Modus aktivieren, um Fehler und Tests zu vereinfachen. Mit einem Debug-Bericht können Sie Ihre cookiebasierten mit Ihren privaten Aggregationsmessungen vergleichen. Außerdem lässt sich damit die API-Einbindung schnell überprüfen.

Durch das Aufrufen von privateAggregation.enableDebugMode() im Worklet wird der Debug-Modus aktiviert, in dem aggregierte Berichte die unverschlüsselte Nutzlast (Klartext) enthalten. Anschließend können Sie diese Nutzlasten mit dem lokalen Testtool von Aggregation Service verarbeiten.

Der Debug-Modus 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() automatisch fehl. Das bedeutet, dass der Debug-Modus nicht mehr verfügbar ist, wenn Drittanbietercookies nicht mehr unterstützt werden.

Sie können den Schlüssel zur Fehlerbehebung auch festlegen, indem Sie privateAggregation.enableDebugMode({ <debugKey: debugKey> }) aufrufen. Dabei kann BigInt als Schlüssel zur Fehlerbehebung verwendet werden. Mit dem Schlüssel zur Fehlerbehebung lassen sich Daten aus einer auf Cookies basierenden Analyse mit Daten aus der privaten Aggregationsmessung verknüpfen. Diese können nur einmal pro Kontext aufgerufen werden. Alle nachfolgenden Aufrufe werden ignoriert.

// 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, rechtmäßig sind, indem Sie dem Aufruf des freigegebenen Speichervorgangs eine Kontext-ID hinzufügen. Die ID wird an den gesendeten Bericht angehängt. Sie können sie später verwenden, um zu bestätigen, dass der Bericht über den Vorgang für den freigegebenen Speicher gesendet wurde.

Die Funktion ist für Tests in Chrome M114 und höher verfügbar. Die Berichtsüberprüfung für die Protected Audience API ist noch nicht für Tests verfügbar.

Weitere Informationen

Reagieren und Feedback geben

Die Private Aggregation API wird derzeit diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API testen und Feedback haben, freuen wir uns darauf, sie zu hören.