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

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

Обзор

Идентификаторы отчетов — это идентификаторы, связанные с объявлением, которые доступны для использования при создании ставок, их оценке и составлении отчетов. Идентификаторы отчетов предоставляются покупателем в конфигурации группы интересов, и они становятся доступными в 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 года).

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

Если в конфигурации группы интересов определен только 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-адресом отображения и размером объявления (размер объявления исключается из этой проверки до тех пор, пока по крайней мере Q1 2025), и reportResult() не будет выполнен для этой ставки. Таким образом, если reportResult() вызывается со значением selectedBuyerAndSellerReportingId , это означает, что идентификаторы отчетов прошли проверку k-анонимности, и все определенные идентификаторы отчетов будут доступны внутри reportResult() .

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

Если selectableBuyerAndSellerReportingIds был определен в конфигурации группы интересов, а selectedBuyerAndSellerReportingId был возвращен generateBid() , то все идентификаторы отчетности, которые были определены в конфигурации группы интересов, становятся доступными. Обратите внимание: как и в случае с отчетами продавцов, если идентификаторы отчетов не являются 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.