Identyfikatory raportowania

Dowiedz się, jak działają identyfikatory raportów w aukcji z chronioną listą odbiorców

Omówienie

Identyfikatory raportowania to identyfikatory powiązane z reklamą, które są dostępne do generowania stawki, oceniania stawki i raportowania. Identyfikatory raportowania są udostępniane przez kupującego w konfiguracji grupy zainteresowań i stają się dostępne w kampaniach generateBid(), scoreAd(), reportResult() i reportWin() w zależności od różnych warunków, które są omawiane w tym przewodniku.

Identyfikatory raportowania umożliwiają raportowanie identyfikatora reklamy, a także umożliwiają stosowanie takich przypadków użycia jak oferty.

Dostępność identyfikatorów raportowania

Istnieją 3 typy identyfikatorów raportowania:

• Identyfikatory raportowania, których nie można wybrać:
  • buyerReportingId (ciąg znaków)
  • buyerAndSellerReportingId (ciąg znaków)
• Dostępne identyfikatory raportowania:
  • selectableBuyerAndSellerReportingIds (tabelka ciągów tekstowych)

Identyfikatory raportowania zachowują się inaczej w zależności od tego, czy są to wybieralne identyfikatory raportowania. Jeśli używane są tylko niewybierane identyfikatory raportowania, są one dostępne tylko w ramach funkcji raportowania. Jeśli używane są wybieralne identyfikatory raportowania, a w razie potrzeby – również niewybieralne identyfikatory raportowania, wszystkie zdefiniowane identyfikatory są dostępne w elementach generateBid() i scoreAd().

Ważne: przed udostępnieniem identyfikatorów raportowania w funkcjach raportowania (reportResult() i reportWin()) sprawdzana jest ich k-anonimizacja.

Niewybierane identyfikatory raportowania

Dostępność identyfikatorów raportów do wyboru

buyerReportingId i buyerAndSellerReportingId to niewybierane identyfikatory raportowania zdefiniowane w konfiguracji grupy zainteresowań, które stają się dostępne w funkcjach raportowania dla kupujących i sprzedawców. Funkcje raportowania dla kupującego i sprzedawcy będą działać tylko w przypadku reklamy zwycięskiej. Funkcje te będą otrzymywać identyfikatory raportowania zdefiniowane dla tej reklamy.

Jeśli nie używasz funkcji raportowania z wybieranymi identyfikatorami raportowania, funkcja raportowania dla kupującego otrzymuje wartość buyerReportingId lub buyerAndSellerReportingId w zależności od zachowania zastępowania, a funkcja raportowania dla sprzedawcy otrzymuje wartość buyerAndSellerReportingId. Jeśli w konfiguracji grupy zainteresowań nie zdefiniowano ani wartości buyerReportingId, ani buyerAndSellerReportingId, funkcja reportWin() otrzymuje nazwę grupy zainteresowań (interestGroupName) z wygrywającej stawki.

Identyfikatory, których nie można wybrać, nie są dostępne w elementach generateBid() i scoreAd(), jeśli nie są używane w połączeniu z identyfikatorami raportowania, których można używać.

Identyfikatory raportowania w grupach zainteresowań

Identyfikatory raportowania są definiowane przez kupującego w przypadku każdej reklamy w grupie zainteresowań:

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

Raportowanie przez sprzedawcę

W fazie raportowania dotyczącego sprzedawcy wartość buyerAndSellerReportingId staje się dostępna dla reportResult():

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

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

Zanim identyfikator stanie się dostępny w reportResult(), jest sprawdzany pod kątem k-anonimowości w przypadku właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do pierwszego kwartału 2025 r.). Jeśli nie jest k-anonimiczny, funkcja reportResult() nadal się wykona, ale wartość identyfikatora raportowania nie będzie dostępna w ramach tej funkcji.

Raporty o kupujących

W fazie raportowania kupującego w aukcji reportWin() staje się dostępny jeden identyfikator raportowania. Jeśli w grupie zainteresowań zdefiniowano więcej niż 1 identyfikator raportowania, zostanie zastosowana reguła zastępowania, w której buyerAndSellerReportingId zastępuje buyerReportingId:

• Jeśli zdefiniowane są zarówno właściwości buyerAndSellerReportingId, jak i buyerReportingId, to pierwsza z nich (buyerAndSellerReportingId) zastąpi drugą (buyerReportingId), a w ramach właściwości reportWin() będzie dostępna tylko pierwsza.buyerAndSellerReportingId
• Jeśli zdefiniowano tylko buyerReportingId, dostępna będzie opcja buyerReportingId.
• Jeśli nie zdefiniujesz ani buyerAndSellerReportingId, ani buyerReportingId, będzie dostępna opcja interestGroupName.

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

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

Identyfikator raportowania, który jest dostępny w reportWin(), jest sprawdzany pod kątem k-anonimowości w przypadku właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.). Jeśli nie przejdzie ona weryfikacji k-anonimizacji, funkcja reportWin() zostanie mimo to wykonana, ale wartość identyfikatora raportowania nie będzie dostępna w ramach funkcji.

Zdefiniowana jest tylko funkcja buyerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowana jest tylko zmienna buyerReportingId:

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

Następnie buyerReportingId jest dostępne w reportWin():

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

Zanim dane reportWin() staną się dostępne dla reportWin(), buyerReportingId jest sprawdzany pod kątem anonimowości k-anonimowości z uwzględnieniem właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartala 2025 r.).

Zdefiniowany jest tylko buyerAndSellerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowana jest tylko zmienna buyerAndSellerReportingId:

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

Następnie buyerAndSellerReportingId jest dostępne w reportWin():

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

Zanim dane reportWin() staną się dostępne dla reportWin(), buyerAndSellerReportingId jest sprawdzany pod kątem anonimowości k-anonimowości u właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i wielkości reklamy (wielkość reklamy jest wyłączona z tego sprawdzania co najmniej do I kwartału 2025 r.).

Zdefiniowane są oba parametry: buyerAndSellerReportingId i buyerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowane są zarówno buyerAndSellerReportingId, jak i buyerReportingId:

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

W takim przypadku tylko buyerAndSellerReportingId jest dostępne w ramach reportWin() ze względu na zachowanie zastępowania:

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

Zanim dane reportWin() staną się dostępne dla reportWin(), buyerAndSellerReportingId jest sprawdzany pod kątem anonimowości k-anonimowości z uwzględnieniem właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartala 2025 r.).

Ani buyerAndSellerReportingId, ani buyerReportingId nie są zdefiniowane

Jeśli w konfiguracji grupy zainteresowań nie ma zdefiniowanych identyfikatorów raportowania:

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

Grupa zainteresowań name jest dostępna w ramach reportWin():

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

Zanim nazwa grupy zainteresowań (interestGroupName) stanie się dostępna dla reportWin(), jest sprawdzana pod kątem anonimowości k-anonimowej w przypadku właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do pierwszego kwartału 2025 r.).

Identyfikatory raportowania do wyboru

Dostępność identyfikatorów raportów z możliwością wyboru identyfikatora raportu

Identyfikatory raportowania, które można wybrać, umożliwiają kupującemu wybranie identyfikatora podczas generowania stawek, a przeglądarka udostępnia wybraną wartość funkcjom scoreAd() i raportowania. Wartość selectableBuyerAndSellerReportingIds, która jest tablicą ciągów znaków, jest przekazywana do generateBid(), a kupujący może zwrócić jeden wybrany identyfikator jako selectedBuyerAndSellerReportingId.

Funkcje generateBid() i scoreAd() będą działać w przypadku każdej reklamy zdefiniowanej w konfiguracji grupy zainteresowań i otrzymają identyfikatory raportowania dla każdej reklamy. Funkcje raportowania dla kupującego i sprzedawcy będą działać tylko w przypadku reklamy zwycięskiej. Funkcje te będą otrzymywać identyfikatory raportowania zdefiniowane dla tej reklamy.

Gdy identyfikatory raportowania, których nie można wybrać, są używane razem z identyfikatorami raportowania, których można używać, ich działanie różni się od opisanego w poprzedniej sekcji. W przeciwieństwie do początkowego zachowania, gdy identyfikatory raportowania, których nie można wybrać, były dostępne tylko w funkcjach raportowania, identyfikatory raportowania, których nie można wybrać, są teraz dostępne także w funkcjach generateBid() i scoreAd().

Uwaga: wybieralne identyfikatory raportowania będą dostępne w wersji stabilnej w wersji M130. Zanim wybrane identyfikatory raportowania dotrą do wersji stabilnej, możesz je przetestować, uruchamiając Canary M130 z wiersza poleceń z flagami --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

.

Grupa zainteresowań

Pole z wybieranymi identyfikatorami raportowania (selectableBuyerAndSellerReportingIds) to tablica ciągów znaków zdefiniowanych przez kupującego w grupie zainteresowań dla reklamy. Oprócz dostępnych identyfikatorów raportowania można też zdefiniować identyfikatory raportowania, których nie można wybrać:

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

Generowanie stawek przez kupującego

Jeśli w konfiguracji grupy zainteresowań zdefiniowano identyfikator selectableBuyerAndSellerReportingIds, staje się on dostępny w konfiguracji generateBid() wraz z innymi zdefiniowanymi identyfikatorami raportowania.

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

Kupujący może wybrać jeden z identyfikatorów z tablicy selectableBuyerAndSellerReportingIds w generateBid() i zwrócić wybrany identyfikator jako selectedBuyerAndSellerReportingId. Stawka zostanie odrzucona, jeśli wybrana wartość nie znajduje się w tablicy selectableBuyerAndSellerReportingIds. Jeśli w konfiguracji grupy zainteresowań zdefiniowany jest parametr selectableBuyerAndSellerReportingIds, a kupujący nie zwraca wartości selectedBuyerAndSellerReportingId z parametru generateBid(), identyfikatory raportowania powrócą do zachowania opisanego w sekcji Identyfikatory raportowania, których nie można wybrać.

Stawka z wartością zwracaną dla selectedbuyerAndSellerReportingId może wygrać aukcję tylko wtedy, gdy wartość selectedbuyerAndSellerReportingId jest wspólnie k-anonimowa z wartością buyerAndSellerReportingId (jeśli występuje), buyerReportingId (jeśli występuje), właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, adresem URL renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tej kontroli co najmniej do pierwszego kwartału 2025 r.).

Uwaga: jeśli generateBid() jest ponownie wykonywane, ponieważ początkowe wywołanie nie wygenerowało żadnych stawek z reklamami, które przeszły weryfikację anonimowości k, to ids raportowania kupującego i sprzedawającego, które nie przeszły weryfikacji anonimowości k, nie będą obecne w grupie zainteresowań podczas ponownego wykonania.

Ocenianie reklam sprzedawcy

W przypadku sprzedawcy selectedBuyerAndSellerReportingId zwrócone przez kupującego z generateBid() staje się dostępne w scoreAd() wraz z buyerAndSellerReportingId, jeśli zostało zdefiniowane w konfiguracji grupy zainteresowań.

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

  // ...
}

Raportowanie przez sprzedawcę

W przypadku raportowania dla sprzedawcy selectedBuyerAndSellerReportingId zwrócone przez kupującego z generateBid() staje się dostępne w reportResult() wraz z buyerAndSellerReportingId, jeśli zostało zdefiniowane w grupie zainteresowań.

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

Jeśli selectableBuyerAndSellerReportingIds została zdefiniowana w konfiguracji grupy zainteresowań, a selectedBuyerAndSellerReportingId została zwrócona z generateBid(), nie może wygrać aukcji, chyba że selectedBuyerAndSellerReportingId i buyerAndSellerReportingId (jeśli występuje) są k-anonimowe w stosunku do właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy jest wykluczony z tej kontroli do co najmniej I kwartału 2025 r.), a reportResult() nie zostanie wykonana w przypadku tej stawki. Jeśli więc funkcja reportResult() zostanie wywołana z wartością selectedBuyerAndSellerReportingId, oznacza to, że identyfikatory raportowania przeszły weryfikację k-anonimowości, a wszystkie zdefiniowane identyfikatory raportowania będą dostępne w funkcji reportResult().

Raporty o kupujących

Jeśli w konfiguracji grupy zainteresowań zdefiniowano parametr selectableBuyerAndSellerReportingIds, a z parametru generateBid() zwrócono wartość selectedBuyerAndSellerReportingId, stają się dostępne wszystkie identyfikatory raportowania zdefiniowane w konfiguracji grupy zainteresowań. Pamiętaj, że podobnie jak w przypadku raportowania przez sprzedawcę, jeśli identyfikatory raportowania nie są anonimowe, nie mogą wygrać aukcji i reportWin() nie będzie działać dla tej stawki.

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

  // ...
}

Zastępowanie reguł

Poniżej przedstawiamy reguły zastępowania zarówno w przypadku niewybieranych, jak i wybieranych identyfikatorów raportów. Który z parametrów selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId lub nazwa grupy zainteresowań zostanie przekazany do reportWin(), określa przeglądarka za pomocą tej logiki:

• Jeśli selectedBuyerAndSellerReportingId zwraca wartość z oferty, do raportowania są dostępne wartości selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jeśli są zdefiniowane w grupie zainteresowań) i buyerReportingId (jeśli są zdefiniowane w grupie zainteresowań).
• Jeśli w grupie zainteresowań zdefiniowano zmienną buyerAndSellerReportingId, do celów raportowania dostępna jest tylko zmienna buyerAndSellerReportingId.
• Jeśli w grupie zainteresowań zdefiniowano zmienną buyerReportingId, do celów raportowania dostępna jest tylko zmienna buyerReportingId.
• W przeciwnym razie do celów raportowania dostępna jest tylko grupa zainteresowań name.

W tabeli poniżej opisano zachowanie zastępowania:

Czy identyfikatory raportowania są zdefiniowane w konfiguracji grupy zainteresowań?			Dostępne identyfikatory raportowania
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Tak, wybrano w generateBid()	Opcjonalny	Opcjonalny	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (jeśli zdefiniowano) 3) buyerReportingId (jeśli zdefiniowano)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (jeśli zdefiniowany)
Nie, lub nie wybrano w generateBid()	Tak	Zignorowano	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Nie, lub nie wybrano w generateBid()	Nie	Tak	buyerReportingId	Brak
Nie lub nie wybrano w generateBid()	Nie	Nie	interestGroupName	Brak

Zaangażowanie i przesyłanie opinii

• Więcej informacji o tożsamości na potrzeby raportowania znajdziesz w sekcji „Tożsamość na potrzeby raportowania” w artykule o chronienych adresatach.
• GitHub zadawaj pytania i śledź dyskusję w problemach w repozytorium API.
• W3C: omówienie zastosowań w branży podczas spotkania WICG.
• Ogłoszenia: dołącz do listy mailingowej lub wyświetl ją.
• Pomoc dla deweloperów w Piaskownicy prywatności: zadawaj pytania i ucz się na podstawie dyskusji w repozytorium pomocy dla deweloperów w Piaskownicy prywatności.
• Chromium zgłoś błąd w Chromium, aby zadać pytania dotyczące implementacji dostępnej do testowania w Chrome.