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

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

Maud Nalpas

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

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

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

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

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

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

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

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

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

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

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

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

Демо и код

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

Различия между 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 не поддерживается и не будет поддерживаться во всех браузерах. Версия 1, скорее всего, в будущем будет поддерживаться во многих браузерах.

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

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

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

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

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

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

Это связано с тем, что отчеты не группируются с помощью 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.

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).

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

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: ...

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

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

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

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

Maud Nalpas

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

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

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

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

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

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

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

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

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

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

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

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

Демо и код

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

Различия между 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 не поддерживается и не будет поддерживаться во всех браузерах. Версия 1, скорее всего, в будущем будет поддерживаться во многих браузерах.

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

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

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

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

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

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

Это связано с тем, что отчеты не группируются с помощью 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.

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).

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

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: ...

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

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

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