Bermigrasi ke Reporting API v1

Versi baru Reporting API telah tersedia. Setelan ini lebih pribadi dan lebih mungkin didukung di seluruh browser.

Maud Nalpas

Reporting API memberi tahu Anda tentang error yang terjadi di seluruh situs Anda saat pengunjung menggunakannya. Ini memberi visibilitas tentang intervensi browser, error browser, pelanggaran Kebijakan Keamanan Konten, Pelanggaran COOP/COEP, peringatan penghentian penggunaan, dan lain-lain.

Versi baru Reporting API telah tersedia. API baru ini lebih ringkas dan cenderung didukung di seluruh browser.

Ringkasan

Developer situs

Jika Anda sudah memiliki fungsi pelaporan untuk situs: migrasikan ke v1 menggunakan header baru (Reporting-Endpoints), tetapi simpan header lama selama beberapa waktu (Report-To). Lihat Migrasi: kode contoh.

Jika Anda baru saja menambahkan fungsi pelaporan ke situs: hanya gunakan header baru (Reporting-Endpoints).

⚠️ Dalam kedua kasus tersebut, pastikan untuk menetapkan header Reporting-Endpoints pada semua respons yang mungkin membuat laporan.

Developer layanan pelaporan

Jika mengelola layanan endpoint atau mengoperasikan layanan endpoint sendiri, Anda akan mendapatkan lebih banyak traffic karena atau developer eksternal bermigrasi ke Reporting API v1 (header Reporting-Endpoints).

Baca terus untuk mengetahui detail dan kode contoh.

Logging Error Jaringan

Mekanisme baru untuk Network Error Logging akan dikembangkan. Setelah itu tersedia, beralihlah dari Reporting API v0 ke mekanisme baru tersebut.

Demo dan kode

• Situs demo: new reporting API (v1)
• Kode untuk situs demo

Perbedaan antara v0 dan v1

Yang berubah

• Platform API-nya berbeda.

 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

• Cakupan laporannya berbeda.

• Kedua API mendukung jenis laporan yang sama, dengan satu pengecualian: v1 tidak mendukung Laporan Error Jaringan. Baca selengkapnya di langkah-langkah migrasi.
• v0 tidak dan tidak akan didukung di semua browser. v1 lebih mungkin didukung di beberapa {i>browser<i} di masa mendatang.

Yang tidak berubah

• Format dan struktur laporan tidak berubah.
• Permintaan yang dikirim oleh browser ke endpoint tetap merupakan permintaan POST dari Content-type application/reports+json.
• Pemetaan endpoint tertentu ke jenis laporan tertentu didukung di v0 dan v1.
• Peran endpoint default tidak berubah.

• Reporting API v1 tidak berdampak pada ReportingObserver. ReportingObserver akan terus mendapatkan akses ke semua laporan yang dapat diamati, dan formatnya adalah identik.

Semua perbedaan antara v0 dan v1

Developer endpoint: Mengharapkan lebih banyak traffic

Jika Anda telah menyiapkan server Anda sendiri sebagai endpoint pelaporan, atau jika Anda mengembangkan atau mempertahankan pengumpul laporan sebagai layanan, nantikan lebih banyak traffic ke endpoint tersebut.

Hal ini karena laporan tidak dikelompokkan dengan Reporting API v1 seperti dengan Reporting API v0. Oleh karena itu, saat developer aplikasi mulai bermigrasi ke Reporting API v1, jumlah laporan akan tetap serupa, tetapi volume permintaan ke server endpoint akan meningkat.

Developer aplikasi: Bermigrasi ke Reporting-Endpoints (v1)

Apa yang perlu Anda lakukan?

Penggunaan Reporting API (v1) baru memiliki beberapa manfaat ✅:

• Sinyal browser bersifat positif, yang berarti dukungan lintas browser dapat diharapkan untuk v1 (tidak seperti v0 yang hanya didukung di Chrome dan tepi).
• API-nya lebih ramping.
• Alat sedang dikembangkan terkait Reporting API (v1) baru.

Mengingat hal ini:

• Jika situs Anda sudah menggunakan Reporting API v0 dengan header Report-To, migrasikan ke Reporting API v1 (lihat langkah-langkah migrasi). Jika situs Anda sudah menggunakan fungsi pelaporan untuk pelanggaran Kebijakan Keamanan Konten, periksa langkah-langkah migrasi yang spesifik untuk pelaporan CSP.
• Jika situs Anda belum menggunakan Reporting API dan kini Anda menambahkan fungsi pelaporan: gunakan Reporting API (v1) baru (header Reporting-Endpoints). Ada satu pengecualian untuk ini: jika Anda perlu menggunakan Logging Error Jaringan, gunakan Report-To (v0). Logging Error Jaringan saat ini tidak didukung di Reporting API v1. Mekanisme baru untuk {i>Network Error Logging<i} akan dikembangkan⏤hingga tersedia, gunakan Reporting API v0. Jika Anda memerlukan Logging Error Jaringan bersama jenis laporan lainnya, gunakan kedua Report-To (v0) dan Reporting-Endpoints (v1). v0 memberi Anda Log Kesalahan Jaringan dan v1 memberi Anda laporan dari semua jenis yang lain.

Langkah migrasi

Sasaran Anda dalam migrasi ini adalah tidak kehilangan laporan yang biasa Anda dapatkan dengan v0.

1. Langkah 1 (lakukan sekarang): Gunakan kedua header: Report-To (v0) dan Reporting-Endpoints (v1).

   Dengan ini, Anda mendapatkan:

   • Laporan dari klien Chrome dan Edge yang lebih baru berkat Reporting-Endpoints (v1).
   • Laporan dari klien Chrome dan Edge lama berkat Report-To (v0).

   Instance browser yang mendukung Reporting-Endpoints akan menggunakan Reporting-Endpoints, dan instance yang tidak dapat dialihkan ke Report-To. Format permintaan dan laporan adalah sama untuk v0 dan v1.

2. Langkah 2 (lakukan sekarang): Pastikan header Reporting-Endpoints disetel di semua respons yang dapat membuat laporan.

   Dengan v0, Anda dapat memilih untuk menetapkan endpoint pelaporan hanya pada beberapa respons, dan dokumen lainnya (halaman) di situs asal tersebut akan menggunakan "ambient" ini endpoint. Dengan v1, karena perbedaan pencakupan, Anda perlu menyetel header Reporting-Endpoints pada semua respons yang mungkin menghasilkan laporan.

3. Langkah 3 (mulai nanti): Setelah semua atau sebagian besar pengguna mengupdate Chrome atau Edge yang lebih baru penginstalan (96 dan yang lebih baru), hapus Report-To (v0) dan hanya mempertahankan Reporting-Endpoints.

   Satu pengecualian: jika Anda memerlukan laporan Logging Error Jaringan, simpan Report-To hingga versi baru diterapkan untuk {i>Network Error Logging<i}.

Lihat contoh kode di buku resep migrasi.

Langkah-langkah migrasi untuk pelaporan CSP

Ada dua cara Content-Security-Policy laporan pelanggaran dapat dikonfigurasi:

• Dengan header CSP saja melalui perintah report-uri. Solusi ini memiliki dukungan browser yang luas, di seluruh Chrome, Firefox, Safari, dan Edge. Laporan dikirim dengan jenis konten application/csp-report dan memiliki format khusus untuk CSP. Laporan ini disebut "Laporan Tingkat 2 CSP" dan lakukan tidak mengandalkan Reporting API.
• Dengan Reporting API, yaitu melalui header Report-To (lama) atau versi yang lebih baru Reporting-Endpoints (v1). Opsi ini hanya didukung di Chrome dan Edge. Permintaan laporan memiliki format yang sama dengan permintaan Reporting API lainnya, dan application/reports+json jenis konten yang sama.

Menggunakan pendekatan pertama (hanya report-uri) tidak lagi direkomendasikan dan menggunakan pendekatan kedua memiliki beberapa manfaat. Secara khusus, hal ini memungkinkan Anda menggunakan satu cara untuk menyiapkan pelaporan bagi semua jenis laporan dan juga menetapkan endpoint umum (karena semua permintaan laporan yang dibuat melalui Reporting API⏤CSP dan lainnya⏤ memiliki format yang sama application/reports+json.

Namun, hanya beberapa browser yang mendukung report-to. Oleh karena itu, sebaiknya tetap gunakan report-uri bersama dengan pendekatan Reporting API (Report-To atau lebih baik, Reporting-Endpoints) untuk mendapatkan laporan pelanggaran CSP dari beberapa browser. Di browser yang mengenali report-uri dan report-to, report-uri akan diabaikan jika report-to tersedia. Di browser yang hanya mengenali report-uri, hanya report-uri yang akan dipertimbangkan.

1. Langkah 1 (lakukan sekarang): Jika Anda belum menambahkannya, tambahkan report-to bersama report-uri. Browser yang hanya mendukung report-uri (Firefox) akan menggunakan report-uri, dan browser yang juga mendukung report-to(Chrome, Edge) akan menggunakan report-to. Untuk menentukan endpoint bernama yang akan Anda gunakan di report-to, gunakan header Report-To dan Reporting-Endpoints. Hal ini memastikan bahwa Anda mendapatkan laporan dari klien Chrome dan Edge versi lama dan yang lebih baru.

2. Langkah 3 (mulai nanti): Setelah semua atau sebagian besar pengguna mengupdate Chrome atau Edge yang lebih baru penginstalan (96 dan yang lebih baru), hapus Report-To (v0) dan hanya mempertahankan Reporting-Endpoints. Pertahankan report-uri sehingga Anda tetap mendapatkan laporan untuk browser yang hanya mendukungnya.

Lihat contoh kode untuk langkah-langkah ini di Migrasi pelaporan CSP.

Migrasi: kode contoh

Ringkasan

Jika Anda menggunakan Reporting API (v0) lama untuk mendapatkan laporan pelanggaran untuk COOP (header Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy), atau kebijakan dokumen (header Document-Policy): Anda tidak perlu mengubah header kebijakan tersebut saat bermigrasi ke Reporting API v1. Anda hanya perlu bermigrasi dari header Report-To lama ke header baru Header Reporting-Endpoints.

Jika Anda menggunakan Reporting API (v0) lama untuk mendapatkan laporan pelanggaran bagi CSP (header Content-Security-Policy), Anda mungkin perlu menyesuaikan Content-Security-Policy sebagai bagian dari migrasi Anda ke Reporting API (v1) baru.

Migrasi dasar

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"

Perhatikan bahwa dengan v1, Anda masih dapat mengirim jenis laporan tertentu ke endpoint tertentu. Tapi Anda hanya dapat memiliki satu URL per endpoint.

Mengamati semua halaman

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(...)
});

Migrasi pelaporan 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: ...

Bacaan lebih lanjut

• Memantau aplikasi web Anda dengan Reporting API (postingan utama di Reporting API)
• Spesifikasi: Reporting API (v0) lama
• Spesifikasi: Reporting API (v1) baru

Banner besar oleh Nine Koepfer / @enka80 di Unsplash, diedit. Terima kasih banyak kepada Ian Clelland, Eiji Kitamura, dan Milica Mihajlija atas ulasan dan saran mereka tentang artikel ini.