Переход на Reporting API v1

Доступна новая версия Reporting API. Это более конфиденциально и, скорее всего, будет поддерживаться во всех браузерах.

Maud Nalpas

Внимание: в этом посте рассказывается, как перейти на новую версию Reporting API (v1). Если вы новичок в API отчетов или вам нужны подробные примеры использования, вместо этого перейдите к основному посту об API отчетов .

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

Доступна новая версия Reporting API. Новый API более компактен и, скорее всего, будет поддерживаться во всех браузерах.

Примечание. Устаревший API Reporting API называется Reporting API v0 . Новый API отчетов называется Reporting API v1 .

Краткое содержание

Разработчики сайта

Если у вас уже есть функции отчетности для вашего сайта : перейдите на версию 1, используя новый заголовок ( Reporting-Endpoints ), но сохраните устаревший заголовок в течение некоторого времени ( Report-To ). См. раздел Миграция: пример кода .

Если вы только сейчас добавляете функцию отчетности на свой сайт : используйте только новый заголовок ( Reporting-Endpoints ).

⚠️ В обоих случаях обязательно установите заголовок Reporting-Endpoints для всех ответов, которые могут генерировать отчеты.

Разработчики сервиса отчетности

Если вы поддерживаете службу конечных точек или используете собственную, ожидайте увеличения трафика по мере перехода вас или внешних разработчиков на Reporting API v1 (заголовок Reporting-Endpoints ).

Продолжайте читать, чтобы узнать подробности и пример кода!

Регистрация сетевых ошибок

Внимание: если вы используете ведение журнала сетевых ошибок , продолжайте использовать Report-To (v0), поскольку ведение журнала сетевых ошибок не поддерживается в Reporting API v1.

Будет разработан новый механизм регистрации сетевых ошибок. Как только это станет доступно, переключитесь с Reporting API v0 на этот новый механизм.

Демо и код

• Демонстрационный сайт: новый API отчетности (v1)
• Код для демо-сайта

Различия между v0 и v1

Что меняется

• Поверхность API другая.

v0 (устаревшая версия)

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 использует заголовок Report-To для настройки именованных групп конечных точек , а директиву report-to в других заголовках для ссылки на эти группы конечных точек.

v1 (новый)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

Версия 1 использует заголовок Reporting-Endpoints для настройки именованных конечных точек . Как и v0, он использует директиву report-to в других заголовках для ссылки на эти группы конечных точек.

• Объем отчета иной.

v0 (устаревшая версия)

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

v1 (новый)

В версии 1 вам необходимо установить заголовок Reporting-Endpoints для всех ответов, которые могут генерировать отчеты.

• Оба API поддерживают одни и те же типы отчетов, за одним исключением: версия 1 не поддерживает отчеты об ошибках сети . Подробнее читайте в шагах миграции .
• v0 не поддерживается и не будет поддерживаться во всех браузерах. Версия 1, скорее всего, в будущем будет поддерживаться во многих браузерах.

Что остается неизменным

• Формат и структура отчетов не изменяются.
• Запрос, отправленный браузером в конечную точку, остается запросом POST Content-type application/reports+json .
• Сопоставление определенных конечных точек с определенными типами отчетов поддерживается как в версии 0, так и в версии 1.
• Роль конечной точки default не изменилась.

• Reporting API v1 не оказывает влияния на ReportingObserver . ReportingObserver продолжает получать доступ ко всем наблюдаемым отчетам, и их формат идентичен.

Все различия между v0 и v1

	Устаревший API отчетов (v0) Заголовок Report-To	Новый API отчетов (v1) Заголовок Reporting-Endpoints
Поддержка браузера	Chrome 69+ и Edge 69+.	Chrome 96+ и Edge 96+. Firefox поддерживает. Сафари не возражает. См. сигналы браузера .
Конечные точки	Отправляет отчеты любому из нескольких сборщиков отчетов (несколько URL-адресов, определенных для каждой группы конечных точек).	Отправляет отчеты определенным сборщикам отчетов (для каждой конечной точки определен только один URL-адрес).
поверхность API	Использует заголовок `Report-To` для настройки именованных групп конечных точек .	Использует заголовок `Reporting-Endpoints` для настройки именованных конечных точек .
Типы отчетов, которые можно создать с помощью этого API	Устаревание Вмешательство Крушение КООП/КОЭП Политика безопасности контента, уровень 3 (CSP, уровень 3) Регистрация сетевых ошибок (NEL) Подробнее о типах отчетов читайте в статье Reporting API .	Без изменений, за исключением журнала сетевых ошибок (NEL): это не поддерживается в новом API отчетов (v1) .
Область отчета	Источник. Заголовок документа Report-To влияет на другие документы (страницы) из этого источника. Поле url отчета по-прежнему варьируется в зависимости от документа.	Документ. Заголовок Reporting-Endpoints документа влияет только на этот документ. Поле url отчета по-прежнему варьируется в зависимости от документа.
Изоляция отчетов (пакетная обработка)	Различные документы (страницы) или сайты/источники, которые создают отчет примерно в одно и то же время и имеют одну и ту же конечную точку создания отчетов, будут объединены в пакет: они будут отправлены в одном сообщении в конечную точку отчетов.	Отчеты из разных документов (страниц) никогда не отправляются вместе. Даже если два документа (страницы) из одного источника одновременно создают отчет для одной и той же конечной точки, они не будут объединены в пакет. Это механизм для смягчения атак на конфиденциальность. Отчеты из одного документа (страницы) могут отправляться вместе.
Поддержка балансировки нагрузки/приоритетов	Да	Нет

Разработчики конечных точек: ожидайте большего трафика

Если вы настроили собственный сервер в качестве конечной точки отчетов или разрабатываете или поддерживаете сборщик отчетов как услугу, ожидайте большего трафика к этой конечной точке.

Это связано с тем, что отчеты не группируются с помощью Reporting API v1, как с Reporting API v0. Таким образом, по мере того, как разработчики приложений начнут мигрировать на Reporting API v1, количество отчетов останется прежним, но объем запросов к конечному серверу увеличится.

Разработчики приложений: переход на Reporting-Endpoints (v1)

Что вам следует делать?

Использование нового Reporting API (v1) имеет ряд преимуществ:

• Сигналы браузера положительные , что означает, что для версии 1 можно ожидать кросс-браузерной поддержки (в отличие от версии 0, которая поддерживается только в Chrome и Edge).
• API стал более компактным.
• Инструментарий разрабатывается на основе нового API отчетов (v1).

Имея это в виду:

• Если ваш сайт уже использует Reporting API v0 с заголовком Report-To , перейдите на Reporting API v1 (см. этапы миграции ). Если ваш сайт уже использует функцию отчетности о нарушениях Content-Security-Policy, проверьте конкретные шаги по переходу для отчетов CSP .
• Если на вашем сайте еще не используется Reporting API, но вы сейчас добавляете функции отчетности: используйте новый Reporting API (v1) (заголовок Reporting-Endpoints ). Есть одно исключение : если вам нужно использовать ведение журнала сетевых ошибок, используйте Report-To (v0). Ведение журнала сетевых ошибок в настоящее время не поддерживается в Reporting API v1. Будет разработан новый механизм регистрации сетевых ошибок. Пока он не станет доступен, используйте Reporting API v0. Если вам необходимо ведение журнала сетевых ошибок наряду с другими типами отчетов, используйте как Report-To (v0), так и Reporting-Endpoints (v1). Версия 0 обеспечивает ведение журнала сетевых ошибок, а версия 1 предоставляет отчеты всех других типов.

Этапы миграции

Ваша цель в этой миграции — не потерять отчеты, которые вы получали с помощью версии 0.

Примечание. Поскольку только Chrome и Edge поддерживают Reporting API v0, вам не нужно сосредотачиваться на других браузерах во время перехода на v1. Однако имейте в виду, что может появиться более широкая поддержка браузеров. На данный момент в этих браузерах нет ошибок отслеживания, но ситуация может измениться.

1. Шаг 1 (выполните сейчас) : используйте оба заголовка: Report-To (v0) и Reporting-Endpoints (v1).

   При этом вы получаете:

   • Отчеты от новых клиентов Chrome и Edge благодаря Reporting-Endpoints (v1).
   • Отчеты от старых клиентов Chrome и Edge благодаря Report-To (v0).

   Экземпляры браузера, поддерживающие Reporting-Endpoints будут использовать Reporting-Endpoints , а экземпляры, которые этого не поддерживают, будут использовать Report-To . Формат запроса и отчета одинаков для v0 и v1.

2. Шаг 2 (выполните сейчас). Убедитесь, что заголовок Reporting-Endpoints установлен во всех ответах, которые могут создавать отчеты.

   В версии 0 вы можете установить конечные точки отчетов только для некоторых ответов, а другие документы (страницы) в этом источнике будут использовать эту «окружающую» конечную точку. В версии 1 из-за разницы в области действия вам необходимо установить заголовок Reporting-Endpoints для всех ответов, которые могут генерировать отчеты.

3. Шаг 3 (начать позже). Как только все или большинство ваших пользователей обновятся до более поздних версий Chrome или Edge (96 и более поздних версий), удалите Report-To (v0) и оставьте только Reporting-Endpoints .

   Единственное исключение: если вам нужны отчеты о регистрации сетевых ошибок, сохраняйте Report-To до тех пор, пока не будет установлен новый механизм регистрации сетевых ошибок.

См. примеры кода в книге рецептов миграции .

Этапы миграции для отчетов CSP

Существует два способа настройки отчетов о нарушениях Content-Security-Policy :

• Только с заголовком CSP через директиву report-uri . Он имеет широкую поддержку браузеров Chrome, Firefox, Safari и Edge. Отчеты отправляются с типом контента application/csp-report и имеют формат, специфичный для CSP. Эти отчеты называются «Отчеты CSP уровня 2» и не зависят от API отчетов.
• С помощью Reporting API, то есть через заголовок Report-To (устаревший) или более новые Reporting-Endpoints (v1). Это поддерживается только в Chrome и Edge. Запросы отчетов имеют тот же формат, что и другие запросы API отчетов, и тот же тип контента application/reports+json .

Использование первого подхода (только report-uri ) больше не рекомендуется , а использование второго подхода имеет несколько преимуществ. В частности, он позволяет использовать единый способ настройки отчетов для всех типов отчетов, а также устанавливать общую конечную точку (поскольку все запросы отчетов, созданные через Reporting API⏤CSP и другие⏤, имеют одинаковый формат application/reports+json .

Однако лишь немногие браузеры поддерживают report-to . Таким образом, рекомендуется сохранять report-uri вместе с подходом Reporting API ( Report-To или лучше, Reporting-Endpoints ), чтобы получать отчеты о нарушениях CSP из нескольких браузеров. В браузере, который распознает report-uri и report-to , report-uri будет игнорироваться, если report-to присутствует. В браузере, который распознает только report-uri , будет учитываться только report-uri .

1. Шаг 1 (сделайте сейчас) : Если вы еще не добавили его, добавьте report-to рядом с report-uri . Браузеры, поддерживающие только report-uri (Firefox), будут использовать report-uri , а браузеры, которые также поддерживают report-to (Chrome, Edge), будут использовать report-to . Чтобы указать именованные конечные точки, которые вы будете использовать в report-to , используйте оба заголовка Report-To и Reporting-Endpoints . Это гарантирует, что вы будете получать отчеты как от старых, так и от новых клиентов Chrome и Edge.

2. Шаг 3 (начать позже). Как только все или большинство ваших пользователей обновятся до более поздних версий Chrome или Edge (96 и более поздних версий), удалите Report-To (v0) и оставьте только Reporting-Endpoints . Сохраните report-uri , чтобы получать отчеты только для браузеров, которые его поддерживают.

См. примеры кода для этих шагов в разделе «Миграция отчетов CSP» .

Миграция: пример кода

Обзор

Если вы используете устаревший API отчетов (v0) для получения отчетов о нарушениях для COOP (заголовок Cross-Origin-Opener-Policy ), COEP ( Cross-Origin-Embedder-Policy ) или политики документа (заголовок Document-Policy . ): вам не нужно изменять сами эти заголовки политики при переходе на Reporting API v1. Что вам действительно нужно, так это перейти от устаревшего заголовка Report-To к новому заголовку Reporting-Endpoints .

Если вы используете устаревший API отчетов (v0) для получения отчетов о нарушениях для CSP (заголовок Content-Security-Policy ), вам может потребоваться настроить Content-Security-Policy в рамках перехода на новый API отчетов ( v1).

Базовая миграция

Устаревший код (с v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Новый код (код перехода с v0 рядом с v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

Если на вашем сайте уже есть функция отчетности, оставляйте Report-To только временно (до тех пор, пока большинство клиентов Chrome и Edge не будут обновлены), чтобы не потерять отчеты.

Если вам требуется ведение журнала сетевых ошибок, сохраняйте Report-To до тех пор, пока не станет доступной замена журнала сетевых ошибок .

Новый код (только с версией 1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Вот как ваш код может выглядеть в будущем, когда большинство клиентов Chrome и Edge будут обновлены и начнут поддерживать API v1.

Обратите внимание, что с помощью версии 1 вы по-прежнему можете отправлять определенные типы отчетов на определенные конечные точки . Но у вас может быть только один URL-адрес для каждой конечной точки.

Просмотр всех страниц

Устаревший код (с v0), например с Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

С помощью версии 0 вы можете устанавливать конечные точки отчетов только для некоторых ответов. Другие документы (страницы) в этом источнике автоматически используют эти внешние конечные точки. Здесь конечные точки, установленные для "/" используются для всех ответов, например для page1 .

Новый код (с v1), например с Express

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

В версии 1 вам необходимо установить заголовок Reporting-Endpoints для всех ответов, которые могут генерировать отчеты.

Миграция отчетов CSP

Устаревший код, только с report-uri

Content-Security-Policy: ...; report-uri https://reports.example/main

Использование только report-uri больше не рекомендуется . Если ваш код выглядит так, как показано выше, выполните миграцию. См. примеры нового кода ниже (зеленым цветом).

Улучшенный устаревший код с report-uri и директивой report-to с заголовком Report-To (v0).

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Это лучше: этот код использует report-to, новую замену report-uri. Он по-прежнему сохраняет report-uri для обратной совместимости; некоторые браузеры не поддерживают report-to , но поддерживают report-uri .

Тем не менее, это могло быть лучше: этот код использует Reporting API v0 (заголовок Report-To ). Перейдите на версию 1: см. примеры «Нового кода» ниже (отмечены зеленым).

Новый код с report-uri и директивой report-to с заголовком Reporting-Endpoints (v1).

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Сохраняйте директиву report-uri вместе с директивой report-to до тех пор, пока директива report-to не будет поддерживаться во всех браузерах. См. таблицу совместимости браузеров .

Временно оставьте Report-To рядом с Reporting-Endpoints . Как только большинство посетителей Chrome и Edge обновятся до версий браузера 96+, удалите Report-To .

Дальнейшее чтение

• Мониторинг вашего веб-приложения с помощью Reporting API (основной пост об Reporting API)
• Спецификация: устаревший API отчетов (v0).
• Спецификация: новый API отчетов (v1).

Выражаем огромную благодарность Яну Клелланду, Эйдзи Китамуре и Милице Михайлии за их обзоры и предложения по этой статье.