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

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

Для тех, кто не знаком с API Protected Audience, прочтите обзор API Protected Audience , чтобы получить общее объяснение API.

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

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

如需接收有关 API 状态变更的通知，请加入开发者邮寄名单。

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

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

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

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

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

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

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

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

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

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

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

Вы можете протестировать API Protected Audience для одного пользователя в бета-версии Chrome 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 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. Пользователь заходит на сайт рекламодателя.

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

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

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

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

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

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

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

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

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

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

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

Прочтите документацию для разработчиковgeneratedBid generatedBid() .

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

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

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

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

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

Рекламный аукцион, скорее всего, будет проводиться поставщиком услуг издателя (SSP) или самим издателем. Цель аукциона — выбрать наиболее подходящее объявление для одного доступного рекламного места на текущей странице. В аукционе учитываются группы по интересам, членом которых является браузер, а также данные покупателей рекламного пространства и продавцов из сервисов «ключ-значение» .

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

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

Во время аукциона рекламы продавец может запросить данные о конкретных рекламных объявлениях в реальном времени, отправив запрос в свою службу «ключ-значение» . Продавец может запросить эту информацию во время 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-адрес объявления не виден специалисту по внедрению фрейма.

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

7. Сообщается результат аукциона.

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

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

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

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

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

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

В чем разница между 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 для управления поведением кэширования.

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

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

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

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

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

Уклоняться

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

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