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

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

Обзор

Идентификаторы отчётности — это идентификаторы, связанные с объявлением, которые можно использовать для формирования ставки, оценки ставки и составления отчётности. Идентификаторы отчётности предоставляются покупателем в конфигурации группы интересов и становятся доступны в 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 проверяется на k-анонимность с владельцем группы интересов, 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 проверяется на k-анонимность с владельцем группы интересов, 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 проверяется на k-анонимность с владельцем группы интересов, 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 , а selectedBuyerAndSellerReportingId был возвращён методом generateBid() , то он не сможет выиграть аукцион, если только 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 , buyerAndSellerReportingId , buyerReportingId и название группы интересов будут переданы в reportWin() определяется браузером с помощью следующей логики:

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

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

Привлекайте и делитесь отзывами

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