Identyfikatory raportowania

Dowiedz się, jak działają identyfikatory raportowania na aukcji z użyciem Protected Audience API

Przegląd

Identyfikatory raportowania to identyfikatory powiązane z reklamą, które są dostępne do użycia podczas generowania stawki, jej oceniania i raportowania. Identyfikatory raportowania są podawane przez kupującego w konfiguracji grupy zainteresowań i stają się dostępne w polach generateBid(), scoreAd(), reportResult() i reportWin() w różnych warunkach, które omawiamy w tym przewodniku.

Identyfikatory raportowania umożliwiają zgłaszanie identyfikatora reklamy, a także korzystanie z przypadków użycia, takich jak transakcje.

Istnieją 3 identyfikatory raportowania 2 rodzajów:

• Identyfikatory raportowania, których nie można wybrać
  • buyerReportingId (ciąg znaków)
  • buyerAndSellerReportingId (ciąg znaków)
• Identyfikatory raportowania, które można wybrać
  • selectableBuyerAndSellerReportingIds (tablica ciągów tekstowych)

Identyfikatory na potrzeby raportowania działają inaczej w zależności od tego, czy są używane identyfikatory na potrzeby raportowania, które można wybrać. Jeśli używane są tylko identyfikatory raportowania, których nie można wybrać, są one dostępne tylko w funkcjach raportowania. Jeśli używane są identyfikatory raportowania, które można wybrać, a w razie potrzeby także identyfikatory raportowania, których nie można wybrać, wszystkie zdefiniowane identyfikatory stają się dostępne w generateBid() i scoreAd().

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

buyerReportingId i buyerAndSellerReportingId to identyfikatory raportowania, których nie można wybrać. Są one zdefiniowane w konfiguracji grupy zainteresowań i dostępne w funkcjach raportowania kupujących i sprzedawców. Funkcje raportowania kupującego i sprzedawcy będą uruchamiane tylko w przypadku zwycięskiej reklamy i będą otrzymywać identyfikatory raportowania zdefiniowane dla tej reklamy.

Gdy funkcja jest używana bez identyfikatorów raportowania, które można wybrać, funkcja raportowania kupującego otrzymuje wartość buyerReportingId lub buyerAndSellerReportingId w zależności od zachowania związanego z zastępowaniem, a funkcja raportowania sprzedawcy otrzymuje wartość buyerAndSellerReportingId. Jeśli w konfiguracji grupy zainteresowań nie zdefiniowano ani buyerReportingId, ani buyerAndSellerReportingId, funkcja reportWin() otrzymuje nazwę grupy zainteresowań (interestGroupName) zwycięskiej stawki.

Identyfikatory, których nie można wybrać, nie są dostępne w przypadku funkcji 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 są definiowane przez kupującego 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',
  }]
});

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 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 ona k-anonimowa, funkcja reportResult() nadal będzie działać, ale wartość identyfikatora raportowania nie będzie w niej dostępna.

Raporty kupujących

Podczas fazy raportowania kupującego w aukcji reportWin() udostępnia jeden identyfikator raportowania. Jeśli w grupie zainteresowań zdefiniowano więcej niż 1 identyfikator raportowania, stosowana jest reguła zastępowania, w której buyerAndSellerReportingId zastępuje buyerReportingId:

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

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 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 przejdzie testu k-anonimowości, funkcja reportWin() nadal będzie działać, ale wartość identyfikatora raportowania nie będzie w niej dostępna.

Zdefiniowana jest tylko wartość 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',
  }]
});

Wtedy buyerReportingId jest dostępny w reportWin():

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

Zanim reportWin() stanie się dostępny dla buyerReportingId, sprawdzana jest jego k-anonimowość w przypadku właściciela grupy zainteresowań, adresu URL skryptu określania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy nie jest uwzględniany w tym sprawdzaniu co najmniej do pierwszego kwartału 2025 r.).

Zdefiniowany jest tylko identyfikator buyerAndSellerReportingId

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

Wtedy buyerAndSellerReportingId jest dostępny w reportWin():

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

Zanim reportWin() stanie się dostępny dla buyerAndSellerReportingId, sprawdzana jest jego k-anonimowość w przypadku właściciela grupy zainteresowań, adresu URL skryptu określania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy nie jest uwzględniany w tym sprawdzaniu co najmniej do pierwszego kwartału 2025 r.).

Zdefiniowane są zarówno buyerAndSellerReportingId, jak 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 w reportWin() dostępna jest tylko wartość buyerAndSellerReportingId ze względu na zachowanie zastępowania:

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

Zanim reportWin() stanie się dostępny dla buyerAndSellerReportingId, sprawdzana jest jego k-anonimowość w przypadku właściciela grupy zainteresowań, adresu URL skryptu określania stawek, adresu URL renderowania i rozmiaru reklamy (rozmiar reklamy nie jest uwzględniany w tym sprawdzaniu co najmniej do pierwszego kwartału 2025 r.).

Nie zdefiniowano ani buyerAndSellerReportingId, ani buyerReportingId

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

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

W takim przypadku grupa zainteresowań name jest dostępna w 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 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.).

Identyfikatory raportowania, które można wybrać

Identyfikatory raportowania, które można wybrać, umożliwiają kupującemu wybranie identyfikatora podczas generowania stawki, a przeglądarka udostępnia wybraną wartość scoreAd() i funkcjom 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ą uruchamiane dla każdej reklamy zdefiniowanej w konfiguracji grupy zainteresowań i będą otrzymywać identyfikatory raportowania każdej reklamy. Funkcje raportowania kupującego i sprzedawcy będą uruchamiane tylko w przypadku zwycięskiej reklamy i będą otrzymywać identyfikatory raportowania zdefiniowane dla tej reklamy.

Gdy identyfikatory raportowania, których nie można wybrać, są używane w połączeniu z identyfikatorami raportowania, które można wybrać, ich działanie różni się od tego opisanego w poprzedniej sekcji. W przeciwieństwie do początkowego działania, w którym tożsamości na potrzeby raportowania, których nie można wybrać, były dostępne tylko w funkcjach raportowania, tożsamości na potrzeby raportowania, które można wybrać, umożliwiają udostępnianie tożsamości na potrzeby raportowania, których nie można wybrać, również w generateBid() i scoreAd().

Grupa zainteresowań

Pole identyfikatorów raportowania, które można wybrać – selectableBuyerAndSellerReportingIds – to tablica ciągów tekstowych zdefiniowanych przez kupującego w grupie zainteresowań na potrzeby reklamy. Oprócz identyfikatorów raportowania, które można wybrać, 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 kupującego

Jeśli w konfiguracji grupy zainteresowań zdefiniowano selectableBuyerAndSellerReportingIds, staje się on dostępny w 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 parametrze generateBid() i zwrócić wybrany identyfikator jako selectedBuyerAndSellerReportingId. Jeśli wybrana wartość nie znajduje się w tablicy selectableBuyerAndSellerReportingIds, stawka jest odrzucana. Jeśli w konfiguracji grupy zainteresowań zdefiniowano parametr selectableBuyerAndSellerReportingIds, a kupujący nie zwróci parametru selectedBuyerAndSellerReportingId z parametru generateBid(), identyfikatory raportowania powrócą do zachowania opisanego 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 wspólnie k-anonimowa z wartościami 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 tego sprawdzania co najmniej do I kwartału 2025 r.).

Ocena reklam sprzedawców

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

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

  // ...
}

Raportowanie przez sprzedawcę

W przypadku raportowania sprzedawcy wartość selectedBuyerAndSellerReportingId zwrócona przez kupującego z generateBid() staje się dostępna w reportResult() wraz z buyerAndSellerReportingId, jeśli została zdefiniowana w grupie zainteresowań.

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

Jeśli w konfiguracji grupy zainteresowań zdefiniowano selectableBuyerAndSellerReportingIds, a funkcja generateBid() zwróciła wartość selectedBuyerAndSellerReportingId, nie może ona wygrać aukcji, chyba że wartości selectedBuyerAndSellerReportingId i buyerAndSellerReportingId (jeśli występuje) są k-anonimowe 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.), a w przypadku tej stawki nie zostanie wykonana funkcja reportResult(). Jeśli więc funkcja reportResult() zostanie wywołana z wartością parametru selectedBuyerAndSellerReportingId, oznacza to, że identyfikatory raportowania przeszły test k-anonimowości i wszystkie zdefiniowane identyfikatory raportowania będą dostępne w funkcji reportResult().

Raporty kupujących

Jeśli w konfiguracji grupy zainteresowań zdefiniowano parametr selectableBuyerAndSellerReportingIds, a funkcja generateBid() zwróciła parametr selectedBuyerAndSellerReportingId, wszystkie identyfikatory raportowania zdefiniowane w konfiguracji grupy zainteresowań staną się dostępne. Pamiętaj, że podobnie jak w przypadku raportowania sprzedawcy, jeśli identyfikatory raportowania nie są k-anonimowe, nie mogą wygrać aukcji i reportWin() nie będzie działać w przypadku tej stawki.

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

  // ...
}

Zastąp reguły

Poniżej podsumowujemy reguły 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óry z tych elementów: selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId czy nazwa grupy zainteresowań, zostanie przekazany do reportWin(), zależy od przeglądarki. Stosuje ona następującą logikę:

• Jeśli w odpowiedzi na żądanie stawki zwrócona zostanie wartość selectedBuyerAndSellerReportingId, na potrzeby raportowania dostępne będą wartości selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jeśli jest zdefiniowana w grupie zainteresowań) i buyerReportingId (jeśli jest zdefiniowana w grupie zainteresowań).
• W przeciwnym razie, jeśli w grupie zainteresowań zdefiniowano buyerAndSellerReportingId, na potrzeby raportowania dostępny jest tylko ten identyfikator.buyerAndSellerReportingId
• W przeciwnym razie, jeśli w grupie zainteresowań zdefiniowano buyerReportingId, na potrzeby raportowania dostępny jest tylko ten identyfikator.buyerReportingId
• W przeciwnym razie do raportowania dostępna jest tylko grupa zainteresowań name.

W tabeli poniżej opisano zachowanie związane z zastępowaniem:

Angażowanie się i przesyłanie opinii

• Więcej informacji o identyfikatorach na potrzeby raportowania znajdziesz w sekcji dotyczącej identyfikatorów na potrzeby raportowania w wyjaśnieniu dotyczącym Protected Audience.
• GitHub zadawaj pytania i śledź dyskusje w sekcji „Issues” w repozytorium interfejsu API.
• W3C: omów przypadki użycia w branży podczas rozmowy WICG.
• Ogłoszenia: dołącz do listy adresowej lub ją wyświetl.
• Pomoc dla deweloperów w zakresie Piaskownicy prywatności: zadawaj pytania i bierz udział w dyskusjach w repozytorium pomocy dla deweloperów w zakresie Piaskownicy prywatności.
• Chromium zgłoś błąd w Chromium, aby zadać pytania dotyczące implementacji dostępnej do testowania w Chrome.