Identyfikatory raportowania

Dowiedz się, jak działają identyfikatory raportowania w aukcji Protected Audience

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ą podawane przez kupującego w konfiguracji grupy zainteresowań i stają się dostępne w 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ą zgłaszanie identyfikatora reklamy, a także umożliwiają stosowanie takich przypadków użycia jak oferty.

Istnieją 3 rodzaje identyfikatorów raportowania:

• Identyfikatory raportowania, których nie można wybrać
  • buyerReportingId (ciąg znaków)
  • buyerAndSellerReportingId (ciąg znaków)
• Identyfikatory raportów do wyboru:
  • selectableBuyerAndSellerReportingIds (tabelka tekstowa)

Identyfikatory raportowania działają inaczej w zależności od tego, czy są to identyfikatory raportowania, które można wybrać. 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().

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

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 nie używasz funkcji raportowania z możliwością wyboru identyfikatorów raportowania, funkcja raportowania dla kupującego otrzymuje wartość buyerReportingId lub buyerAndSellerReportingId w zależności od zachowania zastępowania, a funkcja raportowania dla sprzedawcy – 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 sprzedawcy

W fazie raportowania dotyczącej 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 to funkcja k-anonimizacji, funkcja reportResult() nadal będzie działać, ale wartość identyfikatora raportowania nie będzie dostępna w ramach tej funkcji.

Raporty o kupujących

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

• Jeśli zdefiniowane są zarówno właściwości buyerAndSellerReportingId, jak i buyerReportingId, to buyerAndSellerReportingId zastąpi buyerReportingId, a wartość buyerAndSellerReportingId będzie dostępna w ramach reportWin().
• Jeśli zdefiniowana jest tylko opcja buyerReportingId, dostępna będzie opcja buyerReportingId.
• Jeśli nie zdefiniowano właściwości buyerAndSellerReportingId ani buyerReportingId, dostępna będzie właściwość 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 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 pierwszego kwartału 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.

Zdefiniowana jest tylko właściwość buyerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowana jest tylko wartość 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 reportWin() stanie się dostępna dla reportWin(), buyerReportingId jest sprawdzana pod kątem 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 kwartału 2025 r.).

Zdefiniowany jest tylko buyerAndSellerReportingId

Jeśli w konfiguracji grupy zainteresowań zdefiniowana jest tylko wartość 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 reportWin() stanie się dostępna dla reportWin(), buyerAndSellerReportingId jest sprawdzana pod kątem 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 kwartału 2025 r.).

Zdefiniowane są obie wartości: 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 tym przypadku w elementach reportWin() jest dostępny tylko element buyerAndSellerReportingId, ponieważ zachowanie zastępowania:

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

Zanim reportWin() stanie się dostępna dla reportWin(), buyerAndSellerReportingId jest sprawdzana pod kątem 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 kwartału 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 k-anonimowości przez właściciela grupy zainteresowań, adres URL skryptu ustalania stawek, adres URL renderowania i rozmiar reklamy (rozmiar reklamy jest wykluczony z tej kontroli co najmniej do I kwartału 2025 r.).

Identyfikatory raportowania do wyboru

Wybierane identyfikatory raportowania umożliwiają kupującemu wybór 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 otrzymywać identyfikatory raportowania dla każdej reklamy. 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.

Gdy identyfikatory raportowania, których nie można wybrać, są używane razem z identyfikatorami raportowania, których można wybrać, 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().

Grupa zainteresowań

Pole „selectable reporting ids” (wybierane identyfikatory raportowania) – selectableBuyerAndSellerReportingIds – to tablica ciągów znaków zdefiniowanych przez kupującego w grupie zainteresowań 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 przez 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(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 jest odrzucana, 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 na potrzeby raportowania powrócą do zachowania opisanego w sekcji Identyfikatory na potrzeby raportowania – niemożliwość wyboru.

Oferta z wartością zwracaną dla selectedbuyerAndSellerReportingId może wygrać aukcję tylko wtedy, gdy wartość selectedbuyerAndSellerReportingId jest wspólnie k-anonimowa wraz 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 do co najmniej I kwartala 2025 r.).

Ocenianie reklam sprzedawców

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 ona wygrać aukcji, chyba że 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 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 sprawdzenie k-anonimowości, a wszystkie zdefiniowane identyfikatory raportowania będą dostępne w funkcji selectedBuyerAndSellerReportingId.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ędą wyświetlane w ramach 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óra z wartości selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId lub nazwa grupy zainteresowań zostanie przekazana do atrybutu reportWin(), jest określana przez przeglądarkę według tej logiki:

• Jeśli z stawki zwracana jest wartość selectedBuyerAndSellerReportingId, 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ń zdefiniowana jest wartość buyerAndSellerReportingId, na potrzeby 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 do celów raportowania dostępna jest tylko grupa zainteresowań name.

W tabeli poniżej opisano zachowanie podczas zastępowania:

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 obserwuj dyskusje w problemach w repozytorium interfejsu API.
• W3C: omawiaj przypadki użycia w branży podczas rozmowy z WICG.
• Ogłoszenia: dołącz do listy adresowej 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, którą można przetestować w Chrome.