Identyfikatory raportowania

Jak działają identyfikatory raportowania w aukcji z Protected Audience API

Omówienie

Identyfikatory raportowania to identyfikatory powiązane z reklamą, które można wykorzystać do generowania stawek, ustalania stawek i raportowania. Identyfikatory raportowania podaje kupujący w konfiguracji grupy zainteresowań i stają się one dostępne w usługach generateBid(), scoreAd(), reportResult() i reportWin() w różnych warunkach opisanych w tym przewodniku.

Identyfikatory raportowania pozwalają raportować identyfikator reklamy, a także umożliwiają zastosowanie przypadków użycia takich jak umowy.

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)
• Identyfikatory raportowania do wyboru
  • selectableBuyerAndSellerReportingIds (tablica ciągów znaków)

Sposób działania identyfikatorów raportowania zależy od tego, czy zostaną użyte do wyboru identyfikatory raportowania. Jeśli używasz tylko identyfikatorów raportowania, których nie można wybrać, stają się one dostępne tylko w funkcjach 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.

Identyfikatory raportowania, których nie można wybrać

Dostępność identyfikatorów raportowania 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, a funkcje te będą otrzymywać identyfikatory raportowania zdefiniowane dla tej reklamy.

Jeśli używasz tej funkcji bez identyfikatorów raportowania do wyboru, funkcja raportowania o kupujących otrzymuje wartość buyerReportingId lub buyerAndSellerReportingId w zależności od zastępowania, a funkcja raportowania o sprzedawcy otrzymuje wartość buyerAndSellerReportingId. Jeśli w konfiguracji grupy zainteresowań nie określono ani buyerReportingId, ani buyerAndSellerReportingId, funkcja reportWin() otrzyma nazwę grupy zainteresowań (interestGroupName) zwycięskiej stawki.

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

Identyfikatory raportowania w grupach zainteresowań

Identyfikatory raportowania określa kupujący dla 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',
  }]
});

Raporty o sprzedawcach

Na etapie raportowania 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 on sprawdzany pod kątem k-anonimowości z właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, adresem URL renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.). Jeśli nie jest to k-anonimowa, funkcja reportResult() zostanie uruchomiona, ale wartość identyfikatora raportowania nie będzie dostępna w funkcji.

Raporty dotyczące kupujących

W fazie raportowania kupującego w ramach aukcji reportWin() staje się dostępny jeden identyfikator raportowania. Jeśli w grupie zainteresowań zdefiniowany jest więcej niż 1 identyfikator raportowania, stosowana jest reguła zastępowania, gdzie buyerAndSellerReportingId zastępuje buyerReportingId:

• Jeśli są zdefiniowane zarówno buyerAndSellerReportingId, jak i buyerReportingId, funkcja buyerAndSellerReportingId zastąpi tag buyerReportingId, a pole buyerAndSellerReportingId będzie dostępne w elemencie reportWin().
• Jeśli zdefiniowana jest tylko wartość buyerReportingId, dostępna będzie wartość buyerReportingId.
• Jeśli nie zdefiniowano ani buyerAndSellerReportingId, ani buyerReportingId, wartość interestGroupName będzie dostępna.

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

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

Identyfikator raportowania, który staje się dostępny w reportWin(), jest sprawdzany pod kątem k-anonimowości z uwzględnieniem właściciela grupy zainteresowań, adresu URL skryptu ustalania stawek, adresu URL renderowania i wymiaru reklamy (wymiar reklamy jest wykluczony z tego sprawdzania do co najmniej I kwartala 2025 r.). Jeśli nie przejdzie weryfikacji k-anonimowości, funkcja reportWin() zostanie nadal wykonana, ale wartość identyfikatora raportowania nie będzie dostępna w ramach funkcji.

Określono tylko buyerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowano tylko 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;
}

Przed udostępnieniem na platformie reportWin() narzędzie buyerReportingId jest sprawdzane pod kątem k-anonimowości z właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, adresem URL renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.).

Zdefiniowano tylko identyfikator kupującegoAndSellerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowano tylko buyerAndSellerReportingId:

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

Potem buyerAndSellerReportingId jest dostępny w pakiecie reportWin():

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

Przed udostępnieniem na platformie reportWin() narzędzie buyerAndSellerReportingId jest sprawdzane pod kątem k-anonimowości z właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, adresem URL renderowania i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.).

Zdefiniowano obiekty buyerAndSellerReportingId i buyerReportingId

Jeśli w konfiguracji grupy zainteresowań są zdefiniowane 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 tym przypadku tylko buyerAndSellerReportingId jest dostępne w ramach reportWin() z powodu zachowania 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 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.).

Nie zdefiniowano ani buyerAndSellerReportingId, ani buyerReportingId

Jeśli w konfiguracji grupy zainteresowań nie określono żadnego identyfikatora raportowania:

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

Następnie grupa zainteresowań name jest dostępna w elemencie reportWin():

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

Zanim nazwa grupy zainteresowań (interestGroupName) będzie dostępna dla platformy reportWin(), jest sprawdzana pod kątem k-anonimowości z właścicielami grupy zainteresowań, adresem URL skryptu ustalania stawek, wyrenderowanym adresem URL i rozmiarem reklamy (rozmiar reklamy nie jest objęty tym sprawdzaniem co najmniej do I kwartału 2025 r.).

Identyfikatory raportowania do wyboru

Dostępność identyfikatorów raportowania z wybranym identyfikatorem

Wybierane identyfikatory raportowania umożliwiają kupującemu wybór identyfikatora podczas generowania stawek, a przeglądarka udostępnia wybraną wartość funkcjom scoreAd() i raportowania. Do generateBid() jest przekazywana wartość selectableBuyerAndSellerReportingIds, która jest tablicą ciągów znaków, a kupujący może zwrócić jeden wybrany identyfikator w postaci selectedBuyerAndSellerReportingId.

Funkcje generateBid() i scoreAd() zostaną uruchomione w przypadku każdej reklamy zdefiniowanej w konfiguracji grupy zainteresowań i otrzymają identyfikatory raportowania poszczególnych reklam. Funkcje raportowania kupującego i sprzedawcy będą działać tylko w przypadku zwycięskiej reklamy i otrzymają identyfikatory raportowania zdefiniowane dla zwycięskiej 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 odróżnieniu od początkowego działania niemożliwych do wyboru identyfikatorów raportowania, które są dostępne tylko w funkcjach raportowania, możliwe do wyboru identyfikatory raportowania umożliwiają udostępnianie takich identyfikatorów w funkcjach generateBid() i scoreAd().

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

Grupa zainteresowań

Pole identyfikatorów raportowania do wyboru – selectableBuyerAndSellerReportingIds – to tablica ciągów znaków zdefiniowanych przez kupującego w grupie zainteresowań związanej z reklamą. Niedostępne do wyboru identyfikatory raportowania możesz też zdefiniować razem z identyfikatorami raportowania, które 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 kupującego

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

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

Kupujący może wybrać jeden z identyfikatorów z tablicy selectableBuyerAndSellerReportingIds w narzędziu generateBid() i zwrócić wybrany identyfikator jako selectedBuyerAndSellerReportingId. Stawka jest odrzucana, jeśli wybranej wartości nie ma w tablicy selectableBuyerAndSellerReportingIds. Jeśli w konfiguracji grupy zainteresowań jest zdefiniowany identyfikator selectableBuyerAndSellerReportingIds, a kupujący nie zwróci wartości selectedBuyerAndSellerReportingId z metody generateBid(), identyfikatory raportowania przywrócą działanie opisane w przypadku identyfikatorów raportowania, których nie można wybrać.

Stawka ze zwróconą wartością selectedbuyerAndSellerReportingId może wygrać aukcję tylko wtedy, gdy wartość selectedbuyerAndSellerReportingId jest k-anonimowa razem z wartością buyerAndSellerReportingId (jeśli występuje), buyerReportingId (jeśli występuje), właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, URL-em renderowania oraz rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do I kwartału 2025 r.).

Uwaga: w przypadku ponownego uruchomienia tagu generateBid(), ponieważ pierwotne wywołanie nie wygenerowało żadnych stawek z reklamami, które przeszły weryfikację k-anonimowości, pola selectableBuyerAndSellerReportingIdy niezaliczone przez kontrolę k-anonimowości nie będą widoczne w grupie zainteresowań po ponownym uruchomieniu.

Ocenianie reklam sprzedawców

W przypadku sprzedawcy wartość selectedBuyerAndSellerReportingId zwrócona przez kupującego od kupującego generateBid() stanie się dostępna w scoreAd(), a także buyerAndSellerReportingId, jeśli została ona określona w konfiguracji grupy zainteresowań.

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

  // ...
}

Raportowanie sprzedawcy

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 w konfiguracji grupy zainteresowań został zdefiniowany parametr selectableBuyerAndSellerReportingIds, a z odpowiedzi selectedBuyerAndSellerReportingId został zwrócony wynik selectedBuyerAndSellerReportingId, nie może wygrać aukcji, chyba że elementy selectedBuyerAndSellerReportingId i buyerAndSellerReportingId (jeśli występują) są k-anonimowe z właścicielem grupy zainteresowań, adresem URL skryptu ustalania stawek, wyrenderowanym adresem URL i rozmiarem reklamy (rozmiar reklamy jest wykluczony z tego sprawdzania co najmniej do pierwszego kwartału 2025 r.), a reportResult() nie zostanie przeprowadzone w przypadku tej stawki.generateBid() Dlatego jeśli funkcja reportResult() jest wywoływana z wartością selectedBuyerAndSellerReportingId, oznacza to, że identyfikatory raportowania przeszły kontrolę k-anonimowości, a wszystkie zdefiniowane identyfikatory raportowania będą dostępne w usłudze reportResult().

Raporty dotyczące kupujących

Jeśli w konfiguracji grupy zainteresowań określono ustawienie selectableBuyerAndSellerReportingIds, a wartość selectedBuyerAndSellerReportingId została zwrócona z metody generateBid(), wszystkie identyfikatory raportowania określone w konfiguracji grupy zainteresowań stają się dostępne. Pamiętaj, że podobnie jak w przypadku raportów o sprzedawcach, jeśli identyfikatory raportowania nie zawierają k-anonimowych identyfikatorów, nie mogą wygrać aukcji, a strategia reportWin() nie będzie brać udziału w aukcji z tą stawką.

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

  // ...
}

Zastąp reguły

Poniżej znajdziesz podsumowanie reguł zastępowania zarówno w przypadku identyfikatorów raportowania, których nie można wybrać, jak i tych, które można wybrać. To, które z zasad selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId i nazwy grupy zainteresowań są przekazywane do reportWin(), jest określane przez przeglądarkę w ten sposób:

• Jeśli stawka selectedBuyerAndSellerReportingId zostanie zwrócona ze stawki, na potrzeby raportowania będą dostępne wartości selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jeśli zdefiniowano je w grupie zainteresowań) i buyerReportingId (jeśli zostały określone w grupie zainteresowań).
• Jeśli nie, jeśli w grupie zainteresowań jest zdefiniowany identyfikator buyerAndSellerReportingId, do raportowania dostępna jest tylko wartość buyerAndSellerReportingId.
• Jeśli w grupie zainteresowań zdefiniowana jest wartość buyerReportingId, na potrzeby raportowania dostępna jest tylko wartość buyerReportingId.
• W przeciwnym razie w raportach dostępna będzie tylko grupa zainteresowań name.

W tej tabeli opisano sposób zastępowania:

Czy identyfikatory raportowania są określone w konfiguracji grupy zainteresowań?			Dostępne identyfikatory raportowania
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Tak, wybrano w generateBid()	Opcjonalnie	Opcjonalnie	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (jeśli został określony) 3) buyerReportingId (jeśli został określony)	1) selectableBuyerAnd 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 kategorii generateBid()	Nie	Nie	interestGroupName	Brak

Angażuj odbiorców i dziel się opiniami

• Więcej informacji o tożsamości na potrzeby raportowania znajdziesz w sekcji „Tożsamość na potrzeby raportowania” w artykule wprowadzającym do chronionych list odbiorców.
• GitHub zadawaj pytania i bierz udział w dyskusjach na temat problemów w repozytorium interfejsów API.
• W3C: przedyskutuj przypadki użycia w branży podczas wywołania WICG.
• Ogłoszenia: dołącz do listy adresowej lub dołącz do niej.
• Pomoc dla deweloperów Piaskownicy prywatności: zadawaj pytania i dołączaj do dyskusji w repozytorium pomocy dla deweloperów Piaskownicy prywatności.
• Chromium: zgłoś błąd w Chromium, by zadać pytania na temat implementacji dostępnej do przetestowania w Chrome.