Руководство разработчика API FLEDGE

Для кого эта статья?

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

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

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

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

На диаграмме ниже представлен обзор жизненного цикла FLEDGE:

Иллюстрация, дающая обзор каждого этапа жизненного цикла FLEDGE.
Жизненный цикл FLEDGE.

Как я могу попробовать Защищенную аудиторию?

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

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

В демонстрационном видеоролике объясняется, как работает демонстрационный код, и показано, как использовать Chrome DevTools для отладки защищенной аудитории.

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

Пробная версия Privacy Sandbox Relevance and Measurement Origin доступна в бета-версии Chrome 101.0.4951.26 и более поздних версиях для настольных компьютеров для API-интерфейсов Protected Audience, Topics и Attribution Reporting API.

Чтобы принять участие, зарегистрируйтесь для получения пробного токена Origin .

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

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

Предоставьте пробный токен для каждой страницы, на которой вы хотите запустить код API Protected Audience:

  • В качестве метатега в <head>:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • В качестве HTTP-заголовка:

    Origin-Trial: TOKEN_GOES_HERE

  • Предоставляя токен программно:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

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

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

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

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

  • Включив все API конфиденциальности рекламы в chrome://settings/adPrivacy
  • Путем установки флагов из командной строки.

Рендеринг рекламы в iframe или изолированных фреймах

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

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

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

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

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

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

Запуск Chromium с флагами объясняет, как устанавливать флаги при запуске Chrome и других браузеров на основе Chromium из командной строки. Полный список флагов защищенной аудитории доступен на странице Chromium Code Search .

Какие функции поддерживаются в последней версии Chrome?

Защищенная аудитория становится доступной с помощью флажков функций в Chromium в качестве первого эксперимента по тестированию следующих функций предложения Защищенная аудитория:

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

Объяснение API предоставляет более подробную информацию о поддержке функций и ограничениях.

Разрешения групп по интересам

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

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

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

Код службы «Ключ/значение защищенной аудитории» теперь доступен в репозитории Privacy Sandbox GitHub . Этот сервис могут использовать разработчики Chrome и Android. Чтобы узнать об обновлении статуса, ознакомьтесь с публикацией в блоге . Узнайте больше о службе «ключ/значение защищенной аудитории» в пояснении API и пояснении модели доверия .

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

Чтобы гарантировать, что у экосистемы будет достаточно времени для тестирования, мы не ожидаем, что потребуется использовать службы ключей/значений с открытым исходным кодом или TEE до тех пор, пока не произойдет прекращение поддержки сторонних файлов cookie. Мы предоставим разработчикам существенное уведомление о начале тестирования и внедрения до того, как произойдет этот переход.

Обнаружение поддержки функций

Прежде чем использовать 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 Protected Audience как владелец сайта или как отдельный пользователь.

Как сайты могут контролировать доступ?

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

Существует две политики разрешений Защищенной аудитории, которые можно настроить независимо:

  • join-ad-interest-group включает/отключает функцию добавления браузера в группы по интересам
  • run-ad-auction включает/отключает функцию запуска аукциона на устройстве.

Доступ к API защищенной аудитории можно полностью отключить в собственном контексте, указав следующую политику разрешений в заголовке ответа HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Вы можете отключить использование API в iframe, добавив следующий атрибут allow к элементу iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

Более подробная информация представлена ​​в разделе «Предлагаемая первая пробная версия разрешений для источника защищенной аудитории» .

Отказ пользователя

Пользователь может заблокировать доступ к API Protected Audience и другим функциям Privacy Sandbox, используя любой из следующих механизмов:

  • Отключите пробные версии Privacy Sandbox в настройках Chrome: Настройки > Безопасность и конфиденциальность > Privacy Sandbox . Это также доступно по адресу chrome://settings/adPrivacy .
  • Отключите сторонние файлы cookie в настройках Chrome: Настройки > Безопасность и конфиденциальность .
  • Установите для файлов cookie и других данных сайта значение «Блокировать сторонние файлы cookie» или «Блокировать все файлы cookie» в chrome://settings/cookies .
  • Используйте режим инкогнито.

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

Отладка рабочих модулей Защищенной аудитории

Начиная с Chrome Canary 98.0.4718.0, появилась возможность отладки рабочих модулей Защищенной аудитории в Chrome DevTools.

Первым шагом является установка точек останова с помощью новой категории на панели «Точки останова прослушивателя событий» на панели «Источники» .

Снимок экрана DevTools в Chrome Canary, на котором выделена панель «Точки останова прослушивателя событий» на панели «Источники». Начало фазы торгов для участников торгов выбрано в разделе «Рабочая таблица аукциона рекламы».

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

Сценарии интерактивных рабочихлетов также будут отображаться на панели «Потоки».

Снимок экрана DevTools в Chrome Canary, на котором выделена панель «Потоки» на панели «Источники» и показан текущий сценарий рабочего листа, который был приостановлен.

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

Наблюдайте за событиями защищенной аудитории

На панели приложений в Chrome DevTools вы можете наблюдать за группами интересов Защищенной аудитории и событиями аукционов.

Если вы посетите демонстрационный торговый сайт Защищенной аудитории в браузере с включенной Защищенной аудиторией, DevTools отобразит информацию о событии join .

Панель приложения DevTools в Chrome Canary, показывающая информацию о событии присоединения к группе по интересам Защищенной аудитории.

Теперь, если вы посетите демонстрационный сайт защищенной аудитории в браузере с включенной защищенной аудиторией, DevTools отобразит информацию о событиях bid и win .

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

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

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

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

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

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

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

Иллюстрация, показывающая человека, просматривающего сайт в браузере на своем ноутбуке. Код JavaScript joinAdInterestGroup() выполняется в браузере.

Раздел пояснений: Браузеры записывают группы по интересам

Платформа спроса (DSP) рекламодателя (или сам рекламодатель) вызывает navigator.joinAdInterestGroup() , чтобы попросить браузер добавить группу по интересам в список групп, членом которых является браузер. В этом примере группа называется custom-bikes , а владельцем является dsp.example . Владелец группы интересов (в данном случае DSP) будет покупателем на аукционе объявлений, описанном в шаге 4 . Членство в группе по интересам сохраняется в браузере на устройстве пользователя и не передается поставщику браузера или кому-либо еще.

joinAdInterestGroup() требует разрешения от:

  • Сайт, который посещают
  • Владелец группы по интересам

Например: malicious.example не должен иметь возможности вызывать joinAdInterestGroup() с dsp.example в качестве владельца без разрешения dsp.example .

Разрешение с посещаемого сайта

Тот же источник : по умолчанию неявно предоставляется разрешение на вызовы joinAdInterestGroup() из того же источника, что и посещаемый сайт, т. е. из того же источника, что и фрейм верхнего уровня текущей страницы. Сайты могут использовать директиву join-ad-interest-group заголовка политики разрешений защищенной аудитории, чтобы отключить вызовы joinAdInterestGroup() .

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

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

Разрешение владельца группы интересов предоставляется неявно путем вызова joinAdInterestGroup() из iframe с тем же источником, что и у владельца группы интересов. Например, iframe dsp.example может вызывать joinAdInterestGroup() для групп интересов, принадлежащих dsp.example .

Предлагается, чтобы joinAdInterestGroup() мог выполняться на странице или в iframe в домене владельца или делегироваться другим доменам, предоставленным с использованием списка по .well-known URL-адресу.

Использование navigator.joinAdInterestGroup()

Вот пример того, как можно использовать API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Объект interestGroup , передаваемый в функцию, должен иметь размер не более 50 КБ, иначе вызов завершится неудачей. Второй параметр определяет продолжительность группы интересов, ограниченную 30 днями. Последовательные вызовы перезаписывают ранее сохраненные значения.

Свойства группы по интересам

Свойство Необходимый Пример Роль
owner Необходимый 'https://dsp.example' Происхождение владельца группы интересов.
name Необходимый 'custom-bikes' Название группы интересов.
biddingLogicUrl ** Необязательный* 'https://dsp.example/bid/custom-bikes/bid.js' URL-адрес для выполнения ставок JavaScript в ворлете.
biddingWasmHelperUrl ** Необязательный* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL-адрес для кода WebAssembly, полученный из biddingLogicUrl .
dailyUpdateUrl ** Необязательный 'https://dsp.example/bid/custom-bikes/update' URL-адрес, который возвращает JSON для обновления атрибутов группы интересов. (См. Обновление группы интересов .)
trustedBiddingSignalsUrl ** Необязательный 'https://dsp.example/trusted/bidding-signals' Базовый URL-адрес для запросов «ключ-значение» на доверенный сервер участника торгов.
trustedBiddingSignalsKeys Необязательный ['key1', 'key2' ...] Ключи для запросов к доверенному серверу «ключ-значение».
userBiddingSignals Необязательный {...} Дополнительные метаданные, которые владелец может использовать во время торгов.
ads Необязательный* [bikeAd1, bikeAd2, bikeAd3] Объявления, которые могут быть показаны для этой группы интересов.
adComponents Необязательный [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Компоненты для рекламы, состоящие из нескольких частей .

* Все свойства являются необязательными, за исключением owner и name . Свойства biddingLogicUrl ads не являются обязательными, но необходимы для участия в аукционе. Могут быть варианты использования для создания группы по интересам без этих свойств: например, владелец группы по интересам может захотеть добавить браузер в группу по интересам для кампании, которая еще не запущена, или для какого-либо другого использования в будущем, или они возможно, временно исчерпал рекламный бюджет.

** URL-адреса biddingLogicUrl , biddingWasmHelperUrl , dailyUpdateUrl trustedBiddingSignalsUrl должны иметь то же происхождение, что и владелец. URL-адреса ads и adComponents не имеют такого ограничения.

Обновить атрибуты группы интересов

dailyUpdateUrl указывает веб-сервер, который возвращает JSON, определяющий свойства группы интересов, соответствующие объекту группы интересов, переданному в navigator.joinAdInterestGroup() . Это предоставляет владельцу группы механизм периодического обновления атрибутов группы интересов. В текущей реализации можно изменить следующие атрибуты:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Любое поле, не указанное в JSON, не будет перезаписано — обновляются только поля, указанные в JSON, тогда как вызов navigator.joinAdInterestGroup() перезаписывает любую существующую группу интересов.

Обновления выполняются с максимальной эффективностью и могут завершиться сбоем при следующих условиях:

  • Тайм-аут сетевого запроса (в настоящее время 30 секунд).
  • Другой сбой сети.
  • Ошибка синтаксического анализа JSON.

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

Обновления вручную

Обновления групп интересов, принадлежащих источнику текущего кадра, можно запустить вручную с помощью navigator.updateAdInterestGroups() . Ограничение скорости предотвращает слишком частое обновление обновлений: повторные вызовы navigator.updateAdInterestGroups() ничего не делают, пока не истечет период ограничения скорости (в настоящее время один день). Ограничение скорости сбрасывается, если navigator.joinAdInterestGroup() вызывается снова для того же owner и name группы интересов.

Автоматические обновления

Все группы интересов, загруженные на аукцион, обновляются автоматически после завершения аукциона с учетом тех же ограничений, что и при обновлении вручную. Для каждого владельца, участвующего в аукционе хотя бы с одной группой по интересам, navigator.updateAdInterestGroups() вызывается из iframe, происхождение которого соответствует этому владельцу.

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

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

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

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

Скрипт в biddingLogicUrl предоставленный владельцем группы интересов, должен включать функциюgenerateBid generateBid() . Когда продавец рекламного места вызывает navigator.runAdAuction() , функция generatedBid() вызывается один раз для каждой группы интересов, членом которой является браузер, если владелец группы интересов приглашен принять участие в торгах. Другими словами, generateBid() вызывается один раз для каждого объявления-кандидата. Продавец предоставляет свойство decisionLogicUrl в параметре конфигурации аукциона, передаваемом в navigator.runAdAuction() . Код по этому URL-адресу должен включать функцию scoreAd() , которая запускается для каждого участника аукциона, чтобы оценить каждую ставку, возвращаемую generateBid() .

Скрипт в biddingLogicUrl предоставленный покупателем рекламного места, должен включать функциюgenerateBid generateBid() . Эта функция вызывается один раз для каждого объявления-кандидата. runAdAuction() индивидуально проверяет каждое объявление, а также связанную с ним ставку и метаданные, а затем присваивает объявлению числовой показатель желательности.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() принимает следующие аргументы:

  • interestGroup
    Объект, передаваемый в функцию joinAdInterestGroup() покупателем рекламы. (Группу интересов можно обновить через dailyUpdateUrl .)

  • auctionSignals
    Свойство аргумента конфигурации аукциона , передаваемое в navigator.runAdAuction() продавцом рекламного пространства. Это предоставляет информацию о контексте страницы (например, размер объявления и идентификатор издателя), типе аукциона (первая цена или вторая цена) и другие метаданные.

  • perBuyerSignals
    Как и в случае с auctionSignals , свойство аргумента конфигурации аукциона передается в navigator.runAdAuction() продавцом. Это может обеспечить контекстуальные сигналы от сервера покупателя о странице, если продавец является поставщиком общих служб , который выполняет вызов ставок в реальном времени на серверы покупателей и передает ответ обратно, или если страница издателя напрямую связывается с сервером покупателя. Если да, то покупатель может захотеть проверить криптографическую подпись этих сигналов внутри методаgenerateBid() для защиты от подделки.

  • trustedBiddingSignals
    Объект, ключами которого trustedBiddingSignalsKeys для группы интересов и чьи значения возвращаются в trustedBiddingSignals .

  • browserSignals
    Объект, созданный браузером, который может включать в себя информацию о контексте страницы (например, hostname текущей страницы, которую в противном случае продавец мог бы подделать) и данные для самой группы интересов (например, запись о том, когда группа ранее выиграла аукцион, чтобы разрешить ограничение частоты показов на устройстве).

Объект browserSignals имеет следующие свойства:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Чтобы вычислить значение bid , код generateBid() может использовать свойства параметров функции. Например:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() возвращает объект с четырьмя свойствами:

  • ad
    Произвольные метаданные об объявлении, например информация, которую продавец ожидает узнать об этой ставке или рекламном креативе. Продавец](/privacy-sandbox/resources/glossary#ssp) использует эту информацию в своих объявлениях для аукционов и решений. Продавец использует эту информацию в своей логике аукциона и принятия решений.

  • bid
    Числовая ставка, которая будет участвовать в аукционе. Продавец должен иметь возможность сравнивать предложения разных покупателей, поэтому ставки должны быть в какой-либо единице, выбранной продавцом (например, «доллары США за тысячу»). Если ставка равна нулю или отрицательна, то эта группа интересов вообще не будет участвовать в аукционе продавца. С помощью этого механизма покупатель может реализовать любые правила рекламодателя относительно того, где может или не может появляться его реклама.

  • render
    URL-адрес или список URL-адресов, которые будут использоваться для показа объявления, если эта ставка выиграет аукцион. (См. раздел «Объявления, состоящие из нескольких частей» в пояснении API.) Значение должно соответствовать renderUrl одного из объявлений, определенных для группы интересов .

  • adComponents
    Необязательный список до 20 компонентов для объявлений, состоящих из нескольких частей , взятый из свойства adComponents аргумента группы интересов, передаваемого в navigator.joinAdInterestGroup() .

Просить браузер покинуть группу по интересам

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

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Если пользователь возвращается на сайт, который запросил браузер добавить группу интересов, владелец группы интересов может вызвать функцию navigator.leaveAdInterestGroup() чтобы запросить браузер удалить группу интересов. Код объявления также может вызывать эту функцию для своей группы интересов.

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

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

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

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

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

Раздел пояснений: Продавцы проводят аукционы на устройствах

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

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

Например:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() возвращает обещание, которое преобразуется в URN ( urn:uuid:<something> ), который представляет результат аукциона объявлений. Это может быть декодировано браузером только при передаче в изолированный фрейм для рендеринга: страница издателя не может проверить выигравшее объявление.

Сценарий decisionLogicUrl по одному рассматривает каждое отдельное объявление вместе со связанной с ним ставкой и метаданными, а затем присваивает ему числовой показатель желательности.

Свойства auctionConfig

Свойство Необходимый Пример Роль
seller Необходимый 'https://ssp.example' Происхождение продавца.
decisionLogicUrl Необходимый 'https://ssp.example/auction-decision-logic.js' URL-адрес JavaScript-файла аукциона.
trustedScoringSignalsUrl Необязательный 'https://ssp.example/scoring-signals' URL-адрес доверенного сервера продавца.
interestGroupBuyers* Необходимый ['https://dsp.example', 'https://buyer2.example', ...] Происхождение всех владельцев групп интересов попросили принять участие в аукционе.
auctionSignals Необязательный {...} Информация о продавце о контексте страницы, типе аукциона и т. д.
sellerSignals Необязательный {...} Информация на основе настроек издателя, запроса контекстной рекламы и т. д.
sellerTimeout Необязательный 100 Максимальное время выполнения (мс) скрипта scoreAd() продавца.
perBuyerSignals Необязательный {'https://dsp.example': {...},
'https://another-buyer.example': {...},
...}		 Контекстные сигналы о странице для каждого конкретного покупателя, со своего сервера.
perBuyerTimeouts Необязательный 50 Максимальное время выполнения (мс) сценариев generateBid() конкретного покупателя.
componentAuctions Необязательный [{'seller': 'https://www.some-other-ssp.com',
'decisionLogicUrl': ..., ...},
...]		 Дополнительные настройки для аукционов компонентов .

* Продавец может указать interestGroupBuyers: '*' чтобы разрешить участие в торгах всем группам интересов. Затем объявления принимаются или отклоняются на основе критериев, отличных от включения владельца группы по интересам. Например, продавец может проверить рекламные объявления на предмет соответствия его политике.

** additionalBids не поддерживаются в текущей реализации Защищенной аудитории. Дополнительную информацию можно найти в разделе «Участники аукциона» в пояснении по Защищенной аудитории.

Как отбираются объявления?

Код в decisionLogicUrl (свойство объекта конфигурации аукциона, передаваемое в runAdAuction() ) должен включать функцию scoreAd() . Это запускается один раз для каждого объявления, чтобы определить его желательность.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() принимает следующие аргументы:

  • adMetadata
    Произвольные метаданные, предоставленные покупателем.
  • bid
    Числовое значение ставки.
  • auctionConfig
    Объект конфигурации аукциона, переданный в navigator.runAdAuction() .
  • trustedScoringSignals
    Значения, полученные во время аукциона с доверенного сервера продавца, отражают мнение продавца об объявлении.
  • browserSignals
    Объект, созданный браузером, включающий информацию, известную браузеру и которую сценарий аукциона продавца может захотеть проверить:
{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

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

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

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

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

Во время аукциона рекламы продавец рекламного пространства может получить данные в реальном времени о конкретных рекламных объявлениях, отправив запрос к службе «ключ/значение», используя trustedScoringSignalsUrl аргумента конфигурации аукциона , переданное в navigator.runAdAuction() , вместе с ключами из Свойства 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() преобразуется в URN , который передается в изолированный фрейм для рендеринга, и сайт отображает выигравшее объявление.

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

Раздел пояснений: Отчеты на уровне событий (на данный момент)

Продавец сообщает результат

Раздел «Объяснитель»: Отчеты продавца по рендерингу

JavaScript продавца, предоставленный в decisionLogicUrl (который также предоставил scoreAd() ), может включать функцию reportResult() , чтобы сообщить об аукционном результате.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Аргументы, передаваемые этой функции:

  • auctionConfig
    Объект конфигурации аукциона, переданный на navigator.runAdAuction() .

  • browserSignals
    Объект, построенный браузером, предоставляющий информацию об аукционе. Например:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Возвращающаяся стоимость этой функции используется в качестве аргумента sellerSignals для функции Winning Bider's reportWin() .

Победная торговая торговля сообщает результат

Раздел «Объяснитель: отчетность покупателя по рендерингам и рекламным мероприятиям

JavaScript победителя (который также предоставил generateBid() ), может включать функцию reportWin() для сообщений о результате аукциона.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Аргументы, передаваемые этой функции:

  • auctionSignals и perBuyerSignals
    Те же значения, передаваемые generateBid() для победителя.
  • sellerSignals
    Возвращающаяся стоимость reportResult() , которая дает продавцу возможность передать информацию покупателю.

  • browserSignals
    Объект, построенный браузером, предоставляющий информацию об аукционе. Например: 

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Временная потери/выигрышная реализация отчетности

В Chrome есть два метода, которые временно доступны для аукционной отчетности:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Каждый из этих методов принимает один аргумент: URL -адрес для получения аукциона. Их можно называться несколько раз, как в scoreAd() , так и generateBid() , с различными аргументами URL.

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

Эти методы доступны по умолчанию в Chrome. Чтобы иметь возможность проверить методы, включите все APIS конфиденциальности AD в соответствии с chrome://settings/adPrivacy . Если вы запускаете Chrome с флагами командной строки, чтобы включить защищенную аудиторию, вам нужно явно включить методы, включив флаг BiddingAndScoringDebugReportingAPI . Если флаг не включен, методы все равно будут доступны, но ничего не сделают.

8. Сообщается об рекламе.

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

Сообщается о щелчке рекламы, отображаемой в огороженной кадре. Чтобы узнать больше о том, как это может сработать, см. Объявления о огороженных кадрах .


На приведенной ниже диаграмме на каждом этапе защищенной аудитории аукцион :

Иллюстрация, предоставляющая обзор каждого этапа защищенной аудитории аукциона


В чем разница между охраняемой аудиторией и падацией?

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

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

Усилия от повреждения - это предложение нового API для решения этого варианта использования, предлагая некоторые ключевые достижения конфиденциальности:

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

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

  • В Sparrow : Criteo предложил добавление модели услуг («Gatekeeper»), работающей в надежной среде исполнения (TEE) . Защищенная аудитория включает в себя более ограниченное использование футболок для поиска данных в реальном времени и агрегированной отчетности.
  • Предложения Nextroll Tern и Magnite Parrrot описали различные роли, которые покупатели и продавцы имели на аукционе на конструкции. Защищенная аудитория рекламная торговля/поток заседаний основан на этой работе.
  • RTB House , основанные на результатах и ​​на уровне продуктов , изменение модели анонимности и возможности персонализации аукциона на аукционе на кончике
  • Parakeet -это предложение Microsoft о рекламной службе, подобной Turtledove, которая полагается на прокси-сервер, работающий в футболке между браузером и поставщиками ADTech, для анонимизации запросов на рекламу и обеспечения конфиденциальности. Защищенная аудитория не приняла эту модель прокси. Мы привносим API JavaScript для Parakeet и защищенную аудиторию в соответствие с поддержкой будущей работы для дальнейшего объединения лучших функций обоих предложений.

Защищенная аудитория еще не мешает рекламной сети веб -сайта обучения, которая видит рекламу человека. Мы рассчитываем изменить API, чтобы стать более частным с течением времени.

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

Пользователи могут настроить свое участие в испытаниях на песочницу конфиденциальности в Chrome, включив или отключив настройку верхнего уровня в chrome://settings/adPrivacy . Во время первоначального тестирования люди смогут использовать эту настройку песочниц с конфиденциальностью высокого уровня, чтобы отказаться от защищенной аудитории. Chrome планирует разрешить пользователям видеть и управлять списком групп интересов, которые они были добавлены на веб -сайтах, которые они посетили. Как и в случае с самими технологиями Sandbox Conficate Sandbox, настройки пользователей могут развиваться с обратной связью от пользователей, регуляторов и других.

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

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



Задействовать и обмениваться обратной связью

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

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

Для ошибок и проблем с реализацией API защищенной аудитории в Chrome: * Просмотреть существующие проблемы, представленные для API. * Поднимите новый выпуск на crbug.com/new .

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

Узнать больше

Фото Рэя Хеннесси на Unsplash .