新しいバージョンの Reporting API をご利用いただけます。プライバシーに配慮し、ブラウザをまたいでサポートできる可能性が高くなります。
Reporting API は、サイト訪問者がサイトを使用する際に発生したエラーについて通知します。ブラウザの介入、ブラウザのクラッシュ、コンテンツ セキュリティ ポリシー違反、COOP/COEP 違反、非推奨の警告などを確認できます。
新しいバージョンの Reporting API をご利用いただけます。新しい API はサイズが削減され、どのブラウザでもサポートされる可能性が高くなります。
まとめ
サイト デベロッパー
すでにサイトにレポート機能がある場合: 新しいヘッダー(Reporting-Endpoints
)を使用して v1 に移行します。ただし、以前のヘッダーはしばらくは残しておきます(Report-To
)。移行: サンプルコードをご覧ください。
今すぐサイトにレポート機能を追加する場合: 新しいヘッダー(Reporting-Endpoints
)のみを使用します。
⚠️ いずれの場合も、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints
ヘッダーを設定してください。
レポート サービスのデベロッパー
エンドポイント サービスを保守しているか、独自のサービスを運用している場合は、お客様または外部のデベロッパーが Reporting API v1(Reporting-Endpoints
ヘッダー)に移行するため、トラフィックの増加が予想されます。
詳細とサンプルコードについては、以下をご覧ください。
ネットワーク エラーのロギング
ネットワーク エラー ロギングの新しいメカニズムが開発されます。利用可能になったら、Reporting API v0 からこの新しいメカニズムに切り替えます。
デモとコード
- デモサイト: 新しい Reporting 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
- レポートの範囲が異なります。
v0 では、一部のレスポンスにのみレポート エンドポイントを設定できます。そのオリジンの他のドキュメント(ページ)では、これらのアンビエント エンドポイントが自動的に使用されます。
v1 では、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints
ヘッダーを設定する必要があります。
- どちらの API も同じレポートタイプをサポートしていますが、v1 はネットワーク エラー レポートをサポートしていません。詳しくは、移行手順をご覧ください。
- v0 はサポートされておらず、今後複数のブラウザでサポートされなくなります。v1 は、今後複数のブラウザでサポートされる可能性があります。
変更されないもの
- レポートの形式と構造は変更されません。
- ブラウザからエンドポイントに送信されたリクエストは、
Content-type
application/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 を定義する)のいずれかにレポートを送信します。 | 特定のレポート コレクタにレポートを送信します(エンドポイントごとに 1 つの URL のみを定義します)。 |
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 に移行してください(移行手順をご覧ください)。サイトでコンテンツ セキュリティ ポリシー違反のレポート機能をすでに使用している場合は、該当する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 など、幅広いブラウザをサポートしています。レポートはコンテンツ タイプapplication/csp-report
で送信され、CSP 固有の形式になります。このレポートは「CSP レベル 2 レポート」と呼ばれ、Reporting API には依存しません。- Reporting API の場合は、
Report-To
ヘッダー(従来版)または新しいReporting-Endpoints
(v1)を使用します。この機能は Chrome と Edge でのみサポートされています。レポート リクエストは、他の Reporting API リクエストと同じ形式で、コンテンツ タイプのapplication/reports+json
も同じです。
最初の方法(report-uri
のみ)の使用は推奨されなくなりました。2 番目の方法にはいくつかの利点があります。特に、すべてのレポート タイプのレポートを設定するだけでなく、1 つの方法で汎用のエンドポイントを設定できます(Reporting API と CSP のおよび他のレポート リクエストはすべて同じ形式 application/reports+json
になるためです)。
ただし、report-to
をサポートしているブラウザは限られています。したがって、複数のブラウザから CSP 違反レポートを取得するには、report-uri
を Reporting API のアプローチ(Report-To
以上、Reporting-Endpoints
)とともに使用することをおすすめします。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 および Edge の新旧両方のクライアントからレポートを取得できます。ステップ 3(後で開始): すべてまたは大部分のユーザーが Chrome または Edge 96 以降のインストールに更新したら、
Report-To
(v0)を削除してReporting-Endpoints
のみを残します。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" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
なお、v1 の場合でも、特定のレポートタイプを特定のエンドポイントに送信できます。ただし、エンドポイントごとに指定できる URL は 1 つのみです。
すべてのページの監視
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 に関する主な投稿)
- 仕様: 以前の Reporting API(v0)
- 仕様: 新しい Reporting API(v1)
ヒーロー画像 by Nine Koepfer / @enka80 Unsplash 編集この記事に対するレビューと提案について、Ian Claland、Eiji Kitamura、Milica Mihajlija に感謝します。