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 から新しいメカニズムに切り替えてください。

デモとコード

• デモサイト: 新しいレポート 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 も同じレポートタイプをサポートしていますが、1 つだけ例外があります。v1 はネットワーク エラー レポートをサポートしていません。詳しくは、移行手順をご覧ください。
• v0 はブラウザ間でサポートされておらず、今後もサポートされる予定はありません。v1 は、今後複数のブラウザでサポートされる可能性が高くなります。

変更されない点

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

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

v0 と v1 のすべての違い

エンドポイント デベロッパー: トラフィックの増加が予想されます

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

これは、Reporting API v1 では Reporting API v0 のようにレポートがバッチ処理されないためです。そのため、アプリケーション デベロッパーが 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 のみを保持します。

   ただし、ネットワーク エラー ロギング レポートが必要な場合は、ネットワーク エラー ロギングの新しいメカニズムが導入されるまで 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 を持ちます）。

ただし、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 クライアントの両方からレポートを取得できます。

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）

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