Reporting API の新しいバージョンが利用可能になりました。よりプライバシーが保護され、ブラウザ間でサポートされる可能性が高い。
Reporting API は、訪問者がサイトを使用する際に発生したエラーについて通知します。ブラウザによる介入、ブラウザのクラッシュ、Content-Security-Policy 違反、COOP/COEP 違反、非推奨に関する警告などを可視化できます。
Reporting API の新しいバージョンが利用可能になりました。新しい API はよりシンプルで、ブラウザ間でサポートされる可能性が高い。
概要
サイト デベロッパー
サイトにすでにレポート機能がある場合: 新しいヘッダー（Reporting-Endpoints）を使用して v1 に移行しますが、レガシー ヘッダーはしばらくそのままにしておきます（Report-To）。移行: コード例をご覧ください。
サイトにレポート機能を追加する場合: 新しいヘッダー（Reporting-Endpoints）のみを使用します。
⚠️ どちらの場合も、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定してください。
レポート サービスのデベロッパー
エンドポイント サービスを維持している場合や、独自のエンドポイント サービスを運用している場合、ご自身または外部デベロッパーが Reporting API v1（Reporting-Endpoints ヘッダー）に移行すると、トラフィックが増加します。
詳細とサンプルコードについては、以下をご覧ください。
ネットワーク エラーのロギング
ネットワーク エラーのロギングのための新しいメカニズムが開発されます。利用可能になったら、Reporting API v0 から新しいメカニズムに切り替えてください。
デモとコード
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
{0 は、Report-To ヘッダーを使用して名前付きエンドポイント グループを構成し、他のヘッダーの report-to ディレクティブを使用してこれらのエンドポイント グループを参照します。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
v1 では、Reporting-Endpoints ヘッダーを使用して名前付きエンドポイントを構成します。v0 と同様に、他のヘッダーで report-to ディレクティブを使用して、これらのエンドポイント グループを参照します。
- レポートのスコープが異なります。
v0 では、一部の回答にのみレポート エンドポイントを設定できます。そのオリジンの他のドキュメント（ページ）は、これらのアンビエント エンドポイントを自動的に使用します。
v1 では、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定する必要があります。
- どちらの API も同じレポートタイプをサポートしていますが、v1 はネットワーク エラー レポートをサポートしていません。詳しくは、移行手順をご覧ください。
- v0 はブラウザ間でサポートされていません。今後もサポートされる予定はありません。v1 は、今後複数のブラウザでサポートされる可能性が高いです。
変更されない点
- レポートの形式と構造は変更されません。
- ブラウザからエンドポイントに送信されるリクエストは、
Content-typeapplication/reports+jsonのPOSTリクエストのままです。 - 特定のエンドポイントを特定のレポートタイプにマッピングすることは、v0 と v1 の両方でサポートされています。
defaultエンドポイントのロールは変更されません。Reporting API v1 は
ReportingObserverに影響しません。ReportingObserverは引き続きすべてのオブザーバブル レポートにアクセスでき、形式は同じです。
v0 と v1 のすべての違い
以前の Reporting API（v0）Report-To ヘッダー |
新しい Reporting API（v1）Reporting-Endpoints ヘッダー |
|
|---|---|---|
| ブラウザ サポート | Chrome 69 以降、Edge 69 以降。 | Chrome 96 以降、Edge 96 以降。Firefox はサポートされています。Safari は異議を唱えません。ブラウザ シグナルをご覧ください。 |
| エンドポイント | レポートを複数のレポート コレクタ（エンドポイント グループごとに複数の URL が定義されている）のいずれかに送信します。 | レポートを特定のレポート コレクタに送信します（エンドポイントごとに定義できる URL は 1 つだけです）。 |
| API サーフェス | `Report-To` ヘッダーを使用して、名前付きエンドポイント グループを構成します。 |
`Reporting-Endpoints` ヘッダーを使用して、名前付きエンドポイントを構成します。 |
| この API で生成できるレポートの種類 |
|
ネットワーク エラー ロギング（NEL）: 新しい Reporting API（v1）ではサポートされていませんを除き、変更なし。 |
| レポートの対象 | 生成元に帰属するものとして扱うことを可能にする技術です。 ドキュメントの Report-To ヘッダーは、そのオリジンの他のドキュメント（ページ）に影響します。
レポートの url フィールドは引き続きドキュメントごとに異なります。 |
Document. ドキュメントの Reporting-Endpoints ヘッダーは、そのドキュメントにのみ影響します。
レポートの url フィールドは、引き続きドキュメントごとに異なります。 |
| レポートの分離（バッチ処理） | 同じレポート エンドポイントを持つ異なるドキュメント（ページ）またはサイト/オリジンが同じ時刻にレポートを生成した場合、それらはバッチにまとめられ、同じメッセージでレポート エンドポイントに送信されます。 |
|
| ロード バランシング / 優先度のサポート | はい | × |
エンドポイント デベロッパー: トラフィックの増加が見込まれる
独自のサーバーをレポート エンドポイントとして設定している場合や、レポート コレクタをサービスとして開発またはメンテナンスしている場合は、そのエンドポイントへのトラフィックがさらに増加します。
これは、Reporting API v0 とは異なり、Reporting API v1 ではレポートがバッチ処理されないためです。したがって、アプリケーション デベロッパーが Reporting API v1 への移行を開始すると、レポートの数は変わらないものの、エンドポイント サーバーへのリクエスト数は増加します。
アプリケーション デベロッパー: Reporting-Endpoints（v1）に移行する
どうすればよいですか。
新しい Reporting API（v1）には、次のようなメリットがあります。
- ブラウザ シグナルはポジティブです。つまり、v1 はクロスブラウザ サポートが期待できます（Chrome と Edge でのみサポートされる v0 とは異なります）。
- API がシンプルになりました。
- ツールは新しい Reporting API（v1）を中心に開発されています。
これを踏まえると以下のようになります。
- サイトですでに
Report-Toヘッダーを使用して Reporting API v0 を使用している場合は、Reporting API v1 に移行します（移行手順をご覧ください）。サイトですでに Content-Security-Policy 違反のレポート機能を使用している場合は、CSP レポートの移行手順をご確認ください。 - サイトで Reporting API を使用しておらず、レポート機能を追加する場合は、新しい Reporting API（v1）（
Reporting-Endpointsヘッダー）を使用します。これには 1 つの例外があります。ネットワーク エラー ロギングを使用する必要がある場合は、Report-To（v0）を使用します。現在、Reporting API v1 ではネットワーク エラー ロギングはサポートされていません。ネットワーク エラー ロギングの新しいメカニズムが開発されます。利用可能になるまでは、Reporting API v0 を使用してください。他のレポート タイプと併用してネットワーク エラー ロギングが必要な場合は、Report-To（v0）とReporting-Endpoints（v1）の両方を使用します。v0 はネットワーク エラー ロギングを提供し、v1 は他のすべてのタイプのレポートを提供します。
移行手順
この移行の目的は、v0 で取得していたレポートを失わないことです。
ステップ 1（今すぐ行う）:
Report-To（v0）とReporting-Endpoints（v1）の両方のヘッダーを使用します。これにより、次のことが可能になります。
Reporting-Endpoints（v1）により、新しい Chrome クライアントと Edge クライアントからの報告。Report-To（v0）が原因で、古い Chrome クライアントと Edge クライアントから報告が寄せられています。
Reporting-Endpointsをサポートするブラウザ インスタンスはReporting-Endpointsを使用し、サポートしていないインスタンスはReport-Toにフォールバックします。リクエストとレポートの形式は v0 と v1 で同じです。ステップ 2（今すぐ実施）: レポートが生成される可能性があるすべてのレスポンスで
Reporting-Endpointsヘッダーが設定されていることを確認します。v0 では、一部のレスポンスにのみレポート エンドポイントを設定し、そのオリジンの他のドキュメント（ページ）はこの「アンビエント」エンドポイントを使用するように選択できました。v1 では、スコープが異なるため、レポートを生成する可能性があるすべてのレスポンスに
Reporting-Endpointsヘッダーを設定する必要があります。ステップ 3（後で開始）: すべてのユーザーまたはほとんどのユーザーが、新しいバージョンの Chrome または Edge（96 以降）に更新したら、
Report-To（v0）を削除し、Reporting-Endpointsのみを残します。1 つの例外: ネットワーク エラー ロギング レポートが必要な場合は、ネットワーク エラー ロギング用の新しいメカニズムが確立されるまで
Report-Toを維持します。
移行に関するクックブックのコード例をご覧ください。
CSP レポートの移行手順
Content-Security-Policy 違反レポートを構成する方法は 2 つあります。
report-uriディレクティブを介して CSP ヘッダーのみを使用する。これは、Chrome、Firefox、Safari、Edge など、幅広いブラウザでサポートされています。レポートは content-typeapplication/csp-reportで送信され、CSP に固有の形式になります。これらのレポートは「CSP レベル 2 レポート」と呼ばれ、Reporting API に依存しません。- Reporting API では、
Report-Toヘッダー（従来版）または新しいReporting-Endpoints（v1）を使用します。これは Chrome と Edge でのみサポートされています。レポート リクエストの形式は、他の Reporting API リクエストと同じで、コンテンツ タイプはapplication/reports+jsonです。
最初の方法（report-uri のみ）の使用は推奨されなくなりました。2 つ目の方法にはいくつかのメリットがあります。特に、Reporting API を介して生成されるすべてのレポート リクエスト（CSP など）の形式が同じ application/reports+json であるため、すべてのレポート タイプのレポートを 1 つの方法で設定し、汎用エンドポイントを設定できます。
ただし、report-to をサポートしているのは一部ブラウザのみです。そのため、複数のブラウザから CSP 違反レポートを取得するには、Reporting API アプローチ（Report-To または Reporting-Endpoints）とともに report-uri を維持することをおすすめします。report-uri と report-to を認識するブラウザでは、report-to が存在する場合、report-uri は無視されます。report-uri のみを認識するブラウザでは、report-uri のみが考慮されます。
ステップ 1（今すぐ行う）: まだ追加していない場合は、
report-uriの横にreport-toを追加します。report-uriのみをサポートするブラウザ（Firefox）はreport-uriを使用し、report-toもサポートするブラウザ（Chrome、Edge）はreport-toを使用します。report-toで使用する名前付きエンドポイントを指定するには、ヘッダーReport-ToとReporting-Endpointsの両方を使用します。これにより、古い Chrome クライアントと新しい Chrome クライアント、古い Edge クライアントと新しい Edge クライアントの両方からレポートを受け取ることができます。ステップ 3（後で開始）: すべてのユーザーまたはほとんどのユーザーが、新しいバージョンの Chrome または Edge（96 以降）に更新したら、
Report-To（v0）を削除し、Reporting-Endpointsのみを残します。report-uriを保持すると、report-uriのみをサポートするブラウザのレポートも引き続き取得できます。
これらの手順のコード例については、CSP レポートの移行をご覧ください。
移行: コード例
概要
以前の Reporting API（v0）を使用して、COOP（Cross-Origin-Opener-Policy ヘッダー）、COEP（Cross-Origin-Embedder-Policy）、ドキュメント ポリシー（Document-Policy ヘッダー）の違反レポートを取得している場合: Reporting API v1 に移行する際に、これらのポリシー ヘッダー自体を変更する必要はありません。必要なのは、従来の Report-To ヘッダーから新しい Reporting-Endpoints ヘッダーに移行することです。
以前の Reporting API（v0）を使用して CSP（Content-Security-Policy ヘッダー）の違反レポートを取得している場合は、新しい Reporting API（v1）への移行の一環として Content-Security-Policy を調整する必要があります。
基本的な移行
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" }] }
サイトにレポート機能がすでにある場合は、レポートが失われるのを防ぐため、Report-To を一時的にのみ（ほとんどの Chrome クライアントと Edge クライアントが更新されるまで）保持してください。
ネットワーク エラー ロギングが必要な場合は、ネットワーク エラー ロギングの代替手段が利用可能になるまで Report-To を維持します。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
ほとんどの Chrome クライアントと Edge クライアントが更新され、API v1 をサポートするようになると、コードは次のように変更されます。
v1 では、特定のレポートのタイプを特定のエンドポイントに送信することは引き続き可能です。ただし、エンドポイントごとに使用できる URL は 1 つだけです。
すべてのページをモニタリングする
app.get("/", (request, response) => {
response.set("Report-To", …)
response.render(...)
});
app.get("/page1", (request, response) => {
response.render(...)
});
v0 では、一部の回答にのみレポート エンドポイントを設定できます。そのオリジンの他のドキュメント（ページ）は、これらのアンビエント エンドポイントを自動的に使用します。ここで、"/" に設定されたエンドポイントは、page1 などのすべてのレスポンスに使用されます。
// 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(...)
});
v1 では、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定する必要があります。
CSP レポートの移行
Content-Security-Policy: ...; report-uri https://reports.example/main
report-uri のみを使用することは推奨されなくなりました。コードが上記の状態であれば、移行します。以下の新しいコード例（緑色）をご覧ください。
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
これはより適切なコードです。このコードでは、report-uri の新しい代替である report-to を使用しています。下位互換性を確保するため、report-uri は引き続き保持されます。一部のブラウザは report-to をサポートしていませんが、report-uri はサポートしています。
ただし、このコードは Reporting API v0（Report-To ヘッダー）を使用しています。v1 に移行する: 以下の「新しいコード」の例（緑色）をご覧ください。
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
report-to ディレクティブがブラウザ間でサポートされるまで、report-uri ディレクティブを report-to ディレクティブとともに使用してください。ブラウザの互換性に関する表をご覧ください。
Report-To は Reporting-Endpoints の横に一時的に置いておきます。Chrome と Edge のほとんどのユーザーが 96 以降のブラウザ バージョンにアップグレードしたら、Report-To を削除します。
関連情報
- Reporting API を使用してウェブ アプリケーションをモニタリングする（Reporting API に関するメイン投稿）
- 仕様: 以前の Reporting API（v0）
- 仕様: 新しい Reporting API（v1）
この記事のレビューと提案をしてくれた Ian Clelland 氏、Eiji Kitamura 氏、Milica Mihajlija 氏に感謝します。