Private Aggregation API – Übersicht

Aggregierte Datenberichte mit Daten aus Protected Audience und websiteübergreifenden Daten aus Shared Storage generieren

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

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). Bei Ihrem Histogrammaufruf werden Werte erfasst und ein gefiltertes aggregiertes Ergebnis in Form eines Zusammenfassungsberichts zurückgegeben. 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. Im ersten Schritt müssen Sie genau festlegen, welche Informationen Sie erheben 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 im freigegebenen Speicher ein Flag festlegen, um anzugeben, ob der Nutzer die Inhalte 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 „Altersgruppe“ und „Land“ im Zusammenfassungsschlüssel codieren.

Messung der Häufigkeitsgrad (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 ein Bericht über die private Zusammenfassung gesendet werden.

Multi-Touch-Attribution

Diese Anleitung soll auf der Entwicklerwebsite veröffentlicht werden, damit Anzeigentechnologie-Anbieter nachvollziehen können, wie MTA innerhalb von freigegebenem Speicher und privater Aggregation implementiert wird.

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 ein 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 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 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 privateAggregation.contributeToHistogramOnEvent(eventType, contribution)-Methode nimmt einen eventType an, der das auslösende Ereignis angibt, und die contribution, die gesendet werden soll, wenn das Ereignis ausgelöst wird. Das auslösende Ereignis kann von der Auktion selbst nach deren Ende stammen, z. B. ein Ereignis vom Typ „Auktion gewonnen“ oder „Auktion verloren“. Es kann sich aber auch um ein Ereignis von einem eingegrenzten Frame handeln, 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 eingegrenzten Frame auslösen möchten, verwenden Sie die Methode fence.reportEvent() der Fenced Frames Ads Reporting API.

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 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 gemeinsam genutztem Speicher können Sie die Gültigkeit der aggregierten Berichte prüfen, indem Sie dem Aufruf des gemeinsamen Speichervorgangs 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.

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.

• GitHub: Lesen Sie die Erläuterung, stellen Sie Fragen und nehmen Sie an Diskussionen teil.
• Entwicklersupport: Im Privacy Sandbox Developer Support-Repository können Sie Fragen stellen und an Diskussionen teilnehmen.
• Treten Sie der Shared Storage API-Gruppe und der Protected Audience API-Gruppe bei, um die neuesten Ankündigungen zur privaten Aggregation zu erhalten.