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

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

Maud Nalpas

API отчетов предоставляет информацию об ошибках, возникающих на вашем сайте во время его использования посетителями. Он обеспечивает прозрачность в отношении вмешательств браузера, сбоев браузера, нарушений политики безопасности контента (Content-Security-Policy), нарушений COOP/COEP, предупреждений об устаревании и многого другого.

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

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

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

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

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

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

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

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

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

Журналирование сетевых ошибок

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

Демонстрация и код

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

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

Что меняется?

• Поверхность API отличается.

 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

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

• Объем отчета отличается.

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

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

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

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

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

Разработчики конечных устройств: ожидайте увеличения трафика.

Если вы настроили собственный сервер в качестве конечной точки для формирования отчетов, или если вы разрабатываете или поддерживаете сервис сбора отчетов, ожидайте увеличения трафика на эту конечную точку.

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

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

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

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

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

С учетом этого:

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

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

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

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

   В результате вы получаете:

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

   Экземпляры браузеров, поддерживающие 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

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

• С помощью одного только заголовка CSP, заданного директивой report-uri , обеспечивается широкая поддержка браузеров, включая Chrome, Firefox, Safari и Edge. Отчеты отправляются с типом содержимого application/csp-report и имеют формат, специфичный для CSP. Эти отчеты называются «отчетами CSP уровня 2» и не зависят от API отчетов.
• При использовании Reporting API это осуществляется через заголовок Report-To (устаревшая версия) или через более новую Reporting-Endpoints (v1). Поддерживается только в Chrome и Edge. Запросы на получение отчетов имеют тот же формат, что и другие запросы Reporting 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 ), вам не нужно изменять сами заголовки этих политик при переходе на API отчетов версии 1. Вам необходимо перейти с устаревшего заголовка Report-To на новый заголовок Reporting-Endpoints .

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

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

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

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" }] }

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

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

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

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

// 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(...)
});

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

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

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

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

Дополнительная информация

• Отслеживайте работу вашего веб-приложения с помощью API отчетов (основная статья об API отчетов).
• Спецификация: устаревший API для создания отчетов (версия 0)
• Спецификация: новый API для создания отчетов (версия 1)

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