Узнайте, как определить аудиторию, создав группу по интересам с помощью API Protected Audience. Прочтите руководство для разработчиков , чтобы узнать о полном жизненном цикле API Protected Audience, а также обратитесь к объяснению API Protected Audience, чтобы получить подробное описание того, как браузеры записывают группы по интересам .
Не разработчик? См. обзор API Protected Audience .
Группы по интересам API защищенной аудитории
Группа интересов Protected Audience API представляет собой группу людей с общими интересами, соответствующую списку ремаркетинга . У каждой группы интересов Protected Audience API есть владелец .
Владельцы групп по интересам выступают в качестве покупателя на аукционе объявлений API Protected Audience. Членство в группе по интересам сохраняется в браузере на устройстве пользователя и не передается поставщику браузера или кому-либо еще.
API-функции
joinAdInterestGroup()
Платформа спроса рекламодателя (DSP) или сам рекламодатель вызывает navigator.joinAdInterestGroup()
чтобы попросить браузер добавить группу по интересам в список участников браузера.
Происхождение контекста вызова для joinAdInterestGroup()
должно совпадать с происхождением владельца группы интересов, поэтому joinAdInterestGroup()
необходимо будет вызывать из iframe (например, из DSP), если только происхождение владельца группы интересов не совпадает с происхождением текущий документ (например, сайт со своими группами по интересам).
joinAdInterestGroup()
требует разрешения от:
- Сайт, который посещают
- Владелец группы по интересам
Это означает, что malicious.example
не может вызвать joinAdInterestGroup()
для группы интересов, принадлежащей dsp.example.com
, без разрешения dsp.example.com
.
Разрешение с посещаемого сайта
Разрешение может быть предоставлено из одного и того же или перекрестного происхождения. По умолчанию разрешение предоставляется для вызовов joinAdInterestGroup()
из того же источника, что и посещаемый сайт (другими словами, из того же источника, что и фрейм верхнего уровня текущей страницы).
Пример использования
Вот пример того, как можно определить группу по интересам и попросить браузер присоединиться к группе.
const interestGroup = {
owner: 'https://dsp.example',
name: 'custom-bikes',
biddingLogicUrl: ...,
biddingWasmHelperUrl: ...,
updateUrl: ...,
trustedBiddingSignalsUrl: ...,
trustedBiddingSignalsKeys: ['key1', 'key2'],
userBiddingSignals: {...},
ads: [bikeAd1, bikeAd2, bikeAd3],
adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};
navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);
Объект interestGroup
, передаваемый в функцию, должен иметь размер не более 50 КБ, иначе вызов завершится неудачей. Второй параметр определяет продолжительность группы интересов, ограниченную 30 днями. Последовательные вызовы перезаписывают ранее сохраненные значения.
Обязательные свойства
Единственные обязательные свойства для групп интересов — это owner
и name
:
Свойство | Пример | Роль |
---|---|---|
owner | https://dsp.example | Происхождение владельца группы интересов. |
name | custom-bikes | Название группы интересов. |
Дополнительные свойства
Остальные свойства являются необязательными:
-
biddingLogicUrl
1 , 2 - Пример:
https://dsp.example/bid/custom-bikes/bid.js
- Роль: URL-адрес для выполнения ставок JavaScript в ворлете.
-
biddingWasmHelperUrl
1 , 2 - Пример:
https://dsp.example/bid/custom-bikes/bid.wasm
- Роль: URL-адрес для кода WebAssembly, полученный из
biddingLogicUrl
. -
updateUrl
2 - Пример:
https://dsp.example/bid/custom-bikes/update
- Роль: URL-адрес, который возвращает JSON для обновления атрибутов группы интересов. (См. Обновление данных об аудитории и обновление объявлений .)
-
trustedBiddingSignalsUrl
2 - Пример:
https://dsp.example/trusted/bidding-signals
- Роль: базовый URL-адрес для запросов «ключ-значение» к доверенной службе «ключ-значение» участника торгов.
-
trustedBiddingSignalsKeys
- Пример:
['key1', 'key2' ...]
- Роль: ключи для запросов к доверенной службе ключей/значений.
-
userBiddingSignals
- Пример:
{...}
- Роль: дополнительные метаданные, которые владелец может использовать во время торгов.
-
ads
1 - Пример:
[bikeAd1, bikeAd2, bikeAd3]
- Роль: объявления, которые могут отображаться для этой группы интересов.
-
adComponents
- Пример:
[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
- Роль: компоненты для рекламы, состоящие из нескольких частей .
1 Свойства biddingLogicUrl
ads
не являются обязательными, но необходимы для участия в аукционе. Могут быть варианты использования для создания группы по интересам без этих свойств: например, владелец группы по интересам может захотеть добавить браузер в группу по интересам для кампании, которая еще не запущена, или для какого-либо другого будущего использования, или они возможно, временно исчерпал рекламный бюджет.
2. В текущей реализации API защищенной аудитории biddingLogicUrl
, biddingWasmHelperUrl
, updateUrl
trustedBiddingSignalsUrl
должны иметь то же происхождение, что и владелец. Это не может быть долгосрочным ограничением, и URL-адреса ads
и adComponents
не имеют такого ограничения.
Укажите объявления для группы интересов
ads
и adComponents
включают URL-адрес рекламного объявления и, при необходимости, произвольные метаданные, которые можно использовать во время торгов.
Например:
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // optional
}
leaveAdInterestGroup()
Владелец группы по интересам может запросить удаление браузера из группы по интересам. Браузер удаляет группу по интересам из своего списка участников.
navigator.leaveAdInterestGroup({
owner: 'https://dsp.example',
name: 'custom-bikes'
});
Если пользователь возвращается на сайт, который запросил браузер добавить группу интересов, владелец группы интересов может вызвать функцию navigator.leaveAdInterestGroup()
чтобы запросить браузер удалить группу интересов.
Код объявления также может вызывать эту функцию для своей группы интересов.
Часто задаваемые вопросы
Каково максимальное количество групп по интересам на владельца группы для одного пользователя?
Chrome позволяет создавать до 1000 групп по интересам для каждого владельца и до 1000 владельцев групп по интересам. Эти ограничения предназначены для защиты от нарушений при обычной эксплуатации.
Как я могу максимизировать рекламу групп по интересам, соответствующую пороговым значениям 𝑘-anon?
Как отмечает публичный объяснитель , поскольку одна группа по интересам может предлагать несколько возможных рекламных объявлений, которые она может показывать, у группы будет возможность повторно назначить цену еще одной из своих реклам, чтобы она действовала в качестве «резервной рекламы» в любое время, когда она наиболее предпочтительна. выбор ниже порога. Это означает, что небольшое специализированное объявление, которое все еще находится ниже порога 𝑘-анонимности, все равно может принять участие в аукционах, и у его группы интересов есть возможность вернуться к более общему объявлению до тех пор, пока более специализированное объявление не наберет достаточно большую аудиторию. .
С тактической точки зрения вы можете рассмотреть следующее:
- Чтобы новое объявление начало показываться, просто начните делать ставки с его помощью в тех случаях, когда вы хотите, чтобы оно показывалось. Вам не нужно ничего дополнительно делать.
- У вас может быть резервное объявление, которое вы будете использовать, когда новые объявления не будут 𝑘-анон. Существует некоторый риск того, что ваше резервное объявление само по себе не будет 𝑘-анон, поэтому иногда вы можете подумать о том, чтобы просто назначить ставку с использованием резервного объявления. Возможно, делайте это в 1% случаев, например, если это хороший уровень, гарантирующий, что вы ожидаете, что откат останется выше порогового значения.
Недавно было некоторое обсуждение других способов работы, поэтому, если у вас есть какой-то вариант использования, для которого этот механизм может создать проблему, продолжайте публично обсуждать способы улучшения API.
Все ссылки на API защищенной аудитории
以下是 API 参考指南:
- Protected Audience API 开发者指南。
- 有关 Protected Audience 兴趣群体和出价生成的广告买方指南。
- Protected Audience 广告竞价广告卖方指南。
- 关于报告竞价结果的指南
- Protected Audience 广告竞价延迟时间方面的最佳实践
- 对 Protected Audience 进行问题排查
Protected Audience API 说明信息还详细介绍了功能支持和限制条件。