Berichts-IDs

Informationen zur Funktionsweise von Reporting-IDs in einer Protected Audience-Auktion

Übersicht

Berichts-IDs sind Kennzeichnungen, die einer Anzeige zugeordnet sind und zum Generieren eines Gebots, zum Bewerten eines Gebots und für Berichte verwendet werden können. Die Berichts-IDs werden vom Käufer in der Konfiguration der Interessengruppe angegeben und sind unter verschiedenen Bedingungen, die in diesem Leitfaden beschrieben werden, in generateBid(), scoreAd(), reportResult() und reportWin() verfügbar.

Mit Reporting-IDs können Sie eine Kennung für eine Anzeige melden und Anwendungsfälle wie Deals ermöglichen.

Es gibt drei Berichts-IDs von zwei Typen:

• Nicht auswählbare Berichts-IDs
  • buyerReportingId (ein String)
  • buyerAndSellerReportingId (ein String)
• Auswählbare Berichts-IDs
  • selectableBuyerAndSellerReportingIds (ein Array von Strings)

Die Berichts-IDs verhalten sich unterschiedlich, je nachdem, ob auswählbare Berichts-IDs verwendet werden. Wenn nur nicht auswählbare Berichts-IDs verwendet werden, sind diese IDs nur in den Berichtsfunktionen verfügbar. Wenn auswählbare IDs für die Berichterstellung zusammen mit nicht auswählbaren IDs für die Berichterstellung verwendet werden, sind alle definierten IDs auch in generateBid() und scoreAd() verfügbar.

Nicht auswählbare Berichts-IDs

buyerReportingId und buyerAndSellerReportingId sind nicht auswählbare Berichts-IDs, die in der Konfiguration der Interessengruppe definiert sind und in den Berichtsfunktionen für Käufer und Verkäufer verfügbar sind. Die Berichtsfunktionen für Käufer und Verkäufer werden nur für die Gewinneranzeige ausgeführt und erhalten die für diese Anzeige definierten Berichts-IDs.

Wenn die Funktion für Käuferberichte ohne auswählbare Berichts-IDs verwendet wird, empfängt sie je nach Überschreibungsverhalten buyerReportingId oder buyerAndSellerReportingId und die Funktion für Verkäuferberichte empfängt buyerAndSellerReportingId. Wenn weder buyerReportingId noch buyerAndSellerReportingId in der Konfiguration der Interessengruppe definiert sind, erhält die Funktion reportWin() den Namen der Interessengruppe (interestGroupName) des Gewinnergebots.

Nicht auswählbare IDs sind in generateBid() und scoreAd() nicht verfügbar, wenn sie nicht in Verbindung mit auswählbaren Berichts-IDs verwendet werden.

Berichts-IDs in Interessengruppen

Die Berichts-IDs werden vom Käufer für jede Anzeige in einer Interessengruppe definiert:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

Berichterstellung für Verkäufer

Während der Berichterstellungsphase für Verkäufer ist der Wert buyerAndSellerReportingId für reportResult() verfügbar:

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Bevor die ID in reportResult() verfügbar wird, wird sie anhand des Inhabers der Interessengruppe, der Gebotsskript-URL, der Render-URL und der Anzeigengröße auf k-Anonymität geprüft. Die Anzeigengröße wird bis mindestens zum ersten Quartal 2025 nicht berücksichtigt. Wenn die Daten nicht k-anonym sind, wird die reportResult()-Funktion trotzdem ausgeführt, der Wert der Reporting-ID ist jedoch nicht in der Funktion verfügbar.

Berichterstellung für Käufer

Während der Berichterstellungsphase für Käufer der Auktion ist eine Berichts-ID für reportWin() verfügbar. Wenn in der Interessengruppe mehr als eine Berichts-ID definiert ist, wird eine Überschreibungsregel angewendet, bei der buyerAndSellerReportingId buyerReportingId überschreibt:

• Wenn sowohl buyerAndSellerReportingId als auch buyerReportingId definiert sind, wird buyerReportingId durch buyerAndSellerReportingId überschrieben und buyerAndSellerReportingId ist in reportWin() verfügbar.
• Wenn nur buyerReportingId definiert ist, ist buyerReportingId verfügbar.
• Wenn weder buyerAndSellerReportingId noch buyerReportingId definiert sind, ist interestGroupName verfügbar.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Die Berichts-ID, die in reportWin() verfügbar wird, wird mit dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Render-URL und der Anzeigengröße auf k-Anonymität geprüft. Die Anzeigengröße wird mindestens bis zum 1. Quartal 2025 nicht in diese Prüfung einbezogen. Wenn die k-Anonymitätsprüfung fehlschlägt, wird reportWin() trotzdem ausgeführt, der Wert der Reporting-ID ist in der Funktion jedoch nicht verfügbar.

Nur buyerReportingId ist definiert

Wenn in der Konfiguration der Interessengruppe nur buyerReportingId definiert ist:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

buyerReportingId ist dann in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

Bevor buyerReportingId für reportWin() verfügbar wird, wird die k-Anonymität mit dem Inhaber der Interessengruppe, der Gebotsscript-URL, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird mindestens bis zum 1. Quartal 2025 nicht in diese Prüfung einbezogen.

Nur „buyerAndSellerReportingId“ ist definiert

Wenn in der Konfiguration der Interessengruppe nur buyerAndSellerReportingId definiert ist:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

buyerAndSellerReportingId ist dann in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Bevor buyerAndSellerReportingId für reportWin() verfügbar wird, wird die k-Anonymität mit dem Inhaber der Interessengruppe, der Gebotsscript-URL, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird mindestens bis zum 1. Quartal 2025 nicht in diese Prüfung einbezogen.

Sowohl buyerAndSellerReportingId als auch buyerReportingId sind definiert.

Wenn sowohl buyerAndSellerReportingId als auch buyerReportingId in der Konfiguration der Interessengruppe definiert sind:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Aufgrund des Überschreibungsverhaltens ist dann nur noch buyerAndSellerReportingId in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Bevor buyerAndSellerReportingId für reportWin() verfügbar wird, wird die k-Anonymität mit dem Inhaber der Interessengruppe, der Gebotsscript-URL, der Render-URL und der Anzeigengröße geprüft. Die Anzeigengröße wird mindestens bis zum 1. Quartal 2025 nicht in diese Prüfung einbezogen.

Weder buyerAndSellerReportingId noch buyerReportingId sind definiert

Wenn keine der beiden Reporting-IDs in der Konfiguration der Interessengruppe definiert ist:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

Die Interessengruppe name ist dann in reportWin() verfügbar:

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

Bevor der Name der Interessengruppe (interestGroupName) für reportWin() verfügbar wird, wird er zusammen mit dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Render-URL und der Anzeigengröße auf k-Anonymität geprüft. Die Anzeigengröße wird erst ab dem ersten Quartal 2025 in diese Prüfung einbezogen.

Auswählbare Berichts-IDs

Mit auswählbaren Berichts-IDs kann ein Käufer eine ID während der Gebotsgenerierung auswählen. Der Browser stellt den ausgewählten Wert für scoreAd()- und Berichtsfunktionen zur Verfügung. Der selectableBuyerAndSellerReportingIds-Wert, ein String-Array, wird an generateBid() übergeben und der Käufer kann eine ausgewählte ID als selectedBuyerAndSellerReportingId zurückgeben.

Die Funktionen generateBid() und scoreAd() werden für jede in der Konfiguration der Interessengruppe definierte Anzeige ausgeführt und erhalten die Berichts-IDs für jede Anzeige. Die Berichtsfunktionen für Käufer und Verkäufer werden nur für die Gewinneranzeige ausgeführt und erhalten die für diese Anzeige definierten Berichts-IDs.

Wenn nicht auswählbare Berichts-IDs in Verbindung mit auswählbaren Berichts-IDs verwendet werden, ändert sich ihr Verhalten im Vergleich zum Workflow im vorherigen Abschnitt. Im Gegensatz zum ursprünglichen Verhalten, bei dem nicht auswählbare IDs für die Berichterstellung nur in Berichtsfunktionen verfügbar waren, können sie jetzt auch in generateBid() und scoreAd() verwendet werden.

Interessengruppe

Das Feld „Auswählbare Berichts-IDs“ – selectableBuyerAndSellerReportingIds – ist ein Array von Strings, das vom Käufer in der Interessengruppe für eine Anzeige definiert wird. Neben auswählbaren Berichts-IDs können auch nicht auswählbare Berichts-IDs definiert werden:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

Gebotsgenerierung für Käufer

Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert wurde, ist sie zusammen mit anderen definierten Berichts-IDs in generateBid() verfügbar.

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

Der Käufer kann eine der IDs aus dem selectableBuyerAndSellerReportingIds-Array in generateBid() auswählen und die ausgewählte ID als selectedBuyerAndSellerReportingId zurückgeben. Das Gebot wird abgelehnt, wenn der ausgewählte Wert nicht im selectableBuyerAndSellerReportingIds-Array enthalten ist. Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert ist und der Käufer selectedBuyerAndSellerReportingId nicht von generateBid() zurückgibt, werden die Berichts-IDs auf das Verhalten zurückgesetzt, das für nicht auswählbare Berichts-IDs beschrieben wird.

Ein Gebot mit einem zurückgegebenen Wert für selectedbuyerAndSellerReportingId kann die Auktion nur gewinnen, wenn der Wert von selectedbuyerAndSellerReportingId zusammen mit buyerAndSellerReportingId (falls vorhanden), buyerReportingId (falls vorhanden), dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Render-URL und der Anzeigengröße (die Anzeigengröße wird bis mindestens zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen) gemeinsam k-anonym ist.

Bewertung von Verkäuferanzeigen

Für den Verkäufer ist der selectedBuyerAndSellerReportingId, der vom Käufer aus generateBid() zurückgegeben wurde, in scoreAd() verfügbar, zusammen mit buyerAndSellerReportingId, falls er in der Konfiguration der Interessengruppe definiert wurde.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

Berichterstellung für Verkäufer

Für die Berichterstellung durch Verkäufer ist die selectedBuyerAndSellerReportingId, die vom Käufer aus generateBid() zurückgegeben wurde, in reportResult() verfügbar, zusammen mit buyerAndSellerReportingId, sofern sie in der Interessengruppe definiert wurde.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert wurde und selectedBuyerAndSellerReportingId von generateBid() zurückgegeben wurde, kann das Gebot die Auktion nur gewinnen, wenn selectedBuyerAndSellerReportingId und buyerAndSellerReportingId (falls vorhanden) k-anonym mit dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Render-URL und der Anzeigengröße sind. Die Anzeigengröße wird erst ab dem ersten Quartal 2025 in diese Prüfung einbezogen. reportResult() wird für dieses Gebot nicht ausgeführt. Wenn reportResult() also mit einem Wert für selectedBuyerAndSellerReportingId aufgerufen wird, bedeutet das, dass die Reporting-IDs die k-Anonymitätsprüfung bestanden haben und alle definierten Reporting-IDs in reportResult() verfügbar sind.

Berichterstellung für Käufer

Wenn selectableBuyerAndSellerReportingIds in der Konfiguration der Interessengruppe definiert wurde und selectedBuyerAndSellerReportingId von generateBid() zurückgegeben wurde, sind alle in der Konfiguration der Interessengruppe definierten Reporting-IDs verfügbar. Ähnlich wie bei der Berichterstellung für Verkäufer gilt: Wenn die Berichts-IDs nicht k-anonym sind, können sie die Auktion nicht gewinnen und reportWin() wird für dieses Gebot nicht ausgeführt.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

Regeln überschreiben

Hier fassen wir die Überschreibungsregeln für nicht auswählbare und auswählbare Berichts-IDs zusammen. Welche der folgenden Werte an reportWin() übergeben werden, wird vom Browser anhand der folgenden Logik bestimmt: selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId und der Name der Interessengruppe.

• Wenn selectedBuyerAndSellerReportingId für ein Gebot zurückgegeben wird, sind selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (falls in der Interessengruppe definiert) und buyerReportingId (falls in der Interessengruppe definiert) alle für Berichte verfügbar.
• Wenn buyerAndSellerReportingId in der Interessengruppe definiert ist, ist nur buyerAndSellerReportingId für Berichte verfügbar.
• Wenn buyerReportingId in der Interessengruppe definiert ist, ist nur buyerReportingId für Berichte verfügbar.
• Andernfalls ist nur die Interessengruppe name für Berichte verfügbar.

In der folgenden Tabelle wird das Überschreibungsverhalten beschrieben:

Feedback geben

• Weitere Informationen zu Berichts-IDs
• GitHub: Fragen stellen und Diskussionen in Problemen verfolgen im API-Repository.
• W3C: Branchenspezifische Anwendungsfälle im WICG-Anruf besprechen.
• Ankündigungen: Mailingliste abonnieren oder ansehen.
• Entwicklersupport für die Privacy Sandbox: Fragen stellen und an Diskussionen teilnehmen im Repository für den Entwicklersupport für die Privacy Sandbox.
• Chromium: Chromium-Fehler melden, um Fragen zur Implementierung zu stellen, die in Chrome getestet werden kann.