API отчётов

API отчётов предоставляет общий механизм создания отчётов для веб-приложений, который позволяет получать отчёты по различным функциям платформы (например, Политике безопасности контента, Политике разрешений или отчётам о устаревших функциях) согласованным способом.

На веб-платформе есть несколько различных функций и проблем, которые генерируют информацию, полезную разработчикам веб-приложений при поиске ошибок или улучшении веб-сайтов. Эта информация может включать:

• нарушения Политики безопасности контента.
• нарушения Политики разрешений.
• Использование устаревших функций (когда вы используете что-то, что скоро перестанет работать в браузерах).
• Возникновение сбоев.
• Возникновение вмешательств пользователя (когда браузер блокирует то, что пытается сделать ваш код, потому что это считается риском для безопасности, например, или просто раздражающим, как автоматическое воспроизведение аудио).

Цель API отчётов — предоставить согласованный механизм создания отчётов, который можно использовать для предоставления разработчикам такой информации в виде отчётов, представленных объектами JavaScript. В следующих разделах подробно описаны несколько способов его использования.

Для каждого уникального источника, для которого вы хотите получать отчёты, можно указать ряд «конечных точек», которые представляют собой именованные URL-адреса (или группы URL-адресов), которым пользовательский агент может отправлять отчёты. Сервер отчетов на этих конечных точках может собирать отчёты, обрабатывать и представлять их по мере необходимости вашим приложением.

Заголовок HTTP Reporting-Endpoints используется для указания деталей различных конечных точек, доступных пользовательскому агенту для отправки отчетов. Директива report-to может затем использоваться в определенных заголовках HTTP для указания конкретной конечной точки, которая будет использоваться для соответствующего отчета. Например, директива CSP report-to может использоваться в заголовках HTTP Content-Security-Policy или Content-Security-Policy-Report-Only для указания конечной точки, в которую должны отправляться отчёты о нарушениях CSP.

Сами отчёты отправляются в целевую конечную точку пользовательским агентом в операции POST с типом Content-Type application/reports+json. Это сериализация объектов Report, где type указывает тип отчета, url указывает источник отчета, а body содержит сериализацию API-интерфейса, соответствующего типу отчета. Например, отчёты о нарушениях CSP имеют type csp-violation и body, которая является сериализацией объекта CSPViolationReportBody.

Отчеты, отправленные на конечные точки, могут быть получены независимо от работы веб-сайтов, к которым они относятся, что полезно — например, сбой может привести к остановке веб-сайта и предотвратить выполнение чего-либо, но отчет всё равно можно получить, чтобы дать разработчику некоторые подсказки о том, почему это произошло.

Отчёты также можно получить с помощью объектов ReportingObserver, созданных с помощью JavaScript внутри веб-сайта, для которого вы хотите получить отчёты. Этот метод не такой надёжный, как отправка отчетов на сервер, потому что любой сбой страницы может помешать получению отчетов — но он проще в настройке и более гибкий.

Объект ReportingObserver создается с помощью конструктора ReportingObserver(), которому передаются два параметра:

• Функция обратного вызова с двумя параметрами — массив отчетов, доступных в очереди отчетов наблюдателя, и копия того же объекта ReportingObserver, что позволяет управлять наблюдением непосредственно изнутри обратного вызова. Обратный вызов выполняется при запуске наблюдения.
• Словарь параметров, позволяющий указать тип собираемых отчетов и следует ли наблюдать за отчетами, сгенерированными до создания наблюдателя (buffered: true).

Затем на наблюдателе доступны методы для начала сбора отчетов (ReportingObserver.observe()), получения отчетов, находящихся в очереди отчетов (ReportingObserver.takeRecords()) и отключения наблюдателя, чтобы он больше не мог собирать записи (ReportingObserver.disconnect()).

Отчеты, отправленные на конечные точки отчетов и наблюдателям отчетов, по сути, одинаковы: они имеют источник url, type, и body, который является экземпляром интерфейса, соответствующего этому типу. Единственное различие заключается в том, что серверные отчеты являются JSON-сериализациями объектов.

Сопоставление типов отчета type с body показано ниже.

Спецификация API отчетов также определяет расширение Generate Test Report для WebDriver, которое позволяет моделировать генерацию отчетов во время автоматизации. Отчеты, сгенерированные с помощью WebDriver, наблюдаются любыми зарегистрированными объектами ReportObserver, присутствующими на загруженном веб-сайте. Это пока не задокументировано.

DeprecationReportBody

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

InterventionReportBody

Содержит сведения об отчете об вмешательстве, который генерируется, когда запрос, сделанный веб-сайтом, был отклонен браузером; например, по соображениям безопасности.

Report

Объект, представляющий один отчет.

ReportingObserver

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

Эти интерфейсы определены в рамках спецификаций HTTP Политики безопасности контента (CSP):

CSPViolationReportBody

Содержит подробности о нарушении CSP.

SecurityPolicyViolationEvent

Представляет объект события securitypolicyviolation события, сгенерированного на элементе, документе или рабочем процессе, когда нарушается его политика CSP.

Эти заголовки HTTP определяют конечные точки, на которые отправляются отчеты.

Reporting-Endpoints

Устанавливает имя и URL-адрес конечных точек отчетов. Эти конечные точки могут использоваться в директиве report-to, которая может использоваться с несколькими заголовками HTTP, включая Content-Security-Policy и/или Content-Security-Policy-Report-Only.

Report-To Устаревшее

Устанавливает имя и URL-адрес групп конечных точек отчетов, которые могут использоваться с несколькими заголовками HTTP, включая Content-Security-Policy.

Конечные точки отчетов можно установить для следующих отчетов с помощью директивы report-to в соответствующих заголовках:

Нарушения CSP

report-to в Content-Security-Policy или Content-Security-Policy-Report-Only.

В нашем примере deprecation_report.html мы создаём простой наблюдатель отчётов, чтобы следить за использованием устаревших функций на нашей веб-странице:

const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reportBtn.onclick = () => displayReports(reports);
}, options);

Затем мы говорим ему начать наблюдение за отчётами, используя ReportingObserver.observe(); это говорит наблюдателю начать сбор отчётов в его очереди отчётов и выполнить функцию обратного вызова, указанную внутри конструктора:

observer.observe();

Позже в примере мы намеренно используем устаревшую версию MediaDevices.getUserMedia():

if (navigator.mozGetUserMedia) {
  navigator.mozGetUserMedia(constraints, success, failure);
} else {
  navigator.getUserMedia(constraints, success, failure);
}

Это приводит к генерации отчёта об устаревании; благодаря обработчику событий, который мы настроили внутри конструктора ReportingObserver(), мы теперь можем нажать кнопку, чтобы отобразить детали отчёта.

• Политика безопасности контента
• Permissions-Policy