Руководство разработчика по аукционам рекламы на устройствах для обслуживания ремаркетинга и индивидуализированных аудиторий без межсайтового стороннего отслеживания.
Для тех, кто не знаком с API Protected Audience, прочтите обзор API Protected Audience , чтобы получить общее объяснение API.
Этот пост написан для разработчиков в качестве технического справочника по последней версии экспериментального API Protected Audience. Доступна демонстрация базового развертывания API защищенной аудитории, а также ссылки на API для покупателей и продавцов рекламы .
Статус реализации
- Предложение Protected Audience API теперь становится общедоступным . Задавайте вопросы и следите за обсуждением .
- Статус API Protected Audience для ожидающих возможностей подробно описывает изменения и улучшения API и функций API Protected Audience.
- Статус мигания
- Статус платформы Protected Audience API Chrome : относится к API Protected Audience в Chrome.
- Рекламный API Статус платформы Chrome : набор API для облегчения рекламы: API защищенной аудитории, темы, изолированные фреймы и отчеты об атрибуции.
Чтобы получать уведомления об изменении статуса API, присоединитесь к списку рассылки для разработчиков .
Что такое API защищенной аудитории?
API Protected Audience — это API-интерфейс Privacy Sandbox, предназначенный для обслуживания случаев использования ремаркетинга и индивидуальной аудитории, разработанный таким образом, чтобы его не могли использовать третьи стороны для отслеживания поведения пользователей на разных сайтах. API позволяет браузеру проводить аукционы на устройстве для выбора релевантной рекламы для веб-сайтов, которые пользователь ранее посещал.
API Protected Audience — это первый эксперимент, реализованный в Chromium в рамках семейства предложений TURTLEDOVE .
Попробуйте API защищенной аудитории
Доступная ссылка на API
Этот документ представляет собой обзор API защищенной аудитории. Если вы ищете конкретные методы и параметры API:
- Руководство для покупателей по
joinAdInterestGroup()
generateBid()
. - Руководство для продавца по API защищенной аудитории
runAdAuction()
- Руководство для покупателей по
reportWin()
и руководство для продавцов поreportResult()
- Устранение неполадок API защищенной аудитории
Вы также можете ознакомиться с рекомендациями по снижению задержки на аукционе объявлений API Protected Audience API .
Демонстрация API защищенной аудитории
Подробное описание базового развертывания API Protected Audience на сайтах рекламодателей и издателей доступно по адресу protected-audience-demo.web.app/ .
Протестируйте этот API
Вы можете протестировать API Protected Audience для одного пользователя в бета-версии Chrome 101.0.4951.26 и более поздних версиях на компьютере:
- Включите все API конфиденциальности рекламы в
chrome://settings/adPrivacy
. - Установите флаги из командной строки . Полный список доступных флагов API Protected Audience можно найти в поиске кода Chromium .
Рендеринг рекламы в iframe или изолированных фреймах
Объявления могут отображаться в <iframe>
или <fencedframe>
, в зависимости от того, какие флаги установлены.
Чтобы использовать <fencedframe>
для показа рекламы:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
Чтобы использовать <iframe>
для показа рекламы:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
Включите флаг BiddingAndScoringDebugReportingAPI
, чтобы включить временные методы отладки отчетов о потерях/выигрышах .
Поддерживаемые функции
API Protected Audience API с флагами функций в Chromium — это первый эксперимент по тестированию следующих функций API Protected Audience:
- Группы интересов : хранятся в браузере вместе с соответствующими метаданными для настройки ставок и отображения рекламы.
- Назначение ставок на устройстве покупателями (DSP или рекламодателем) : на основе сохраненных групп интересов и сигналов продавца.
- Выбор рекламы на устройстве продавцом (SSP или издателем) : на основе аукционных ставок и метаданных покупателей.
- Рендеринг рекламы во временно упрощенной версии Fenced Frames : для рендеринга рекламы разрешен доступ к сети и ведение журнала.
Подробнее о поддержке функций и ограничениях читайте в пояснении API Protected Audience .
Разрешения групп по интересам
По умолчанию текущая реализация API защищенной аудитории позволяет вызывать joinAdInterestGroup()
из любого места на странице, даже из междоменных iframe.
В будущем, как только у владельцев сайтов будет время обновить свои политики разрешений междоменных iframe, планируется запретить вызовы из междоменных iframe.
Служба ключей/значений
Для поддержки рекламного аукциона API Protected Audience браузер может получить доступ к службе «ключ-значение» для получения информации в реальном времени, которая поддерживает аукцион рекламы API Protected Audience. Эту информацию можно использовать несколькими способами:
- Покупатели могут захотеть рассчитать оставшийся бюджет рекламной кампании.
- От продавцов могут потребовать проверить рекламные объявления на соответствие политике издателя.
Код службы ключей и значений API Protected Audience теперь доступен. Чтобы узнать об обновлении статуса, ознакомьтесь с публикацией в блоге .
Для первоначального тестирования была представлена модель « Принеси свой собственный сервер ». В долгосрочной перспективе рекламным специалистам придется использовать службы «ключ/значение» Protected Audience API с открытым исходным кодом, работающие в доверенных средах выполнения.
Обновления временной шкалы см. в блоге служб API защищенной аудитории . Мы предоставим разработчикам существенное уведомление о начале тестирования и внедрения до того, как произойдет этот переход.
Обнаружение поддержки функций
Прежде чем использовать API, проверьте, поддерживается ли он браузером и доступен ли он в документе:
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
Как работает API защищенной аудитории?
В этом примере пользователь просматривает веб-сайт производителя кастомных велосипедов, затем посещает новостной веб-сайт и видит рекламу нового велосипеда от производителя велосипедов.
Функции API Protected Audience будут добавляться со временем по мере продвижения работы над реализацией.
1. Пользователь заходит на сайт рекламодателя.
![Человек посещает сайт производителя кастомных велосипедов в браузере на своем ноутбуке.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-visiting-custom-2ca7094e57259.png?authuser=8&hl=ru)
Представьте, что пользователь посещает веб-сайт производителя кастомных велосипедов (в этом примере рекламодателя) и проводит некоторое время на странице продукта, посвященного стальному велосипеду ручной работы. Это дает производителю велосипедов возможность ремаркетинга .
2. Браузеру пользователя предлагается добавить группу по интересам.
![Пользователь открывает браузер на своем ноутбуке и посещает сайт. В браузере выполняется код JavaScript для присоединения к группам по интересам.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-user-opens-browser-th-6c2a4e6d97af7.png?authuser=8&hl=ru)
Платформа спроса (DSP) рекламодателя (или сам рекламодатель) вызывает navigator.joinAdInterestGroup()
, чтобы попросить браузер добавить группу по интересам в список групп, членом которых является браузер.
В этом примере группа называется custom-bikes
, а владельцем является dsp.example
. Владелец группы интересов (в данном случае DSP) будет покупателем на рекламном аукционе API Protected Audience. Членство в группе по интересам сохраняется в браузере на устройстве пользователя и не передается поставщику браузера или кому-либо еще.
- Прочтите пояснение API Protected Audience : Браузеры записывают группы по интересам .
- Прочтите руководство по API : покупатели и DSP, узнайте, как
joinAdInterestGroup()
и генерировать ставки.
Укажите объявления для группы интересов
ads
и adComponents
включают URL-адрес рекламного объявления и, при необходимости, произвольные метаданные, которые можно использовать во время торгов. Например:
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // optional
}
Как покупатели делают ставки?
generateBid()
вызывается для каждой группы интересов, членом которой является браузер, — если владелец группы интересов приглашен принять участие в торгах.
Прочтите документацию для разработчиковgeneratedBid generatedBid()
.
3. Пользователь посещает сайт, продающий рекламное место.
![Человек посещает новостной сайт в браузере на своем ноутбуке. На сайте есть пустое рекламное место.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=8&hl=ru)
Позже пользователь посещает сайт, на котором продаются рекламные места, в данном примере новостной сайт. На сайте есть рекламные ресурсы, которые он продает программно с назначением ставок в реальном времени.
4. В браузере запускается аукцион рекламы.
![Человек просматривает новостной сайт в браузере на своем ноутбуке. Аукцион объявлений Protected Audience API запускается для выбора объявления для доступного рекламного места.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-views-news-webs-32cbfd93dc442.png?authuser=8&hl=ru)
Рекламный аукцион, скорее всего, будет проводиться поставщиком услуг издателя (SSP) или самим издателем. Цель аукциона — выбрать наиболее подходящее объявление для одного доступного рекламного места на текущей странице. В аукционе учитываются группы по интересам, членом которых является браузер, а также данные покупателей рекламного пространства и продавцов из сервисов «ключ-значение» .
- Прочтите объяснение API защищенной аудитории : Продавцы проводят аукционы на устройствах
- Прочтите руководство по API : продавцы могут узнать больше о
runAdAuction()
и лучших методах работы с задержкой на аукционе объявлений .
5. Продавец и участвующие покупатели запрашивают данные в режиме реального времени у службы «Ключ/Значение».
![Пользователь просматривает новостной сайт в браузере на своем ноутбуке. Проводится рекламный аукцион с использованием API Protected Audience, участник которого получает данные из службы «ключ-значение».](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=8&hl=ru)
Во время аукциона рекламы продавец может запросить данные о конкретных рекламных объявлениях в реальном времени, отправив запрос в свою службу «ключ-значение» . Продавец может запросить эту информацию во время runAdAuction()
с помощью trustedScoringSignalsUrl
, а также ключей из свойств renderUrl
всех записей в полях ads
и adComponents
всех групп интересов на аукционе.
Покупатель может запросить данные в реальном времени из своей службы ключей/значений, используя trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
аргумента группы интересов, переданного в navigator.joinAdInterestGroup()
.
При вызове runAdAuction()
браузер отправляет запрос на доверенный сервер каждого покупателя рекламы. URL-адрес запроса может выглядеть следующим образом:
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
- Базовый URL-адрес берется
trustedBiddingSignalsUrl
. -
hostname
предоставляется браузером. - Значение
keys
беретсяtrustedBiddingSignalsKeys
.
Ответом на этот запрос является объект JSON, предоставляющий значения для каждого из ключей.
- Прочтите объяснение API Protected Audience : Получение данных в реальном времени из службы ключей и значений API Protected Audience .
- Ознакомьтесь с открытым исходным кодом службы ключей и значений API Protected Audience .
6. Показывается победившее объявление.
![Человек просматривает новостной сайт в браузере на своем ноутбуке. Объявление о скидке 20 % на велосипед размещается в безопасном огороженном рамке.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=8&hl=ru)
Обещание, возвращаемое функцией runAdAuction(), преобразуется в объект конфигурации изолированного фрейма ( FencedFrameConfig
), когда в конфигурации аукциона resolveToConfig
установлено значение true
. Конфигурация фрейма используется изолированным фреймом для перехода к победившему объявлению, но URL-адрес объявления не виден специалисту по внедрению фрейма.
Объект конфигурации изолированного фрейма доступен, начиная с M114. Подробнее об объекте FencedFrameConfig
см. в статье блога Chrome .
- Прочтите пояснение к API Protected Audience : браузеры отображают выигрышную рекламу
7. Сообщается результат аукциона.
Долгосрочный план состоит в том, чтобы позволить браузеру сообщать о результатах аукциона для продавца и покупателя с помощью API частного агрегирования .
В качестве временного механизма отчетности на уровне событий код, реализующий reportResult()
для продавца и reportWin()
для победителя торгов, может вызывать функцию sendReportTo()
. Здесь принимается один аргумент: строка, представляющая URL-адрес, полученный после завершения аукциона, который кодирует информацию уровня события, подлежащую сообщению.
- Прочтите руководство по API : узнайте об отчетах о продавцах и покупателях.
8. Сообщается о клике по объявлению
![Человек нажимает на рекламу велосипеда, встроенного в огороженную раму, на новостном сайте. Данные отчета отправляются продавцу и покупателям.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/a-person-clicks-an-ad-a-be2111724646f.png?authuser=8&hl=ru)
Сообщается о клике по объявлению, отображаемому в огороженном фрейме. Подробнее о том, как это может работать, читайте в разделе «Отчеты по рекламе с ограниченными рамками» .
![Обзор каждого этапа рекламного аукциона API Protected Audience API](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/an-overview-each-stage-c8bac3c2c070f.png?authuser=8&hl=ru)
В чем разница между API защищенной аудитории и TURTLEDOVE?
API Protected Audience — это первый эксперимент, реализованный в Chromium в рамках семейства предложений TURTLEDOVE.
API Protected Audience соответствует принципам высокого уровня TURTLEDOVE. Некоторая онлайн-реклама основана на показе рекламы потенциально заинтересованному лицу, которое ранее взаимодействовало с рекламодателем или рекламной сетью. Исторически сложилось так, что рекламодатель узнавал конкретного человека при просмотре веб-сайтов, что является основной проблемой конфиденциальности в современной сети.
Усилия TURTLEDOVE направлены на предложение нового API для решения этого варианта использования, а также на некоторые ключевые улучшения конфиденциальности:
- Браузер, а не рекламодатель, хранит информацию о том, что, по мнению рекламодателя, интересует человека.
- Рекламодатели могут показывать рекламу на основе интересов, но не могут объединять этот интерес с другой информацией о человеке, в частности с тем, кто он или какую страницу посещает.
API Protected Audience вырос из TURTLEDOVE и набора связанных с ним предложений по модификациям, призванным лучше обслуживать разработчиков, которые будут использовать API:
- В SPARROW : Criteo предложила добавить модель сервиса («Gatekeeper»), работающую в доверенной среде выполнения (TEE) . API Protected Audience включает более ограниченное использование TEE для поиска данных в реальном времени и составления агрегированных отчетов.
- В предложениях TERN от NextRoll и PARRROT от Magnite описывались различные роли покупателей и продавцов на аукционе на устройствах. Процесс назначения ставок и оценки рекламы в API Protected Audience основан на этой работе.
- Модификации RTB House на основе результатов и на уровне продукта улучшили модель анонимности и возможности персонализации аукциона на устройстве.
- PARAKEET — это предложение Microsoft по созданию рекламной службы, подобной TURTLEDOVE, которая использует прокси-сервер, работающий в TEE между браузером и поставщиками рекламных технологий, для анонимизации рекламных запросов и обеспечения конфиденциальности. API Protected Audience не поддерживает эту модель прокси. Мы согласовываем API-интерфейсы JavaScript для PARAKEET и API-интерфейса Protected Audience для поддержки будущей работы по дальнейшему объединению лучших функций обоих предложений.
API Protected Audience пока не мешает рекламной сети веб-сайта узнавать, какую рекламу видит человек. Мы планируем со временем изменить API, чтобы он стал более конфиденциальным.
Можно ли использовать API тем с API защищенной аудитории?
Да. Наблюдаемая тема для текущего пользователя, предоставленная API тем , может использоваться продавцом или участником торгов в качестве контекстной информации. Тема может быть включена в следующие свойства:
-
auctionSignals
— свойство объекта конфигурации аукциона, передаваемое вnavigator.runAdAuction()
-
userBiddingSignals
— свойство объекта конфигурации группы интересов, передаваемое вnavigator.joinAdInterestGroup()
Доступная конфигурация браузера
Пользователи могут настроить свое участие в пробных версиях Privacy Sandbox в Chrome, включив или отключив настройку верхнего уровня в chrome://settings/adPrivacy
.
Во время первоначального тестирования люди смогут использовать этот параметр «Песочницы конфиденциальности» высокого уровня, чтобы отказаться от API Protected Audience. Chrome планирует предоставить пользователям возможность видеть и управлять списком групп по интересам, в которые они добавлены, на посещаемых ими веб-сайтах. Как и в случае с самими технологиями Privacy Sandbox, пользовательские настройки могут меняться с учетом отзывов пользователей, регулирующих органов и других лиц.
Мы продолжим обновлять доступные настройки Chrome на основе тестов и отзывов . В будущем мы планируем предложить более детальные настройки для управления API Protected Audience и связанными с ним данными.
Вызывающие API не могут получить доступ к членству в группе, когда пользователи просматривают данные в режиме инкогнито, а членство удаляется, когда пользователи очищают данные своего сайта.
Кэшируются ли рабочие листы Защищенной аудитории браузером?
Ресурсы, содержащие рабочие модули Защищенной аудитории (рабочие модули формирования ставок и отчетности покупателя, а также рабочие модули оценки рекламы и отчетности продавца), кэшируются браузером. Вы можете использовать заголовок Cache-Control
для управления поведением кэширования.
Привлекайте и делитесь отзывами
Получить поддержку
Чтобы задать вопросы и получить поддержку по вашей реализации, демо-версии или документации:
- GitHub : читайте пояснение , задавайте вопросы и следите за обсуждением .
- Демо : Поднимите проблему в репозитории демонстрационного кода .
- Поддержка разработчиков : задавайте вопросы и присоединяйтесь к обсуждениям в репозитории поддержки разработчиков Privacy Sandbox . Выберите шаблон проблемы для API Protected Audience.
- Реализация Chrome : если есть ошибки или проблемы с реализацией Chrome Protected Audience API, вы можете просмотреть существующие проблемы или поднять новую проблему .
Если у вас есть более общие вопросы об удовлетворении ваших потребностей с помощью API Protected Audience, сообщите о проблеме в репозитории API . Вы также можете обсудить примеры использования в отрасли в бизнес-группе улучшения веб-рекламы W3C.
Используйте форму обратной связи Privacy Sandbox, чтобы поделиться отзывами с командой Chrome в частном порядке за пределами общедоступных форумов.
Уклоняться
Хотите отказаться от API Protected Audience? Узнайте, как заблокировать доступ к API Protected Audience API для владельца сайта или отдельного пользователя.
Получайте обновления
- Чтобы получать уведомления об изменении статуса API, присоединяйтесь к списку рассылки для разработчиков .
- Чтобы внимательно следить за всеми текущими обсуждениями API, нажмите кнопку «Смотреть» на странице API на GitHub . Для этого вам необходимо иметь или создать учетную запись GitHub .
- Чтобы получать общие обновления Privacy Sandbox, подпишитесь на RSS-канал [Прогресс в Privacy Sandbox].
- Присоединяйтесь к запланированным вызовам API Protected Audience (каждые две недели). Присоединиться может каждый — чтобы принять участие, сначала убедитесь, что вы присоединились к WICG . Вы можете активно участвовать или просто слушать!