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

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

Обновление: FLEDGE был переименован в API защищенной аудитории. Подробнее об изменении имени читайте в сообщении в блоге .

Ключевой момент: пробная версия исходной версии Privacy Sandbox Relevance and Measurement завершилась 20 сентября 2023 г., и теперь API-интерфейсы доступны для 99 % пользователей Chrome, а регистрация на пробную версию Origin завершена. Чтобы быть в курсе процентной доли пользователей, для которых включен каждый API, смотрите графики статуса Chrome .

Для тех, кто не знаком с 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/ .

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

Протестируйте этот 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 Protected Audience обсуждаются на регулярных собраниях WICG. На временной шкале Privacy Sandbox указаны сроки реализации API Protected Audience и других API Privacy Sandbox.

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

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

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

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

Предупреждение. Не все функции, описанные в этом посте, реализованы (или полностью реализованы) в версии API Protected Audience, которая в настоящее время тестируется в Chrome. Тест с флагами функций объясняет, какие функции API Protected Audience в настоящее время доступны для тестирования в Chrome, запускаемого из командной строки.

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

1. Пользователь заходит на сайт рекламодателя.

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

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

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

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

• Прочтите пояснение API Protected Audience : Браузеры записывают группы по интересам .
• Прочтите руководство по API : покупатели и DSP, узнайте, как joinAdInterestGroup() и генерировать ставки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ключевой момент: на начальном экспериментальном этапе тестирования API Protected Audience trustedBiddingSignalsUrl должен иметь то же происхождение, что и владелец группы интересов. Узнайте больше в статье «Как создать собственный сервер» .

6. Показывается победившее объявление.

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

Примечание. Объект FencedFrameConfig возвращается только в том случае, если в конфигурации аукциона для resolveToConfig установлено true . Если флаг не установлен или имеет значение false , будет возвращен непрозрачный URN , который можно отобразить только в iframe.

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

• Прочтите пояснение к API Protected Audience : браузеры отображают выигрышную рекламу

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

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

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

• Прочтите руководство по API : узнайте об отчетах о продавцах и покупателях.

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

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

---

На этой диаграмме показаны все этапы аукциона 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 для управления поведением кэширования.

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

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

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

• 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 . Вы можете активно участвовать или просто слушать!