Доступна новая версия Reporting API. Это более конфиденциально и, скорее всего, будет поддерживаться во всех браузерах.
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
- Объем отчета иной.
С помощью версии 0 вы можете устанавливать конечные точки отчетов только для некоторых ответов. Другие документы (страницы) этого источника будут автоматически использовать эти внешние конечные точки.
В версии 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 |
| Без изменений, за исключением журнала сетевых ошибок (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.
Шаг 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.- Отчеты от новых клиентов Chrome и Edge благодаря
Шаг 2 (выполните сейчас). Убедитесь, что заголовок
Reporting-Endpoints
установлен во всех ответах, которые могут создавать отчеты.В версии 0 вы можете установить конечные точки отчетов только для некоторых ответов, а другие документы (страницы) в этом источнике будут использовать эту «окружающую» конечную точку. В версии 1 из-за разницы в области действия вам необходимо установить заголовок
Reporting-Endpoints
для всех ответов, которые могут генерировать отчеты.Шаг 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. Запросы отчетов имеют тот же формат, что и другие запросы 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 (сделайте сейчас) : Если вы еще не добавили его, добавьте
report-to
рядом сreport-uri
. Браузеры, поддерживающие толькоreport-uri
(Firefox), будут использоватьreport-uri
, а браузеры, которые также поддерживаютreport-to
(Chrome, Edge), будут использоватьreport-to
. Чтобы указать именованные конечные точки, которые вы будете использовать вreport-to
, используйте оба заголовкаReport-To
иReporting-Endpoints
. Это гарантирует, что вы будете получать отчеты как от старых, так и от новых клиентов Chrome и Edge.Шаг 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).
Выражаем огромную благодарность Яну Клелланду, Эйджи Китамуре и Милице Михайлии за их обзоры и предложения по этой статье.