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

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

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

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

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

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

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

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

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

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

Доступная справочная информация по API

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

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

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

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

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

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

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

Отображение рекламы во фреймах или фреймах с ограждением

Реклама может отображаться в <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() из любой точки страницы, даже из iframe-элементов, расположенных в разных доменах.

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

Сервис «Ключ/Значение»

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

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

Код сервиса API «Защищенная аудитория» (ключ/значение) теперь доступен. Следите за обновлениями в блоге, посвященном этому объявлению.

Для первоначального тестирования была внедрена модель " используйте собственный сервер ". В долгосрочной перспективе специалистам по рекламным технологиям потребуется использовать сервисы 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 для защищенной аудитории будет добавляться постепенно по мере продвижения работы над его внедрением.

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

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

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

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

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

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

В этом примере группа называется custom-bikes , а её владельцем является dsp.example . Владелец группы интересов (в данном случае, DSP) будет покупателем на аукционе рекламы Protected Audience 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 всех групп интересов в аукционе.

Покупатель может запросить данные в режиме реального времени из своего сервиса «Ключ/Значение», используя свойства 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. Сообщается о клике по рекламе.

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

Сообщается о клике по объявлению, отображаемому во фрейме. Подробнее о том, как это может работать, см. в разделе «Отчеты по объявлениям во фреймах» .

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

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

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

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

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

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

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

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

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

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

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

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

Доступные настройки браузера

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

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

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

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

Кэшируются ли в браузере рабочие модули для защищенной аудитории?

Ресурсы, содержащие рабочие модули для защищенной аудитории — рабочие модули генерации ставок и формирования отчетов для покупателей, а также рабочие модули оценки и формирования отчетов для продавцов — кэшируются браузером. Вы можете использовать заголовок Cache-Control для управления поведением кэширования.

Принимайте участие и делитесь отзывами.

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

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

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

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

Уклоняться

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

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