API ограждённых фреймов

API ограждённых фреймов предоставляет функциональность для управления содержимым, вставленным в <fencedframe> элементы.

Одним из основных источников проблем с приватностью и безопасностью в интернете является содержимое, встроенное в <iframe> элементы. Исторически <iframe> использовались для установки файлов cookie третьих сторон, которые могут использоваться для обмена информацией и отслеживания пользователей по разным сайтам. Кроме того, содержимое, встроенное в <iframe> может взаимодействовать с документом-вкладкой (например, с помощью Window.postMessage()).

Документ-вкладка также может использовать скриптинг для считывания различных видов информации из <iframe> — например, вы потенциально можете получить значительные данные для отслеживания/определения пользователя из считывания вложенного URL из свойства src, особенно если он содержит параметры URL. <iframe> также может получить доступ к DOM среды вставки, и наоборот.

Большинство современных браузеров работают над механизмами разделения хранилища, чтобы данные файлов cookie больше не использовались для отслеживания (например, см. Файлы cookie с независимым разнесённым состоянием (CHIPS) или Разделение состояний Firefox).

Элементы <fencedframe> направлены на решение другой части этой задачи — они очень похожи на <iframe> по форме и функциям, за исключением того, что:

• Обмен данными между содержимым фрейма <fencedframe> и сайтом-вкладкой невозможен.
• <fencedframe> может получать доступ к данным между сайтами, но только в очень специфических контролируемых условиях, которые сохраняют конфиденциальность пользователя.
• <fencedframe> нельзя свободно изменять или получать доступ к его данным через обычное скриптырование (например, считывание или установка URL источника). Содержимое <fencedframe> может быть вставлено только с помощью специальных API.
• <fencedframe> не может получить доступ к DOM среды вставки, так же как среда вставки не может получить доступ к DOM <fencedframe>.

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

<fencedframe> используются другими API для встраивания различных типов межсайтового содержимого или сбора данных, обеспечивая различные сценарии использования в соответствии с политикой конфиденциальности. Большинство из этих сценариев ранее полагались на cookie третьих сторон или другие механизмы, негативно влияющие на приватность.

• API Shared Storage предоставляет доступ к неразделенным межсайтовым данным в безопасной среде, вычисляя и/или отображая результаты в <fencedframe>. Например:
  • Рекламодатели могут измерять охват рекламы или показывать последующие объявления на основе того, какие объявления пользователи уже видели на других сайтах.
  • Разработчики могут проводить A/B-тестирование, показывая варианты пользователю на основе группы, к которой он принадлежит, или на основе того, сколько пользователей уже видели каждый вариант.
  • Компании могут персонализировать опыт пользователя на основе того, что он видел на других сайтах. Например, если он уже купил подписку, вы можете не показывать ему рекламу подписки на других ваших ресурсах.
• API Protected Audience позволяет разработчикам внедрять рекламу на основе интересов пользователей, в частности, для ремаркетинга и использования пользовательских аудиторий. Он может оценивать несколько ставок за рекламное место и отображать лучшее объявление в <fencedframe>.
• API Private Aggregation может собирать данные из <fencedframe> (полученные из shared storage или Protected Audience API) и создавать агрегированные отчёты.

Как упоминалось выше, вы не контролируете содержимое, встроенное в <fencedframe>, напрямую с помощью обычного скрипта.

Чтобы установить, какое содержимое будет показано в <fencedframe>, используемый API (например, Protected Audience или Shared Storage) генерирует объект FencedFrameConfig, который затем устанавливается с помощью JavaScript в качестве значения свойства HTMLFencedFrameElement.config <fencedframe>.

Следующий пример получает FencedFrameConfig из аукциона рекламы API Protected Audience, который затем используется для отображения выигрышного объявления в <fencedframe>:

const frameConfig = await navigator.runAdAuction({
  // ...auction configuration
  resolveToConfig: true,
});

const frame = document.createElement("fencedframe");
frame.config = frameConfig;

resolveToConfig: true должен быть передан в вызов runAdAuction() для получения объекта FencedFrameConfig. Если resolveToConfig установлено в false, результирующая Promise разрешится на неявный URN (например, urn:uuid:c36973b5-e5d9-de59-e4c4-364f137b3c7a), который может быть использован только в <iframe>.

В любом случае браузер сохраняет URL, содержащий целевое местоположение встраиваемого содержимого — сопоставленный с неявным URN или внутренним свойством FencedFrameConfig url. Значение URL не может быть прочитано JavaScript, выполняющимся в контексте вставки.

В документах, встроенных в <fencedframe> , JavaScript имеет доступ к свойству Window.fence, которое возвращает экземпляр Fence для этого документа. Этот объект содержит несколько функций, конкретно относящихся к функциональности API ограждённых фреймов. Например, Fence.reportEvent() предоставляет способ запуска отчёта о данных через маяк на один или несколько указанных URL-адресов для отчёта о просмотре и кликах рекламы.

Только конкретные функции, предназначенные для использования в <fencedframe> , могут быть включены с помощью политик разрешений, установленных на них; другие управляемые политикой функции недоступны в этом контексте. Дополнительные сведения см. в Политики разрешений для ограждённых фреймов.

Заголовок Sec-Fetch-Dest со значением fencedframe будет установлен для всех запросов, выполненных внутри <fencedframe>, включая вложенные <iframe> внутри <fencedframe>.

Sec-Fetch-Dest: fencedframe

Сервер должен установить заголовок ответа Supports-Loading-Mode со значением fenced-frame для любого документа, предназначенного для загрузки в <fencedframe>, или <iframe> вложенного внутри <fencedframe>.

Supports-Loading-Mode: fenced-frame

Другие эффекты фреймов с изолированной средой на HTTP-заголовках следующие:

• Подсказки пользовательского агента недоступны внутри фреймов с изолированной средой, так как они полагаются на делегирование политики разрешений, что может быть использовано для утечки данных.
• Строгие настройки Cross-Origin-Opener-Policy применяются к новым контекстам просмотра, открытым изнутри фреймов с изолированной средой, иначе они могут быть использованы для утечки информации в другие источники. Любое новое окно, открытое изнутри фрейма с изолированной средой, будет иметь rel="noopener" и Cross-Origin-Opener-Policy: same-origin установленные, чтобы гарантировать, что Window.opener возвращает null и размещает его в своей собственной группе контекстов просмотра.
• Content-Security-Policy: fenced-frame-src был добавлен для указания допустимых источников для вложенных контекстов просмотра, загружаемых в элементы <fencedframe>.
• Content-Security-Policy: sandbox настраиваемые параметры не могут быть унаследованы фреймами с изолированной средой, чтобы снизить риски нарушения конфиденциальности. Для загрузки фрейма с изолированной средой необходимо указать CSP без sandbox (что подразумевает значения ниже) или указать следующие значения sandbox:
  • allow-same-origin
  • allow-forms
  • allow-scripts
  • allow-popups
  • allow-popups-to-escape-sandbox
  • allow-top-navigation-by-user-activation

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

FencedFrameConfig

Представляет навигацию <fencedframe>, т.е. какой контент будет отображаться в нём. FencedFrameConfig возвращается из источника, такого как API защищённой аудитории, и устанавливается в качестве значения HTMLFencedFrameElement.config.

Fence

Содержит несколько функций, относящихся к функциональности фрейма с изолированной средой. Доступен только для документов, вложенных внутри <fencedframe>.

HTMLFencedFrameElement

Представляет элемент <fencedframe> в JavaScript и предоставляет свойства для его настройки.

Navigator.deprecatedReplaceInURN()

Заменяет указанные строки внутри отображаемого URL, соответствующего заданному неявным URN или внутреннему свойству FencedFrameConfig url.

Window.fence

Возвращает экземпляр объекта Fence для текущего контекста документа. Доступен только для документов, вложенных внутри <fencedframe>.

Некоторые функции API, создающие FencedFrameConfig, такие как Navigator.runAdAuction() (API защищённой аудитории) и WindowSharedStorage.selectURL() (API общего хранилища), а также другие функции, такие как Fence.reportEvent(), требуют регистрации вашего сайта в процессе регистрации песочницы конфиденциальности. Если этого не сделать, вызовы API завершатся с предупреждением в консоли.

В следующих демонстрациях используются <fencedframe>:

• Демонстрации API общего хранилища (которые также включают примеры API частной агрегации)
• Демонстрация API защищённой аудитории

• Фреймы с изолированной средой на developers.google.com
• Песочница конфиденциальности на developers.google.com