Идентификаторы отчетов

Узнайте, как работают идентификаторы для отправки отчетов на аукционе защищенной аудитории.

Обзор

Идентификаторы отчетов — это идентификаторы, связанные с объявлением, которые можно использовать для генерации ставки, оценки ставки и составления отчетов. Идентификаторы отчетов предоставляются покупателем в конфигурации группы интересов и становятся доступными в generateBid() , scoreAd() , reportResult() и reportWin() при различных условиях, которые обсуждаются в этом руководстве.

Идентификаторы для отправки отчетов позволяют сообщать об идентификаторе объявления, а также использовать их в таких сценариях, как акции и предложения .

Существует три идентификатора для отчетности двух типов:

• Идентификаторы отчетов, которые нельзя выбрать
  • buyerReportingId (строка)
  • buyerAndSellerReportingId (строка)
• Выбираемые идентификаторы отчетов
  • selectableBuyerAndSellerReportingIds (массив строк)

Идентификаторы отчетов ведут себя по-разному в зависимости от того, используются ли выбираемые идентификаторы отчетов. Если используются только невыбираемые идентификаторы отчетов, то эти идентификаторы становятся доступны только внутри функций формирования отчетов. Если используются выбираемые идентификаторы отчетов, а также, при необходимости, невыбираемые идентификаторы отчетов, то все определенные идентификаторы становятся доступны также внутри generateBid() и scoreAd() .

Идентификаторы отчетов, которые нельзя выбрать

buyerReportingId и buyerAndSellerReportingId — это невыбираемые идентификаторы отчетов, определенные в конфигурации группы интересов, которые становятся доступными в функциях отчетности для покупателей и продавцов. Функции отчетности для покупателей и продавцов будут запускаться только для выигрышного объявления, и функции будут получать идентификаторы отчетов, определенные для этого выигрышного объявления.

При использовании без возможности выбора идентификаторов отчетов функция формирования отчетов для покупателей получает buyerReportingId или buyerAndSellerReportingId в зависимости от поведения перезаписи , а функция формирования отчетов для продавцов получает buyerAndSellerReportingId . Если ни buyerReportingId , ни buyerAndSellerReportingId не определены в конфигурации группы интересов, то функция reportWin() получает имя группы интересов ( interestGroupName ) выигравшей ставки.

Идентификаторы, которые нельзя выбрать, недоступны внутри generateBid() и scoreAd() если они не используются совместно с выбираемыми идентификаторами для отчетов.

Сообщения об идентификационных данных в группах по интересам

Идентификаторы для формирования отчетов определяются покупателем для каждого объявления в группе интересов:

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

Отчетность продавца

На этапе формирования отчетов продавцом значение buyerAndSellerReportingId становится доступным для reportResult() :

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

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

Прежде чем идентификатор станет доступен в функции reportResult() , он проверяется на k-анонимность по отношению к владельцу группы интересов, URL-адресу скрипта торгов, URL-адресу рендеринга и размеру объявления (размер объявления исключен из этой проверки как минимум до первого квартала 2025 года). Если он не является k-анонимным, функция reportResult() все равно будет выполнена, но значение идентификатора отчета не будет доступно внутри функции.

Отчет покупателя

На этапе формирования отчетов покупателями в ходе аукциона становится доступен один идентификатор отчета для функции reportWin() . Если в группе интересов определено более одного идентификатора отчета, применяется правило перезаписи, согласно которому buyerAndSellerReportingId перезаписывает buyerReportingId :

• Если переменные buyerAndSellerReportingId и buyerReportingId определены, то buyerAndSellerReportingId перезапишет buyerReportingId , и buyerAndSellerReportingId будет доступен внутри reportWin() .
• Если определен только buyerReportingId , то buyerReportingId будет доступен.
• Если buyerAndSellerReportingId и buyerReportingId не определены, то будет доступен interestGroupName .

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

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

Идентификатор отчета, который становится доступен внутри reportWin() , проверяется на k-анонимность с указанием владельца группы интересов, URL-адреса скрипта назначения ставок, URL-адреса рендеринга и размера объявления (размер объявления исключен из этой проверки как минимум до первого квартала 2025 года). Если проверка на k-анонимность не пройдена, функция reportWin() все равно будет запущена, но значение идентификатора отчета не будет доступно внутри функции.

Определен только buyerReportingId

Если в конфигурации группы интересов определен только buyerReportingId :

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

В этом случае buyerReportingId будет доступен внутри reportWin() :

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

Прежде чем стать доступным для reportWin() , проверяется анонимность идентификатора buyerReportingId по отношению к владельцу группы интересов, URL-адресу скрипта торгов, URL-адресу рендеринга и размеру объявления (размер объявления исключается из этой проверки как минимум до первого квартала 2025 года).

Определен только buyerAndSellerReportingId.

Если в конфигурации группы интересов определен только buyerAndSellerReportingId :

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

В этом случае buyerAndSellerReportingId будет доступен внутри reportWin() :

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

Перед тем как стать доступным для reportWin() , проверяется анонимность данных buyerAndSellerReportingId по отношению к владельцу группы интересов, URL-адресу скрипта торгов, URL-адресу рендеринга и размеру объявления (размер объявления исключается из этой проверки как минимум до первого квартала 2025 года).

Определены оба параметра: buyerAndSellerReportingId и buyerReportingId

Если в конфигурации группы интересов определены и buyerAndSellerReportingId , и buyerReportingId :

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

В этом случае внутри reportWin() будет доступен только buyerAndSellerReportingId из-за механизма перезаписи :

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

Перед тем как стать доступным для reportWin() , проверяется анонимность данных buyerAndSellerReportingId по отношению к владельцу группы интересов, URL-адресу скрипта торгов, URL-адресу рендеринга и размеру объявления (размер объявления исключается из этой проверки как минимум до первого квартала 2025 года).

Ни buyerAndSellerReportingId , ни buyerReportingId не определены.

Если ни один из идентификаторов отчетов не определен в конфигурации группы интересов:

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

В этом случае name группы интересов будет доступно внутри функции reportWin() :

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

Перед тем как стать доступным для функции reportWin() , имя группы интересов ( interestGroupName ) проверяется на k-анонимность с владельцем группы интересов, URL скрипта назначения ставок, URL рендеринга и размером объявления (размер объявления исключается из этой проверки как минимум до первого квартала 2025 года).

Выбираемые идентификаторы отчетов

Выбираемые идентификаторы отчетов позволяют покупателю выбрать идентификатор во время генерации ставок, и браузер предоставляет выбранное значение функциям scoreAd() и функциям формирования отчетов. Значение selectableBuyerAndSellerReportingIds , представляющее собой массив строк, передается функции generateBid() , и покупатель может вернуть один выбранный идентификатор в качестве selectedBuyerAndSellerReportingId .

Функции generateBid() и scoreAd() будут выполняться для каждого объявления, определенного в конфигурации группы интересов, и получать идентификаторы отчетов для каждого объявления. Функции отчетности для покупателей и продавцов будут выполняться только для объявления-победителя, и эти функции будут получать идентификаторы отчетов, определенные для этого объявления-победителя.

При использовании невыбираемых идентификаторов отчетов совместно с выбираемыми идентификаторами отчетов их поведение изменяется по сравнению с рабочим процессом, описанным в предыдущем разделе. В отличие от первоначального поведения невыбираемых идентификаторов отчетов, доступных только внутри функций формирования отчетов, выбираемые идентификаторы отчетов позволяют сделать невыбираемые идентификаторы отчетов доступными также внутри generateBid() и scoreAd() .

Группа по интересам

Поле «Выбираемые идентификаторы отчетов» — selectableBuyerAndSellerReportingIds — представляет собой массив строк, заданных покупателем в группе интересов для объявления. Наряду с выбираемыми идентификаторами отчетов можно также определить невыбираемые идентификаторы отчетов:

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

Формирование предложений покупателя

Если selectableBuyerAndSellerReportingIds был определен в конфигурации группы интересов, то он становится доступен внутри generateBid() вместе с другими определенными идентификаторами отчетов.

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

Покупатель может выбрать один из идентификаторов из массива selectableBuyerAndSellerReportingIds в generateBid() и вернуть выбранный идентификатор в качестве selectedBuyerAndSellerReportingId . Ставка отклоняется, если выбранное значение отсутствует в массиве selectableBuyerAndSellerReportingIds . Если selectableBuyerAndSellerReportingIds определен в конфигурации группы интересов, и покупатель не возвращает selectedBuyerAndSellerReportingId из generateBid() , то идентификаторы отчетов вернутся к поведению, описанному для невыбираемых идентификаторов отчетов .

Ставка с возвращаемым значением для selectedbuyerAndSellerReportingId может выиграть аукцион только в том случае, если значение selectedbuyerAndSellerReportingId является совместно k-анонимным с buyerAndSellerReportingId (если присутствует), buyerReportingId (если присутствует), владельцем группы интересов, URL скрипта торгов, URL рендеринга и размером объявления (размер объявления исключается из этой проверки как минимум до первого квартала 2025 года).

Оценка рекламных объявлений продавцов

Для продавца selectedBuyerAndSellerReportingId , возвращенное покупателем из generateBid() становится доступным в scoreAd() , наряду со buyerAndSellerReportingId , если оно было определено в конфигурации группы интересов.

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

  // ...
}

Отчетность продавца

Для формирования отчетов продавцами, значение selectedBuyerAndSellerReportingId , возвращенное покупателем из generateBid() становится доступным в reportResult() вместе со значением buyerAndSellerReportingId , если оно было определено в группе интересов.

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

Если в конфигурации группы интересов был определен selectableBuyerAndSellerReportingIds , и метод generateBid() вернул selectedBuyerAndSellerReportingId , то он не сможет выиграть аукцион, если selectedBuyerAndSellerReportingId и buyerAndSellerReportingId (если присутствует) не являются k-анонимными по отношению к владельцу группы интересов, URL-адресу скрипта торгов, URL-адресу рендеринга и размеру объявления (размер объявления исключен из этой проверки как минимум до первого квартала 2025 года), и reportResult() не будет выполнен для этой ставки. Следовательно, если reportResult() вызывается со значением для selectedBuyerAndSellerReportingId , это означает, что идентификаторы отчетов прошли проверку k-анонимности, и все определенные идентификаторы отчетов будут доступны внутри reportResult() .

Отчет покупателя

Если в конфигурации группы интересов был определен selectableBuyerAndSellerReportingIds , и метод generateBid() вернул selectedBuyerAndSellerReportingId , то становятся доступны все идентификаторы отчетов, определенные в конфигурации группы интересов. Обратите внимание, что, как и в случае с отчетами продавцов, если идентификаторы отчетов не являются k-анонимными, то они не могут выиграть аукцион, и reportWin() не будет выполняться для этой ставки.

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

  // ...
}

Перезаписать правила

Здесь мы суммируем правила перезаписи как для невыбираемых, так и для выбираемых идентификаторов отчетов. Какой из selectableBuyerAndSellerReportingIds идентификаторов отчетов BuyerAndSellerReportingIds, buyerAndSellerReportingId , buyerReportingId и имени группы интересов будет передан в reportWin() , определяется браузером по следующей логике:

• Если в результате рассмотрения заявки возвращается значение selectedBuyerAndSellerReportingId , то для формирования отчетов доступны значения selectedBuyerAndSellerReportingId , buyerAndSellerReportingId (если определено в группе интересов) и buyerReportingId (если определено в группе интересов).
• В противном случае, если в группе интересов определен buyerAndSellerReportingId , то для формирования отчетов будет доступен только buyerAndSellerReportingId .
• В противном случае, если в группе интересов определен buyerReportingId , то для формирования отчетов доступен только buyerReportingId .
• В противном случае для составления отчета доступно только name заинтересованной группы.

В следующей таблице описано поведение функции перезаписи:

Принимайте участие и делитесь отзывами.

• Чтобы узнать больше об идентификаторах для отправки отчетов, см. раздел «Идентификаторы для отправки отчетов» в пояснительной записке по защищенной аудитории .
• GitHub : Задавайте вопросы и следите за обсуждением в разделе Issues в репозитории API.
• W3C : Обсудите примеры применения в отрасли в рамках конференции WICG .
• Объявления : Подпишитесь на рассылку или просмотрите её.
• Поддержка разработчиков Privacy Sandbox : Задавайте вопросы и участвуйте в обсуждениях в репозитории поддержки разработчиков Privacy Sandbox.
• Chromium : Сообщите об ошибке в Chromium , чтобы задать вопросы о доступной для тестирования реализации в Chrome.