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 das Web angewiesen ist, wurde die Private Aggregation API entwickelt, mit der websiteübergreifende Daten datenschutzfreundlich zusammengefasst und in Berichte aufgenommen werden können.

Implementierungsstatus

Was ist die Private Aggregation API?

Mit der Private Aggregation API können Entwickler zusammengefasste Datenberichte mit Daten aus der Protected Audience API und websiteübergreifenden Daten aus dem Shared Storage generieren.

Die Hauptfunktion dieser API wird als contributeToHistogram() bezeichnet. Mit dem Histogramm-Vorgang können Sie Daten für alle Nutzer in jedem Bucket (in der API als Aggregationsschlüssel bezeichnet) zusammenfassen, den Sie definieren. Bei Ihrem Histogrammaufruf werden Werte erfasst und ein gefiltertes aggregiertes Ergebnis in Form eines Zusammenfassungsberichts zurückgegeben. So sehen Sie beispielsweise die Anzahl der Websites, auf denen die Inhalte der einzelnen Nutzer ausgeliefert wurden, oder einen Fehler im Script eines Drittanbieters. Dieser Vorgang wird im Worklet einer anderen API ausgeführt.

Wenn Sie beispielsweise zuvor demografische und geografische Daten in Shared Storage erfasst haben, können Sie mit der Private Aggregation API ein Histogramm erstellen, das Ihnen ungefähr angibt, wie viele Nutzer in New York City Ihre Websiteinhalte gesehen haben. Wenn Sie diese Messwerte zusammenfassen möchten, können Sie die geografische Dimension in den Aggregationsschlüssel einfügen 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 aggregierbaren Bericht.

Aggregierbare Berichte werden zur Erhebung und Batchverarbeitung an Ihren Server gesendet. Die Berichte im Batch werden später vom Aggregationsdienst verarbeitet und ein Zusammenfassungsbericht generiert.

Im Dokument Grundlagen der Private Aggregation API finden Sie weitere Informationen zu den wichtigsten Konzepten der Private Aggregation API.

Unterschiede zu Attributionsberichten

Die Private Aggregation API weist viele Ähnlichkeiten mit der Attribution Reporting API auf. Die Attribution Reporting API ist eine eigenständige API zur Messung von Conversions. Private Aggregation ist für websiteübergreifende Messungen in Verbindung mit APIs wie der Protected Audience API und Shared Storage konzipiert. Beide APIs generieren aggregierbare Berichte, die vom Aggregationsdienst-Backend verwendet werden, um Zusammenfassungsberichte zu erstellen.

In Attributionsberichten werden Daten aus einem Impressions- und einem Conversion-Ereignis verknüpft, die zu unterschiedlichen Zeiten auftreten. Bei 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 APIs für den Datenschutz bei Werbung unter chrome://settings/adPrivacy.

Weitere Informationen zu Tests finden Sie unter Tests durchführen und daran teilnehmen.

Demo verwenden

Die Demo der Private Aggregation API für Shared Storage 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 aggregierbarer 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

Private Aggregation ist eine allgemeine API für websiteübergreifende Messungen. 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 für Ihre Aggregationsschlüssel.

Mit freigegebenem Speicher

Mit der Shared Storage API können Sie websiteübergreifende Daten in einer sicheren Umgebung lesen und schreiben, um Datenlecks zu verhindern. Mit der Private Aggregation API können Sie websiteübergreifende Daten messen, die im Shared Storage gespeichert sind.

Unique Reach-Messung

Sie möchten wissen, wie viele einzelne Nutzer die Inhalte gesehen haben. Die Private Aggregation API kann beispielsweise eine Antwort wie „Ungefähr 317 einmalige Nutzer haben sich den Content 861 angesehen“ liefern.

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 die private Aggregation aufgerufen und das Flag wird festgelegt. Bei nachfolgenden Besuchen des Nutzers, einschließlich seitenübergreifender Besuche, können Sie den gemeinsamen Speicher prüfen und das Senden eines Berichts an die private Aggregation überspringen, wenn das Flag gesetzt ist. Weitere Informationen zu Methoden zur Implementierung dieser Messungen finden Sie in unserem Whitepaper zur Reichweite.

Demografische Messung

Vielleicht möchten Sie die demografischen Merkmale der Nutzer messen, die Ihre Inhalte auf verschiedenen Websites gesehen haben.

Die private Aggregation kann eine Antwort liefern, z. B. „Ungefähr 317 Nutzer sind zwischen 18 und 45 Jahre alt und kommen aus Deutschland.“ Verwenden Sie den freigegebenen Speicher, um auf demografische Daten aus dem Kontext eines Drittanbieters zuzugreifen. Später können Sie einen Bericht mit privater Aggregation generieren, indem Sie die Dimensionen „Altersgruppe“ und „Land“ im Aggregationsschlüssel codieren.

Messung der Häufigkeit von mehr als K Impressionen

Sie möchten beispielsweise die Anzahl der Nutzer messen, die einen bestimmten Inhalt oder eine bestimmte Anzeige in einem bestimmten Browser mindestens K-mal gesehen haben, wobei K ein vordefinierter Wert ist.

Die private Aggregation kann beispielsweise eine Antwort wie „Ungefähr 89 Nutzer haben sich die Content-ID 581 mindestens dreimal angesehen“ liefern. Ein Zähler kann im freigegebenen Speicher von verschiedenen Websites erhöht und in einem Worklet gelesen werden. Sobald die Anzahl K erreicht ist, kann ein Bericht mithilfe der privaten Aggregation eingereicht werden.

Multi-Touch-Attribution

Die Marketing-Attribution ist eine Methode, mit der Werbetreibende den Beitrag von Marketingtaktiken und nachfolgenden Anzeigeninteraktionen zu Verkäufen oder Conversions ermitteln.

Mit der Protected Audience API

Mit der Protected Audience API können Sie Remarketing und benutzerdefinierte Zielgruppen verwenden. Mit Private Aggregation können Sie Ereignisse aus Käufer- und Verkäufer-Worklets erfassen. Die API kann für Aufgaben wie die Messung der Verteilung von Auktionsgeboten verwendet werden.

In einem Protected Audience API-Worklet können Sie Ihre Daten direkt mit contributeToHistogram() zusammenfassen und mit contributeToHistogramOnEvent(), einer speziellen Erweiterung für die Protected Audience API, Berichte basierend auf einem Trigger erstellen.

Verfügbare Funktionen

Die folgenden Funktionen sind im privateAggregation-Objekt verfügbar, das in Shared Storage- und Protected Audience API-Worklets verwendet wird.

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 es im freigegebenen Speicher für die Reichweitenmessung aufgerufen werden kann:

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

    // Don't 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);

Im vorherigen Codebeispiel wird die private Aggregation aufgerufen, sobald der websiteübergreifende iframe-Inhalt geladen wird. Der Iframe-Code lädt das Worklet und das Worklet ruft die Private Aggregation API mit der Inhalts-ID auf, die in einen Aggregationsschlüssel (Bucket) umgewandelt wurde.

contributeToHistogramOnEvent()

Nur in Protected Audience API-Worklets bieten wir einen triggerbasierten Mechanismus, um einen Bericht nur dann zu senden, wenn ein bestimmtes Ereignis eintritt. Mit dieser Funktion können der Bucket und der Wert auch 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 für Auktionsereignisse senden möchten, können Sie zwei reservierte Keywords verwenden: reserved.win, reserved.loss und reserved.always. Wenn Sie einen Bericht einreichen möchten, der durch ein Ereignis aus einem eingegrenzten Frame ausgelöst wird, müssen Sie einen benutzerdefinierten Ereignistyp definieren. 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 Bericht zu Impressionen gesendet, wenn das Ereignis „auction_win“ ausgelöst wird, und ein Bericht zu Klicks, wenn ein click-Ereignis vom eingezäunten Frame ausgelöst wird, in dem die Anzeige gerendert wurde. Anhand dieser beiden Werte lässt sich die Klickrate berechnen.

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 im Hilfeartikel Erweiterte Berichte zur privaten Aggregation.

enableDebugMode()

Drittanbieter-Cookies sind zwar weiterhin verfügbar, aber wir stellen einen vorübergehenden Mechanismus bereit, der die Fehlerbehebung und Tests durch Aktivieren des Debug-Modus erleichtert. Mit einem Debug-Bericht können Sie Ihre cookiebasierten Messungen mit Ihren Messungen mit privater Aggregation vergleichen und Ihre API-Integration schnell überprüfen.

Wenn Sie privateAggregation.enableDebugMode() im Worklet aufrufen, wird der Debug-Modus aktiviert, wodurch aggregierbare Berichte die unverschlüsselte (in Klartext) Nutzlast enthalten. Sie können diese Nutzlasten dann mit dem lokalen Testtool des Aggregationsdiensts verarbeiten.

Der Debug-Modus ist nur für Aufrufer verfügbar, die auf Drittanbieter-Cookies zugreifen dürfen. Wenn der Aufrufer keinen Zugriff auf Drittanbieter-Cookies hat, schlägt enableDebugMode() stillschweigend fehl.

Sie können den Debug-Schlüssel auch durch Aufrufen von privateAggregation.enableDebugMode({ <debugKey: debugKey> }) festlegen, wobei BigInt als Debug-Schlüssel verwendet werden kann. Mit dem Debug-Schlüssel können Daten aus einer cookiebasierten Messung und Daten aus einer Messung mit privater Aggregation verknüpft werden.

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

Überprüfung von Meldungen

Mit der Private Aggregation API können Sie websiteübergreifend messen und gleichzeitig den Datenschutz für Nutzer schützen. Böswillige Akteure können jedoch versuchen, die Genauigkeit dieser Messungen zu manipulieren. Sie können dies verhindern, indem Sie die Echtheit von Berichten mithilfe einer Kontext-ID überprüfen.

Wenn Sie eine Kontext-ID festlegen, können Sie dafür sorgen, dass die Daten korrekt sind, wenn sie zu den endgültigen zusammengefassten Ergebnissen beitragen. Dazu gehört Folgendes:

• Verhinderung von unzulässigen oder unechten Berichten: Sorgen Sie dafür, dass Berichte über legitime und authentische API-Aufrufe generiert werden, um die Fälschung von Berichten für böswillige Akteure zu erschweren.
• Wiedergabe von Berichten verhindern:Alle Versuche, alte Berichte wiederzuverwenden, werden erkannt und abgelehnt. So wird sichergestellt, dass jeder Bericht nur einmal zu den zusammengefassten Ergebnissen beiträgt.

Shared Storage

Wenn Sie Shared Storage zum Ausführen eines Vorgangs verwenden, mit dem ein aggregierbarer Bericht gesendet werden kann, können Sie außerhalb des Worklets eine nicht vorhersehbare ID festlegen.

Diese ID ist in den Bericht eingebettet, der aus dem Worklet erstellt wurde. Sie können sie beim Aufrufen der Methoden run() oder selectURL() für freigegebenen Speicher im Optionsobjekt unter dem Schlüssel privateAggregationConfig angeben.

Beispiel:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Nachdem Sie diese ID festgelegt haben, können Sie damit prüfen, ob der Bericht von Ihrem Shared Storage-Vorgang gesendet wurde. Um Datenlecks zu verhindern, wird pro Vorgang im gemeinsamen Speicher genau ein Bericht gesendet, unabhängig von der Anzahl der contributeToHistogram()-Aufrufe, auch wenn keine Beiträge gemacht werden.

Die Private Aggregation API sendet Berichte mit aggregierten Daten mit einer zufälligen Verzögerung von bis zu einer Stunde. Wenn Sie jedoch eine Kontext-ID zum Bestätigen eines Berichts festlegen, wird diese Verzögerung verringert. In diesem Fall gibt es eine feste, kürzere Verzögerung von 5 Sekunden nach Beginn des Vorgangs für den freigegebenen Speicher.

Beispiel für einen Workflow (wie im Diagramm oben dargestellt):

1. Der Vorgang für freigegebenen Speicher wird mit einer Konfiguration für die private Aggregation ausgeführt, in der eine Kontext-ID angegeben wird. Daraufhin wird ein aggregierbarer Bericht generiert.
2. Die Kontext-ID ist in den generierten Bericht eingebettet, der an Ihren Server gesendet wird.
3. Auf Ihrem Server werden die generierten aggregierbaren Berichte erfasst.
4. Prozesse auf Ihrem Server prüfen die Kontext-ID in jedem aggregierbaren Bericht auf Gültigkeit, bevor die Berichte in einem Batch zusammengefasst und an Ihren Aggregationsdienst gesendet werden.

Kontext-ID bestätigen

Eingehende Berichte auf Ihrem Collector-Server können auf unterschiedliche Weise überprüft werden, bevor sie an den Aggregationsdienst gesendet werden. Berichte mit ungültigen Kontext-IDs können abgelehnt werden, wenn die Kontext-ID:

• Unbekannt:Wenn ein Bericht mit einer Kontext-ID eingeht, die nicht von Ihrem System erstellt wurde, können Sie ihn verwerfen. So wird verhindert, dass unbekannte oder böswillige Akteure Daten in Ihre Aggregationspipeline einschleusen.
• Duplikat:Wenn Sie zwei oder mehr Berichte mit derselben Kontext-ID erhalten, müssen Sie auswählen, welchen Bericht Sie verwerfen möchten.
• Von der Spamerkennung gemeldet:
  • Wenn Sie bei der Verarbeitung eines Berichts verdächtige Aktivitäten eines Nutzers feststellen, z. B. eine plötzliche Änderung der Aktivitäten eines Nutzers, können Sie ihn verwerfen.
  • Sie können Berichte zusammen mit ihren Kontext-IDs und allen relevanten Signalen speichern (z. B. User-Agent, Verweisquelle usw.). Wenn Sie später das Nutzerverhalten analysieren und neue Spam-Indikatoren identifizieren, können Sie gespeicherte Berichte anhand der zugehörigen Kontext-IDs und -Signale noch einmal auswerten. So können Sie Meldungen von Nutzern mit verdächtigen Aktivitäten ablehnen, auch wenn sie nicht ursprünglich gemeldet wurden.

Feedback geben und erhalten

Die Private Aggregation API befindet sich in der Entwicklungsphase und kann sich in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback haben, würden wir uns sehr darüber freuen.

• GitHub: Lesen Sie die Erläuterung, stellen Sie Fragen und nehmen Sie an der Diskussion 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.