Berichts-IDs

Informationen zur Funktionsweise von Berichts-IDs in Protected Audience-Auktionen

Übersicht

Berichts-IDs sind IDs, die einer Anzeige zugeordnet sind, und können zum Generieren eines Gebots, zum Bewerten eines Gebots und zum Erstellen von Berichten verwendet werden. Die Berichts-IDs werden vom Käufer in der Interessengruppenkonfiguration bereitgestellt und sind in generateBid(), scoreAd(), reportResult() und reportWin() unter verschiedenen Bedingungen verfügbar, die in diesem Leitfaden erläutert werden.

Mithilfe von Berichts-IDs können Sie eine ID für eine Anzeige melden und Anwendungsfälle wie Deals ermöglichen.

Verfügbarkeit von Identitäten für die Berichterstellung

Es gibt drei Berichts-IDs von zwei Typen:

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

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 Identitäten für die Berichterstellung zusammen mit nicht auswählbaren Identitäten für die Berichterstellung verwendet werden, sind alle definierten IDs auch in generateBid() und scoreAd() verfügbar.

Wichtig :Berichts-IDs werden auf k-Anonymität geprüft, bevor sie in den Berichtsfunktionen (reportResult() und reportWin()) verfügbar sind.

Nicht auswählbare Berichts-IDs

Verfügbarkeit auswählbarer Identitäten für die Berichterstellung

buyerReportingId und buyerAndSellerReportingId sind nicht auswählbare Berichts-IDs, die in der Interessengruppenkonfiguration definiert sind und in Berichtsfunktionen für Käufer und Verkäufer zur Verfügung stehen. Die Berichtsfunktionen für Käufer und Verkäufer werden nur für die erfolgreiche Anzeige ausgeführt. Die Funktionen empfangen die Berichts-IDs, die für die erfolgreiche Anzeige definiert sind.

Wenn sie ohne auswählbare Berichts-IDs verwendet werden, erhält die Berichtsfunktion für Käufer je nach Überschreibungsverhalten buyerReportingId oder buyerAndSellerReportingId und die Berichtsfunktion für Verkäufer buyerAndSellerReportingId. Wenn in der Interessengruppenkonfiguration weder buyerReportingId noch buyerAndSellerReportingId definiert ist, empfängt die reportWin()-Funktion den Interessengruppennamen (interestGroupName) des erfolgreichen Gebots.

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',
  }]
});

Verkäuferberichte

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 ist, wird sie mit dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Rendering-URL und der Anzeigengröße auf k-Anonymität geprüft. Die Anzeigengröße ist mindestens bis zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen. Wenn sie nicht k-anonym ist, wird die reportResult()-Funktion zwar ausgeführt, aber der Wert der Berichts-ID ist in der Funktion nicht verfügbar.

Käuferberichte

Während der Berichtsphase für Käufer in der Auktion wird reportWin() eine Berichts-ID zugewiesen. 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 von 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 in reportWin() verfügbare Berichts-ID wird mit dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Rendering-URL und der Anzeigengröße auf k-Anonymität geprüft. Die Anzeigengröße ist mindestens bis zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen. Wenn die k-Anonymitätsprüfung nicht besteht, wird reportWin() zwar ausgeführt, aber der Wert der Berichts-ID ist in der Funktion nicht verfügbar.

Nur buyerReportingId ist definiert

Wenn in der Interessengruppenkonfiguration nur buyerReportingId definiert ist:

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

Dann ist buyerReportingId 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 Gebotsskript-URL, der Rendering-URL und der Anzeigengröße überprüft (die Anzeigengröße ist mindestens bis zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen).

Es ist nur "buyerAndSellerReportingId" 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',
  }]
});

Dann ist 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 Gebotsskript-URL, der Rendering-URL und der Anzeigengröße überprüft (die Anzeigengröße ist mindestens bis zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen).

Sowohl buyerAndSellerReportingId als auch buyerReportingId sind definiert

Wenn sowohl buyerAndSellerReportingId als auch buyerReportingId in der Interessengruppenkonfiguration definiert sind:

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

Dann ist aufgrund des Überschreibungsverhaltens nur buyerAndSellerReportingId innerhalb von 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 Gebotsskript-URL, der Rendering-URL und der Anzeigengröße überprüft (die Anzeigengröße ist mindestens bis zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen).

Weder buyerAndSellerReportingId noch buyerReportingId sind definiert

Wenn keine der Berichts-IDs in der Interessengruppenkonfiguration definiert ist:

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

Dann ist die Interessengruppe name in reportWin() verfügbar:

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

Bevor der Name der Interessengruppe (interestGroupName) für reportWin() zur Verfügung gestellt wird, wird k-Anonymität mit dem Inhaber der Interessengruppe, der Gebotsskript-URL, der Rendering-URL und der Anzeigengröße überprüft. Die Anzeigengröße ist mindestens bis zum 1. Quartal 2025 von dieser Prüfung ausgeschlossen.

Auswählbare Berichts-IDs

Verfügbarkeit von Berichts-IDs mit auswählbarer Berichts-ID

Über auswählbare Berichts-IDs kann ein Käufer bei der Gebotserstellung eine ID auswählen. Über den Browser wird der ausgewählte Wert dann scoreAd() und Berichtsfunktionen zur Verfügung gestellt. Der Wert selectableBuyerAndSellerReportingIds, bei dem es sich um ein String-Array handelt, wird für generateBid() bereitgestellt und der Käufer kann eine ausgewählte ID als selectedBuyerAndSellerReportingId zurückgeben.

Die Funktionen generateBid() und scoreAd() werden für jede in der Interessengruppenkonfiguration 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 erfolgreiche Anzeige ausgeführt. Die Funktionen empfangen die Berichts-IDs, die für die erfolgreiche Anzeige definiert sind.

Wenn nicht auswählbare Berichts-IDs in Verbindung mit auswählbaren Berichts-IDs verwendet werden, unterscheidet sich ihr Verhalten vom im vorherigen Abschnitt beschriebenen Workflow. Im Gegensatz zum ursprünglichen Verhalten, bei dem nicht auswählbare Berichts-IDs nur in Berichtsfunktionen verfügbar waren, können nicht auswählbare Berichts-IDs mit auswählbaren Berichts-IDs auch in generateBid() und scoreAd() verfügbar gemacht werden.

Hinweis: Die auswählbaren Berichts-IDs sind in der stabilen Version ab M130 verfügbar. Bevor die auswählbaren Berichts-IDs die stabile Version erreichen, können sie getestet werden, indem in der Befehlszeile Canary M130 mit den Flags --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport gestartet wird.

Interessengruppe

Das auswählbare Feld für die Berichts-IDs (selectableBuyerAndSellerReportingIds) besteht aus einem Array von Strings, die vom Käufer in der Interessengruppe für eine Anzeige definiert wurden. Nicht auswählbare Berichts-IDs können auch zusammen mit auswählbaren 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 durch 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(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  } = browserSignals;

  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 Array selectableBuyerAndSellerReportingIds enthalten ist. Wenn selectableBuyerAndSellerReportingIds in der Interessengruppenkonfiguration definiert ist und der Käufer selectedBuyerAndSellerReportingId von generateBid() nicht zurückgibt, gilt für die Berichts-IDs die für nicht auswählbare Berichts-IDs beschriebene Funktionsweise.

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

Hinweis: Falls generateBid() noch einmal ausgeführt wird, weil beim ersten Aufruf keine Gebote mit Anzeigen abgegeben wurden, die die k-Anonymitätsprüfungen bestanden haben, sind selectableBuyerAndSellerReportingIds, die die k-Anonymitätsprüfung nicht bestehen, bei der erneuten Ausführung nicht in der Interessengruppe enthalten.

Bewertung der Verkäuferanzeigen

Für den Verkäufer ist die selectedBuyerAndSellerReportingId, die der Käufer vom generateBid() zurückgegeben hat, in scoreAd() verfügbar, zusammen mit buyerAndSellerReportingId, wenn sie in der Interessengruppenkonfiguration definiert wurde.

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

  // ...
}

Verkäuferberichte

Für Verkäuferberichte ist das selectedBuyerAndSellerReportingId, das der Käufer vom generateBid() zurückgegeben hat, in reportResult() verfügbar, zusammen mit buyerAndSellerReportingId, falls es 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 die Auktion nur dann gewonnen werden, wenn selectedBuyerAndSellerReportingId und buyerAndSellerReportingId (falls vorhanden) k-anonym mit dem Inhaber der Interessengruppe, der URL des Gebotsscripts, der Rendering-URL und der Anzeigengröße sind. Die Anzeigengröße ist bis mindestens Q1 2025 von dieser Prüfung ausgenommen. reportResult() wird für dieses Gebot nicht ausgeführt. Wenn reportResult() mit einem Wert für selectedBuyerAndSellerReportingId aufgerufen wird, bedeutet dies, dass die Berichts-IDs die k-Anonymitätsprüfung bestanden haben und alle definierten Berichts-IDs in reportResult() verfügbar sind.

Käuferberichte

Wenn selectableBuyerAndSellerReportingIds in der Interessengruppenkonfiguration definiert und selectedBuyerAndSellerReportingId von generateBid() zurückgegeben wurde, sind alle Berichts-IDs verfügbar, die in der Interessengruppenkonfiguration definiert wurden. Ähnlich wie bei Verkäuferberichten 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

Im Folgenden finden Sie eine Zusammenfassung der Überschreibungsregeln für nicht auswählbare und auswählbare Berichts-IDs. Welcher der folgenden Werte ist selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId und der Interessengruppenname, der an reportWin() übergeben wird, wird vom Browser anhand der folgenden Logik bestimmt:

• Wenn selectedBuyerAndSellerReportingId von einem Gebot zurückgegeben wird, stehen selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (falls in der Interessengruppe definiert) und buyerReportingId (falls in der Interessengruppe definiert) für die Berichterstellung zur Verfügung.
• Wenn buyerAndSellerReportingId in der Interessengruppe definiert ist, steht nur buyerAndSellerReportingId für Berichte zur Verfügung.
• Wenn buyerReportingId in der Interessengruppe definiert ist, steht nur buyerReportingId für Berichte zur Verfügung.
• Andernfalls steht nur die Interessengruppe „name“ für die Berichterstellung zur Verfügung.

In der folgenden Tabelle wird das Überschreibungsverhalten beschrieben:

Sind die Berichts-IDs in der Interessengruppenkonfiguration definiert?			Verfügbare Berichts-IDs
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Ja und in generateBid() ausgewählt	Optional	Optional	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (falls definiert) 3) buyerReportingId (falls definiert)	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (falls definiert)
Nein oder nicht ausgewählt in generateBid()	Ja	Ignoriert	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Nein oder nicht ausgewählt in generateBid()	Nein	Ja	buyerReportingId	Keine
Nein oder nicht ausgewählt in generateBid()	Nein	Nein	interestGroupName	Keine

Mit Nutzern interagieren und Feedback geben

• Weitere Informationen zu Identitäten für die Berichterstellung finden Sie im Abschnitt „Identität für die Berichterstellung“ der Erläuterung zu geschützten Zielgruppen.
• GitHub Im API-Repository können Sie Fragen stellen und Diskussionen zu Problemen folgen.
• W3C: Im WICG-Anruf werden Anwendungsfälle aus der Branche besprochen.
• Ankündigungen: Sie können der Mailingliste beitreten oder sich die Liste ansehen.
• Privacy Sandbox-Entwicklersupport: Im Privacy Sandbox-Repository für Entwicklersupport können Sie Fragen stellen und sich an Diskussionen beteiligen.
• Chromium: Melden Sie Chromium-Fehler, um Fragen zur für das Testen in Chrome verfügbaren Implementierung zu stellen.