Reporting API v1 に移行する

新しいバージョンの Reporting API をご利用いただけます。プライバシーに配慮し、ブラウザをまたいでサポートできる可能性が高くなります。

Maud Nalpas

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

• レポートの範囲が異なります。

• どちらの API も同じレポートタイプをサポートしていますが、v1 はネットワーク エラー レポートをサポートしていません。詳しくは、移行手順をご覧ください。
• v0 はサポートされておらず、今後複数のブラウザでサポートされなくなります。v1 は、今後複数のブラウザでサポートされる可能性があります。

変更されないもの

• レポートの形式と構造は変更されません。
• ブラウザからエンドポイントに送信されたリクエストは、Content-type application/reports+json の POST リクエストのままです。
• 特定のエンドポイントを特定のレポートタイプにマッピングすることは、v0 と v1 の両方でサポートされています。
• default エンドポイントのロールは変更されません。

• Reporting API v1 は ReportingObserver には影響しません。 ReportingObserver はすべての観測可能なレポートに引き続きアクセスできます。それらの形式は同じです。

v0 と v1 のすべての違い

エンドポイントのデベロッパー: トラフィックの増加が期待できる

独自のサーバーをレポート エンドポイントとして設定している場合や、レポート コレクタをサービスとして開発または維持している場合は、そのエンドポイントへのトラフィックが増えることが予想されます。

これは、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. ステップ 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. ステップ 2（今すぐ）: レポートを生成する可能性のあるすべてのレスポンスに Reporting-Endpoints ヘッダーが設定されていることを確認します。

   v0 では、一部のレスポンスにのみレポート エンドポイントを設定し、そのオリジンの他のドキュメント（ページ）でこの「アンビエント」エンドポイントを使用することができます。v1 ではスコープの違いにより、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定する必要があります。

3. ステップ 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. ステップ 1（今すぐ行う）: まだ追加していない場合は、report-uri とともに report-to を追加します。report-uri のみをサポートするブラウザ（Firefox）では report-uri を使用し、report-to もサポートしているブラウザ（Chrome、Edge）では report-to を使用します。report-to で使用する名前付きエンドポイントを指定するには、ヘッダー Report-To と Reporting-Endpoints の両方を使用します。これにより、Chrome および Edge の新旧両方のクライアントからレポートを取得できます。

2. ステップ 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 に感謝します。