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

Скрипт в biddingLogicUrl , предоставленный покупателем рекламного места, должен включать 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() продавцом. Это может предоставлять контекстуальные сигналы от сервера покупателя о странице, если продавец является SSP , который выполняет вызов ставки в реальном времени на серверы покупателей и передает ответ обратно, или если страница издателя напрямую связывается с сервером покупателя. Если да, то покупатель может захотеть проверить криптографическую подпись этих сигналов внутри метода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
    Произвольные метаданные об объявлении, например информация, которую продавец ожидает узнать об этой ставке или рекламном креативе. Продавец](/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 для функции 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. Чтобы иметь возможность протестировать эти методы, включите все API конфиденциальности рекламы в разделе chrome://settings/adPrivacy . Если вы используете Chrome с флагами командной строки для включения Защищенной аудитории, вам необходимо явно включить эти методы, включив флаг BiddingAndScoringDebugReportingAPI . Если флаг не включен, методы по-прежнему будут доступны, но ничего не будут делать.

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

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

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


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

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


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

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

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

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

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

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

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

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

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

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

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

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



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

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

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

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

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

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

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