API защищенной аудитории: руководство для разработчиков

Руководство разработчика по аукционам рекламы на устройствах для ремаркетинга и пользовательских аудиторий без межсайтового отслеживания третьими лицами.

Для тех, кто впервые знаком с API защищенной аудитории, прочитайте обзор API защищенной аудитории , где приведено общее объяснение API.

Эта публикация написана для разработчиков и представляет собой техническое руководство по последней версии экспериментального API Protected Audience. Доступна демоверсия базового развертывания API Protected Audience, а также справочные материалы по API для покупателей и продавцов рекламы .

Статус реализации

Чтобы получать уведомления об изменениях статуса API, подпишитесь на рассылку для разработчиков .

Что такое API защищенной аудитории?

API Protected Audience — это API Privacy Sandbox , разработанный для ремаркетинга и создания индивидуальных аудиторий. Он разработан таким образом, что не позволяет третьим лицам отслеживать поведение пользователей на сайтах. API позволяет браузеру проводить аукционы на устройстве, чтобы выбирать релевантные объявления для веб-сайтов, которые пользователь посещал ранее.

Protected Audience API — первый эксперимент, реализованный в Chromium в рамках семейства предложений TURTLEDOVE .

Попробуйте API защищенной аудитории

Доступная ссылка API

Этот документ содержит обзор API Protected Audience. Если вам нужны конкретные методы и параметры API:

Вы также можете ознакомиться с рекомендациями по задержке аукциона объявлений Protected Audience API .

Демонстрация API защищенной аудитории

Пошаговое руководство по развертыванию API защищенной аудитории на сайтах рекламодателей и издателей доступно по адресу protected-audience-demo.web.app/ .

Посмотрите это сквозное развертывание, чтобы узнать, как работает демонстрационный код API Protected Audience и как использовать Chrome DevTools для отладки.

Протестируйте этот API

Вы можете протестировать API защищенной аудитории для одного пользователя в Chrome Beta 101.0.4951.26 и более поздних версиях на настольном компьютере:

Отображать рекламу в iframe или фреймах

Рекламу можно отображать в <iframe> или <fencedframe> , в зависимости от установленных флагов.

Чтобы использовать <fencedframe> для отображения рекламы:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Чтобы использовать <iframe> для отображения рекламы:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Включите флаг BiddingAndScoringDebugReportingAPI , чтобы включить временные методы отладки отчетов о проигрышах/выигрышах .

Поддерживаемые функции

Защищенный API аудитории, стоящий за флагами функций в Chromium, — это первый эксперимент по тестированию следующих функций защищенного API аудитории:

  • Группы интересов : хранятся в браузере вместе с соответствующими метаданными для настройки ставок и рендеринга рекламы.
  • Торги, проводимые покупателями на устройстве (DSP или рекламодателем) : на основе сохраненных групп интересов и сигналов от продавца.
  • Выбор рекламы на устройстве продавцом (SSP или издателем) : на основе аукционных ставок и метаданных покупателей.
  • Рендеринг рекламы во временно облегченной версии Fenced Frames : с доступом к сети и ведением журнала, разрешенными для рендеринга рекламы.

Подробнее о поддержке функций и ограничениях читайте в объяснении API защищенной аудитории .

Разрешения для групп интересов

По умолчанию в текущей реализации API защищенной аудитории разрешен вызов joinAdInterestGroup() из любой точки страницы, даже из кросс-доменных фреймов.

В будущем, как только владельцы сайтов успеют обновить политики разрешений для междоменных фреймов, планируется запретить вызовы из междоменных фреймов.

Служба «ключ/значение»

Для поддержки аукциона рекламы через API Protected Audience браузер может обратиться к сервису «ключ/значение» для получения информации в режиме реального времени, которая поддерживает аукцион рекламы через API Protected Audience. Эту информацию можно использовать несколькими способами:

  • Покупатели могут захотеть рассчитать оставшийся бюджет рекламной кампании.
  • Продавцам может потребоваться проверять рекламные объявления на соответствие политике издателя.

Код сервиса «ключ/значение» для API Protected Audience теперь доступен. Следите за анонсом в блоге, чтобы узнать об обновлении статуса.

Для первоначального тестирования была представлена ​​модель « Принеси свой сервер ». В долгосрочной перспективе специалистам по рекламе потребуется использовать службы «ключ/значение» API Protected Audience с открытым исходным кодом, работающие в доверенных средах выполнения.

Следите за обновлениями графика в блоге, посвящённом 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 защищенной аудитории будут добавляться со временем, по мере продвижения работ по внедрению.

1. Пользователь посещает сайт рекламодателя.

Человек посещает сайт производителя кастомных велосипедов в браузере своего ноутбука.

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

2. Браузер пользователя просит добавить группу интересов.

Пользователь открывает браузер на ноутбуке и заходит на сайт. В браузере запущен JavaScript-код для присоединения к группам по интересам.

Платформа спроса рекламодателя (DSP) (или сам рекламодатель) вызывает navigator.joinAdInterestGroup() чтобы попросить браузер добавить группу интересов в список групп, членом которых является браузер.

В этом примере группа называется custom-bikes , а её владелец — dsp.example . Владелец группы интересов (в данном случае DSP) будет покупателем на аукционе рекламы через API защищенной аудитории. Информация о членстве в группе интересов хранится браузером на устройстве пользователя и не передается разработчику браузера или кому-либо ещё.

Укажите рекламу для группы интересов

Объекты ads и adComponents включают URL-адрес рекламного объявления и, при необходимости, произвольные метаданные, которые можно использовать во время торгов. Например:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

Как покупатели делают ставки?

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

Ознакомьтесь с документацией разработчика generatedBid() .

3. Пользователь посещает сайт, на котором продается рекламное место.

Человек заходит на новостной сайт в браузере на ноутбуке. На сайте есть пустое рекламное место.

Позже пользователь посещает сайт, продающий рекламное пространство, в данном случае — новостной сайт. На сайте есть рекламный инвентарь, который продаётся программно с использованием ставок в режиме реального времени.

4. В браузере запускается аукцион рекламы.

Пользователь просматривает новостной сайт в браузере на ноутбуке. Проводится аукцион рекламы через API защищенной аудитории, чтобы выбрать рекламное место для размещения.

Аукцион рекламы, скорее всего, будет проводиться поставщиком (SSP) издателя или самим издателем. Цель аукциона — выбрать наиболее подходящее объявление для одного доступного рекламного места на текущей странице. Аукцион учитывает группы интересов, к которым принадлежит браузер, а также данные покупателей и продавцов рекламного пространства из сервисов Key/Value .

5. Продавец и участвующие покупатели запрашивают данные в режиме реального времени из сервиса «Ключ/Значение».

Пользователь просматривает новостной сайт в браузере на своем ноутбуке. Проводится аукцион рекламы с использованием API защищенной аудитории, при этом участник получает данные из сервиса «ключ/значение».

Во время аукциона объявлений продавец может запросить данные в режиме реального времени о конкретных рекламных креативах, отправив запрос к своему сервису Key/Value . Продавец может запросить эту информацию во время runAdAuction() , используя свойство trustedScoringSignalsUrl , а также ключи из свойств renderUrl всех записей в полях ads и adComponents всех групп интересов, участвующих в аукционе.

Покупатель может запросить данные в режиме реального времени из своей службы Key/Value, используя свойства trustedBiddingSignalsUrl и trustedBiddingSignalsKeys аргумента группы интересов, переданного в navigator.joinAdInterestGroup() .

При вызове runAdAuction() браузер отправляет запрос к доверенному серверу каждого покупателя рекламы. URL-адрес запроса может выглядеть следующим образом:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • Базовый URL-адрес берется из trustedBiddingSignalsUrl .
  • hostname предоставляется браузером.
  • Значение keys берется из trustedBiddingSignalsKeys .

Ответом на этот запрос является JSON-объект, предоставляющий значения для каждого из ключей.

6. Победившее объявление отображается

Человек просматривает новостной сайт в браузере на ноутбуке. Реклама скидки 20% на велосипед отображается в защищенном огороженном пространстве.

Промис, возвращаемый функцией runAdAuction(), преобразуется в объект конфигурации огороженного фрейма ( FencedFrameConfig ), если флаг resolveToConfig в конфигурации аукциона установлен в true . Конфигурация фрейма используется огороженным фреймом для навигации к победившему объявлению, но URL-адрес объявления не виден для встраивания фрейма.

Объект конфигурации FencedFrameConfig доступен начиная с версии M114. Подробнее об объекте FencedFrameConfig см. в статье блога Chrome .

7. Результат аукциона объявляется.

Долгосрочный план заключается в том, чтобы разрешить браузеру сообщать результаты аукционов продавцу и покупателям с использованием API частного агрегирования .

В качестве временного механизма отчётности на уровне событий код, реализующий reportResult() для продавца и reportWin() для победителя торгов, может вызвать функцию sendReportTo() . Эта функция принимает один аргумент: строку, представляющую URL-адрес, который извлекается после завершения аукциона и кодирует информацию на уровне событий для отчётности.

8. Сообщается о клике по объявлению.

Пользователь нажимает на объявление о продаже велосипеда с рамой, встроенной в ограждение, на новостном сайте. Данные отчёта отправляются продавцу и покупателям.

Клик по объявлению, отображаемому в рамке, регистрируется. Подробнее о том, как это работает, см. в разделе «Отчёты по рекламе в рамке» .

Обзор каждого этапа аукциона рекламы Protected Audience API
На этой диаграмме показан каждый этап аукциона API защищенной аудитории.

В чем разница между API защищенной аудитории и TURTLEDOVE?

Protected Audience API — первый эксперимент, реализованный в Chromium в рамках семейства предложений TURTLEDOVE.

API защищенной аудитории следует общим принципам TURTLEDOVE. Некоторые виды онлайн-рекламы основаны на показе рекламы потенциально заинтересованному человеку, который ранее взаимодействовал с рекламодателем или рекламной сетью. Исторически это работало за счет того, что рекламодатель распознавал конкретного человека при просмотре им веб-сайтов, что является одним из основных требований конфиденциальности в современном Интернете.

Цель проекта TURTLEDOVE — предложить новый API для решения этой задачи, а также ряд важных усовершенствований в области конфиденциальности:

  • Информацию о том, что, по мнению рекламодателя, интересует человека, хранит браузер, а не рекламодатель.
  • Рекламодатели могут показывать рекламу на основе интересов, но не могут объединять эти интересы с другой информацией о человеке, в частности, с тем, кто он или какую страницу посещает.

API защищенной аудитории вырос из TURTLEDOVE и ряда связанных с ним предложений по модификациям, направленным на улучшение обслуживания разработчиков, которые будут использовать этот API:

  • В SPARROW : Criteo предложила добавить модель сервиса («Gatekeeper»), работающую в доверенной среде выполнения (TEE) . API защищенной аудитории включает более ограниченное использование TEE для поиска данных в режиме реального времени и агрегированной отчетности.
  • Предложения TERN от NextRoll и PARRROT от Magnite описывают различные роли покупателей и продавцов в аукционе на устройстве. Процесс назначения ставок и оценки рекламы в API Protected Audience основан на этой работе.
  • Модификации TURTLEDOVE, основанные на результатах и ​​на уровне продукта, от RTB House улучшили модель анонимности и возможности персонализации аукциона на устройстве.
  • PARAKEET — это предложение Microsoft по созданию рекламного сервиса, подобного TURTLEDOVE, который использует прокси-сервер, работающий в TEE между браузером и поставщиками рекламных технологий, для анонимизации рекламных запросов и обеспечения конфиденциальности. В API защищенной аудитории эта модель проксирования не реализована. Мы согласовываем API JavaScript для PARAKEET и API защищенной аудитории, чтобы обеспечить дальнейшее объединение лучших функций обоих предложений.

API Protected Audience пока не препятствует рекламной сети веб-сайта получать информацию о том, какую рекламу видит пользователь. Мы планируем со временем модифицировать API, сделав его более конфиденциальным.

Можно ли использовать API тем с API защищенной аудитории?

Да. Наблюдаемая тема для текущего пользователя, предоставляемая API тем , может использоваться продавцом или участником торгов в качестве контекстной информации. Тема может быть включена в следующие свойства:

  • auctionSignals — свойство объекта конфигурации аукциона, переданное в navigator.runAdAuction()
  • userBiddingSignals , свойство объекта конфигурации группы интересов, переданное в navigator.joinAdInterestGroup()

Доступная конфигурация браузера

Пользователи могут настроить свое участие в пробных версиях Privacy Sandbox в Chrome, включив или отключив настройку верхнего уровня в chrome://settings/adPrivacy .

В ходе первоначального тестирования пользователи смогут использовать эту высокоуровневую настройку Privacy Sandbox для отказа от API защищенной аудитории. Chrome планирует предоставить пользователям возможность просматривать и управлять списком групп интересов, в которые они добавлены на посещенных ими веб-сайтах. Как и сами технологии Privacy Sandbox, пользовательские настройки могут меняться с учетом отзывов пользователей, регулирующих органов и других лиц.

Мы продолжим обновлять доступные настройки в Chrome на основе тестов и отзывов . В будущем мы планируем предложить более детальные настройки для управления API защищенной аудитории и связанными с ней данными.

Вызывающие API не могут получить доступ к членству в группе, когда пользователи просматривают страницы в режиме инкогнито, а членство удаляется, когда пользователи очищают данные своего сайта.

Кэшируются ли ворклеты Protected Audience браузером?

Ресурсы, содержащие рабочие модули Protected Audience (рабочие модули генерации ставок и отчётности для покупателя, а также рабочие модули оценки и отчётности для продавца), кэшируются браузером. Для управления кэшированием можно использовать заголовок Cache-Control .

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

Получить поддержку

Чтобы задать вопросы и получить поддержку по вашей реализации, демонстрации или документации:

Если у вас есть более общие вопросы о том, как использовать API Protected Audience, сообщите об этом в репозитории API . Вы также можете обсудить варианты использования в отрасли в группе W3C по улучшению веб-рекламы .

Используйте форму обратной связи Privacy Sandbox, чтобы конфиденциально поделиться отзывом с командой Chrome за пределами публичных форумов.

Уклоняться

Хотите отказаться от API защищенной аудитории? Узнайте, как заблокировать доступ к API защищенной аудитории для владельца сайта или отдельного пользователя.

Получайте обновления