Reporting API v1 に移行する

新しいバージョンの Reporting API をご利用いただけます。よりプライバシーが保護され、ブラウザ間でサポートされる可能性が高い。

Maud Nalpas

注意: この記事では、Reporting API の新しいバージョン（v1）に移行する方法について説明します。Reporting API を初めて使用する方や、詳細な使用例が必要な方は、Reporting API に関するメイン投稿をご覧ください。

Reporting API は、訪問者がサイトを使用する際に発生したエラーを通知します。ブラウザの介入、ブラウザのクラッシュ、Content-Security-Policy 違反、COOP / COEP 違反、非推奨に関する警告などを可視化できます。

Reporting API の新しいバージョンが利用可能になりました。新しい API はよりシンプルで、ブラウザ間でサポートされる可能性が高い。

注: 以前の Reporting API の名前は Reporting API v0 です。新しい Reporting API の名前は Reporting API v1 です。

概要

サイト デベロッパー

サイトにすでにレポート機能がある場合: 新しいヘッダー（Reporting-Endpoints）を使用して v1 に移行しますが、レガシー ヘッダーはしばらくそのままにしておきます（Report-To）。移行: コード例をご覧ください。

今すぐサイトにレポート機能を追加する場合: 新しいヘッダー（Reporting-Endpoints）のみを使用します。

⚠️ どちらの場合も、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定してください。

レポート サービスのデベロッパー

エンドポイント サービスを管理している場合や独自のエンドポイント サービスを運用している場合、ご自身または外部のデベロッパーが Reporting API v1（Reporting-Endpoints ヘッダー）に移行するため、トラフィックの増加が予想されます。

詳細とサンプルコードについては、以下をご覧ください。

ネットワーク エラーのロギング

注意: ネットワーク エラー ロギングを使用している場合は、Reporting API v1 でネットワーク エラー ロギングがサポートされていないため、Report-To（v0）を引き続き使用してください。

ネットワーク エラーのロギングのための新しいメカニズムが開発されます。利用可能になったら、Reporting API v0 から新しいメカニズムに切り替えてください。

デモとコード

• デモサイト: 新しい Reporting API（v1）
• デモサイトのコード

v0 と v1 の違い

変更点

• API サーフェスは異なります。

v0（以前のバージョン）

 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 ディレクティブを使用してこれらのエンドポイント グループを参照します。

v1（新規）

 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（以前のバージョン）

v0 では、一部の回答にのみレポート エンドポイントを設定できます。そのオリジンの他のドキュメント（ページ）は、これらのアンビエント エンドポイントを自動的に使用します。

v1（新規）

v1 では、レポートを生成する可能性があるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定する必要があります。

• どちらの API も同じレポートタイプをサポートしていますが、1 つの例外として、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 が定義されている）のいずれかに送信します。	レポートを特定のレポート コレクタに送信します（エンドポイントごとに定義される URL は 1 つだけです）。
API サーフェス	`Report-To` ヘッダーを使用して、名前付きエンドポイント グループを構成します。	`Reporting-Endpoints` ヘッダーを使用して、名前付きエンドポイントを構成します。
この API で生成できるレポートの種類	非推奨 介入 衝突事故 COOP / COEP Content-Security-Policy レベル 3（CSP Level 3） ネットワーク エラー ロギング（NEL） レポート タイプの詳細については、Reporting API に関する投稿をご覧ください。	ネットワーク エラー ロギング（NEL）: 新しい Reporting API（v1）ではサポートされていませんを除き、変更なし。
レポートの範囲	生成元に帰属するものとして扱うことを可能にする技術です。 ドキュメントの Report-To ヘッダーは、その生成元の他のドキュメント（ページ）に影響します。レポートの url フィールドは、引き続きドキュメントごとに異なります。	Document. ドキュメントの Reporting-Endpoints ヘッダーは、そのドキュメントにのみ影響します。 レポートの url フィールドは、引き続きドキュメントごとに異なります。
レポートの分離（バッチ処理）	同じレポート エンドポイントを持つ異なるドキュメント（ページ）やサイト/オリジンがほぼ同時にレポートを生成する場合、それらのドキュメントはまとめてバッチ処理され、同じメッセージでレポート エンドポイントに送信されます。	異なるドキュメント（ページ）のレポートが一緒に送信されることはありません。同じオリジンの 2 つのドキュメント（ページ）が同じエンドポイントに対して同時にレポートを生成しても、バッチ化はされません。これは、プライバシー攻撃を軽減するメカニズムです。 同じドキュメント（ページ）のレポートは、まとめて送信されることがあります。
ロード バランシング / 優先度のサポート	はい	×

エンドポイント デベロッパー: トラフィックの増加が見込まれる

独自のサーバーをレポート エンドポイントとして設定している場合や、レポート コレクタをサービスとして開発またはメンテナンスしている場合は、そのエンドポイントへのトラフィックがさらに増加します。

これは、Reporting API v0 とは異なり、Reporting API v1 ではレポートがバッチ処理されないためです。したがって、アプリケーション デベロッパーが Reporting API v1 への移行を開始すると、レポートの数は変わらないものの、エンドポイント サーバーへのリクエスト数は増加します。

アプリケーション デベロッパー: Reporting-Endpoints（v1）に移行する

どうすればよいですか。

新しい Reporting API（v1）には、次のようなメリットがあります。

• ブラウザ シグナルはポジティブです。つまり、Chrome と Edge でのみサポートされている v0 とは異なり、v1 ではクロスブラウザのサポートが期待できます。
• 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 で取得していたレポートが失われるのを防ぐことです。

注: Reporting API v0 は Chrome と Edge でのみサポートされているため、v1 への移行中に他のブラウザに注意する必要はありません。ただし、今後、より幅広いブラウザのサポートが追加される可能性があります。現時点ではこれらのブラウザのトラッキング バグはありませんが、今後変更される可能性があります。

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 など、幅広いブラウザでサポートされています。レポートは content-type 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 つ目の方法にはいくつかのメリットがあります。特に、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. ステップ 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 クライアントの両方からレポートを受け取ることができます。

2. ステップ 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 を調整する必要があります。

基本的な移行

以前のコード（v0 を使用）

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

新しいコード（v1 と v0 の両方を含む移行コード）

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 を維持します。

新しいコード（v1 のみ）

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

ほとんどの Chrome クライアントと Edge クライアントが更新され、API v1 をサポートするようになると、コードは次のように変更されます。

v1 では、特定のレポートのタイプを特定のエンドポイントに送信することは引き続き可能です。ただし、エンドポイントごとに使用できる URL は 1 つだけです。

すべてのページをモニタリングする

以前のコード（v0 を使用）: Express など

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

v0 では、一部の回答にのみレポート エンドポイントを設定できます。そのオリジンの他のドキュメント（ページ）は、これらのアンビエント エンドポイントを自動的に使用します。ここで、"/" に設定されたエンドポイントは、page1 などのすべてのレスポンスに使用されます。

新しいコード（v1 を使用）: Express など

// 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 レポートの移行

レガシー コード（report-uri のみ）

Content-Security-Policy: ...; report-uri https://reports.example/main

report-uri のみを使用することは推奨されなくなりました。コードが上記の状態であれば、移行します。以下の新しいコード例（緑色）をご覧ください。

より優れたレガシー コード: report-uri と Report-To（v0）ヘッダーを含む report-to ディレクティブ

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 に移行する: 以下の「新しいコード」の例（緑色）をご覧ください。

report-uri と report-to ディレクティブ（Reporting-Endpoints（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 ディレクティブとともに使用してください。ブラウザの互換性に関する表をご覧ください。

一時的に Reporting-Endpoints と Report-To を一緒に置いてください。Chrome と Edge のほとんどのユーザーが 96 以降のブラウザ バージョンにアップグレードしたら、Report-To を削除します。

関連情報

• Reporting API を使用してウェブ アプリケーションをモニタリングする（Reporting API に関するメイン投稿）
• 仕様: 以前の Reporting API（v0）
• 仕様: 新しい Reporting API（v1）

この記事のレビューと提案をしてくれた Ian Clelland 氏、Eiji Kitamura 氏、Milica Mihajlija 氏に感謝します。