レポート API

概念と使い方

ウェブプラットフォームには、バグ修正や他の方法でウェブサイトを改善しようとするウェブ開発者にとって有用な情報を生み出す、さまざまな機能や問題が存在します。そのような情報には、次のようなものがあります。

• コンテンツセキュリティポリシー違反。
• 権限ポリシー違反。
• 一貫性ポリシー違反。
• Cross-Origin-Embedder-Policy 違反。
• 非推奨機能の使用（ブラウザーでまもなく動作しなくなる機能を使用している場合）。
• クラッシュの発生。
• ユーザーエージェントによる干渉の発生（セキュリティ上のリスクとみなされたためや、自動再生される音声のように単に煩わしいという理由で、ブラウザーがコードの動作をブロックする場合など）。

レポート API の目的は、開発者が JavaScript オブジェクトとして表現されたレポートの形で、こうした情報を利用できるようにするための、一貫性のあるレポート提供メカニズムを提供することです。

レポートは、JavaScript のレポートオブザーバーを介して取得するか、リモートサーバーのエンドポイントに送信することができます。 レポートの種類と、これら 2 つのレポート作成方法については、以下の節で詳しく説明します。

レポートの種類

レポートオブザーバーに送信されるレポートは、辞書オブジェクトのインスタンスです。 これらはすべて type、url、body プロパティを持ち、type はレポートの種類を示し、body はそのレポートの種類に固有のものです。

レポートエンドポイントに送信されるレポートは、基本的に同じものです。 唯一の違いは、サーバーレポートが、user_agent および age フィールドが追加されたオブジェクトの JSON シリアライズであるという点です。 以下の表には、文書化されているレポートの種類、それに対応するレポート辞書、および違反に関する注記が記載されています。 なお、JavaScript では観測できない crash レポート（観測元のページがクラッシュしているため）を除き、記載されているすべてのレポートはオブザーバーで確認可能であり、サーバーエンドポイントへ送信することができます。

これらの種類のリストは、ReportingObserver() コンストラクターに渡される options.types 引数にも記載されています。

レポートオブザーバー

レポートは、レポートの取得対象となるウェブサイト内で JavaScript によって作成された ReportingObserver オブジェクトを介して取得できます。 この方法は、サーバーへのレポート送信ほど確実ではありません。ページがクラッシュするとレポートの取得ができなくなる可能性があるためです。しかし、設定が簡単で、柔軟性が高いという利点があります。 ReportingObserver オブジェクトは、ReportingObserver() コンストラクターを使用して作成され、このコンストラクターには 2 つの引数が渡されます。

• 2 つの引数を取るコールバック関数。引数には、オブザーバーのレポートキューにあるレポートの配列と、同じ ReportingObserver オブジェクトのコピーが含まれます。これにより、コールバック内部から直接の監視制御が可能になります。このコールバックは、監視が開始されたときに実行されます。
• 収集するレポートの種類を指定したり、オブザーバーの作成前に生成されたレポートも監視対象とするかどうか (buffered: true) を設定できるオプション辞書。

その後、オブザーバー上でレポートの収集を開始するためのメソッド (ReportingObserver.observe())、レポートキューに現在あるレポートを取得するためのメソッド (ReportingObserver.takeRecords())、オブザーバーを切断してレコードの収集を停止するためのメソッド (ReportingObserver.disconnect()) が利用可能になります。

レポートサーバーのエンドポイント

レポートは、ユーザーエージェントによって、Content-Type を application/reports+json に設定した POST 操作を通じて、リモートのサーバーエンドポイントに送信することもできます。 これらは、それぞれのレポート型に対応する辞書のシリアライズ形式です。 たとえば、CSP 違反レポートは、CSPViolationReport オブジェクトのシリアライズデータです。

エンドポイントに送信されたレポートは、それに関連するウェブサイトの稼働状況とは無関係に取得することができます。これはとても有用です。例えば、クラッシュによってウェブサイトがダウンし、すべての処理が停止してしまった場合でも、レポートを取得することで、開発者は原因を特定するための手がかりを得ることができます。

HTTP の Reporting-Endpoints ヘッダーは、ユーザーエージェントがレポートを送信するために利用可能な、さまざまなエンドポイントの名前と URL を指定するために使用されます。 これにより、特定の HTTP レスポンスヘッダー内でエンドポイント（場合によっては複数のエンドポイント）を指定し、関連するレポートがどのエンドポイントに送信されるかを示すことができます。 crash、 deprecation、intervention レポートなど、関連する HTTP ヘッダーを持たないレポートタイプは、通常、"default" レポート送信エンドポイント にレポートを送信します（これは、Reporting-Endpoints ヘッダーを使用して指定された、"default" という名前のエンドポイントにすぎません）。

各レポート型のサーバーエンドポイントを指定する方法は、以下の通りです。

coep

• Cross-Origin-Embedder-Policy または Cross-Origin-Embedder-Policy-Report-Only の report-to 引数

csp-violation

• Content-Security-Policy または Content-Security-Policy-Report-Only の report-to ディレクティブ

integrity-violation

• Integrity-Policy または Integrity-Policy-Report-Only の endpoints フィールド

permissions-policy-violation

• Permissions-Policy または Permissions-Policy-Report-Only の report-to 引数
• "default" エンドポイント

crash

• crash-reporting エンドポイント
• default エンドポイント

deprecation

• default エンドポイント

intervention

• default エンドポイント

WebDriver によるレポートの生成

レポート API の仕様書では、テストレポートの生成の WebDriver 拡張機能も定義されています。これにより、自動化処理中にレポート生成をシミュレートすることができます。WebDriver を介して生成されたレポートは、読み込まれたウェブサイト内に存在する登録済みの ReportingObserver オブジェクトによって監視されます。この機能については、現時点ではまだドキュメント化されていません。

インターフェイス

CrashReportContext

現在の最上位の閲覧コンテキストについて、任意のデータを記録するためのメソッドを提供します。このデータは、ブラウザーがクラッシュした際に CrashReport に追加され、レポート送信先エンドポイントへ送信されます。

ReportingObserver

レポートが生成されるたびに、それを収集・参照するために使用できるオブジェクト。

関連インターフェイス

SecurityPolicyViolationEvent

要素、文書、ワーカーの CSP に違反があった際に、それらに対して発生する securitypolicyviolation イベントのイベントオブジェクトを表します。 これは、HTTP の コンテンツセキュリティポリシー (CSP) 仕様の一部として定義されています。

辞書

COEPViolationReport

Cross-Origin-Embedder-Policy (COEP) 違反の詳細を保持します。

CrashReport

ブラウザークラッシュの詳細を保持します。

CSPViolationReport

CSP 違反の詳細を保持します。 これは、HTTP のコンテンツセキュリティポリシー (CSP) 仕様の一部として定義されています。

DeprecationReport

そのウェブサイトが使用している、非推奨となったウェブプラットフォーム機能の詳細を保持します。

InterventionReport

ウェブサイトからのリクエストが、セキュリティ上の理由などでブラウザによって拒否された際に生成される、干渉レポートの詳細が含まれています。

IntegrityViolationReport

Integrity-Policy で要求されるサブリソースの整合性保証を満たしていないためにブロックされたリソース、または Integrity-Policy-Report-Only を使用して設定された report-only ポリシーによってブロックされるリソースに関する情報が含まれています。 これは、サブリソースの完全性仕様の一部として定義されています。

PermissionsPolicyViolationReport

Permissions-Policy 違反の詳細を保持します。

関連 HTTP ヘッダー

これらの HTTP レスポンスヘッダーは、レポートが送信されるエンドポイントを定義します。

Reporting-Endpoints

レポート用エンドポイントの名前と URL を設定します。 これらのエンドポイントは、report-to ディレクティブで使用できます。このディレクティブは、Content-Security-Policy や Content-Security-Policy-Report-Only を含む、さまざまな HTTP ヘッダーと組み合わせて使用できます。

Report-To

レポート API からは除外されましたが、一部のブラウザーはまだこれに対応しています。これは、レポートエンドポイントグループの名前と URL を設定するもので、特にReporting-Endpointsへの対応がまだ更新されていないネットワークエラーのロギングなど、いくつかの HTTP ヘッダーと組み合わせて使用される場合があります。その他のレポート API のレポートでは、将来的に確実に対応されるよう、代わりに Reporting-Endpoints を使用してください。

例

非推奨の機能のレポート

この例では、"deprecation" レポートを、ReportingObserver を使用して、そのレポートを報告するページ内で確認する方法を示しています。 なお、特定の HTTP ヘッダーの設定を必要とせず、MDN のライブサンプルとして実行できるため、ここでは "deprecation" レポートを表示するようにしています。

<pre id="log"></pre>

#log {
  height: 200px;
  margin: 10px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

まず、型が "deprecation" のレポートを監視するために、新しい ReportingObserver オブジェクトを作成し、レポートを受信してログに記録するコールバックを渡します。

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

const observer = new ReportingObserver((reports, observer) => {
  reports.forEach((report) => {
    log(JSON.stringify(report, null, 2));
  });
}, options);

// オブザーバーを起動
observer.observe();

次に、同期 XHR（非推奨の API）を使用する以下のコードを呼び出します。 なお、これはオブザーバーの後に定義されており、オブザーバーの実行中に一度起動されます。

const xhr = new XMLHttpRequest();
xhr.open("GET", "/", false); // false = 同期モード（非推奨）
xhr.send();

結果

非推奨レポートに対応しているブラウザーでは、下にレポートが表示されるはずです。 なお、type は "deprecation" であることに注意してください。

仕様書

ブラウザーの互換性

関連情報

• Content Security Policy
• Permissions-Policy