Bermigrasi ke Reporting API v1

Reporting API versi baru telah tersedia. Metode ini lebih bersifat pribadi dan lebih cenderung didukung di seluruh browser.

Maud Nalpas

Perhatian: Postingan ini membahas cara bermigrasi ke Reporting API versi baru (v1). Jika Anda baru menggunakan Reporting API atau memerlukan contoh penggunaan yang mendetail, buka postingan utama tentang Reporting API.

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

Reporting API versi baru telah tersedia. API baru ini lebih ramping dan lebih mungkin didukung di seluruh browser.

Catatan: Reporting API lama bernama Reporting API v0. Reporting API baru diberi nama Reporting API v1.

Ringkasan

Developer situs

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

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 menghasilkan laporan.

Developer layanan pelaporan

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

Baca terus untuk mengetahui detail dan contoh kodenya.

Logging Error Jaringan

Perhatian: Jika Anda menggunakan Penautan Error Jaringan, terus gunakan Report-To (v0) karena Penautan Error Jaringan tidak didukung di Reporting API v1.

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

Demo dan kode

• Situs demo: API pelaporan baru (v1)
• Kode untuk situs demo

Perbedaan antara v0 dan v1

Yang berubah

• Platform API-nya berbeda.

v0 (lama)

 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 menggunakan header Report-To untuk mengonfigurasi grup endpoint bernama, dan perintah report-to di header lain untuk mereferensikan grup endpoint ini.

v1 (baru)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 menggunakan header Reporting-Endpoints untuk mengonfigurasi endpoint bernama. Seperti v0, v1 menggunakan perintah report-to di header lain untuk mereferensikan grup endpoint ini.

• Cakupan laporan berbeda.

v0 (lama)

Dengan v0, Anda dapat menetapkan endpoint pelaporan hanya pada beberapa respons. Dokumen (halaman) lain di origin tersebut akan otomatis menggunakan endpoint standby ini.

v1 (baru)

Dengan v1, Anda perlu menetapkan header Reporting-Endpoints di semua respons yang mungkin menghasilkan laporan.

• 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 seluruh browser. v1 kemungkinan besar akan didukung di beberapa browser pada masa mendatang.

Yang tetap tidak berubah

• Format dan struktur laporan tidak berubah.
• Permintaan yang dikirim oleh browser ke endpoint tetap berupa 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 memengaruhi ReportingObserver. ReportingObserver terus mendapatkan akses ke semua laporan yang dapat diamati, dan formatnya sama.

Semua perbedaan antara v0 dan v1

	Header Reporting API lama (v0) Report-To	Header Reporting API (v1) Reporting-Endpoints baru
Dukungan browser	Chrome 69+ dan Edge 69+.	Chrome 96+ dan Edge 96+. Firefox mendukung. Safari tidak keberatan. Lihat sinyal browser.
Endpoint	Mengirim laporan ke beberapa kolektor laporan (beberapa URL yang ditentukan per grup endpoint).	Mengirim laporan ke pengumpulan laporan tertentu (hanya satu URL yang ditentukan per endpoint).
Platform API	Menggunakan header `Report-To` untuk mengonfigurasi grup endpoint bernama.	Menggunakan header `Reporting-Endpoints` untuk mengonfigurasi endpoint bernama.
Jenis laporan yang dapat dibuat melalui API ini	Status penghentian penggunaan Intervensi Tabrakan COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Pencatatan Log Error Jaringan (NEL) Pelajari jenis laporan lebih lanjut di postingan Reporting API.	Tidak berubah, kecuali dari Penautan Log Error Jaringan (NEL): ini tidak didukung di Reporting API (v1) yang baru.
Cakupan laporan	Asal Anda. Header Report-To dokumen memengaruhi dokumen (halaman) lain dari origin tersebut. Kolom url laporan masih bervariasi per dokumen.	Dokumentasikan. Header Reporting-Endpoints dokumen hanya memengaruhi dokumen tersebut. Kolom url laporan masih bervariasi per dokumen.
Isolasi laporan (pengelompokan)	Dokumen (halaman) atau situs/asal yang berbeda yang membuat laporan pada waktu yang hampir bersamaan dan memiliki endpoint pelaporan yang sama akan dikelompokkan bersama: dokumen tersebut akan dikirim dalam pesan yang sama ke endpoint pelaporan.	Laporan dari dokumen (halaman) yang berbeda tidak pernah dikirim bersama. Meskipun dua dokumen (halaman) dari origin yang sama menghasilkan laporan secara bersamaan, untuk endpoint yang sama, laporan tersebut tidak akan dikelompokkan. Ini adalah mekanisme untuk mengurangi serangan privasi. Laporan dari dokumen (halaman) yang sama dapat dikirim bersama.
Dukungan untuk load balancing / prioritas	Ya	Tidak

Developer endpoint: Mendapatkan lebih banyak traffic

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

Hal ini karena laporan tidak dikelompokkan dengan Reporting API v1 seperti halnya 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?

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

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

Dengan mempertimbangkan 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 untuk pelaporan CSP tertentu.
• Jika situs Anda belum menggunakan Reporting API dan Anda sekarang menambahkan fungsi pelaporan: gunakan Reporting API baru (v1) (header Reporting-Endpoints). Ada satu pengecualian untuk hal 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 Logging Error Jaringan akan dikembangkan⏤hingga tersedia, gunakan Reporting API v0. Jika Anda memerlukan Logging Error Jaringan bersama jenis laporan lainnya, gunakan Report-To (v0) dan Reporting-Endpoints (v1). v0 memberi Anda Logging Error Jaringan dan v1 memberi Anda laporan dari semua jenis lainnya.

Langkah migrasi

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

Catatan: Karena hanya Chrome dan Edge yang mendukung Reporting API v0, Anda tidak perlu berfokus pada browser lain selama migrasi ke v1. Namun, perlu diingat bahwa dukungan browser yang lebih luas mungkin akan tersedia. Saat ini tidak ada bug pelacakan untuk browser ini, tetapi hal ini dapat berubah.

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 akan kembali ke Report-To. Format permintaan dan laporan sama untuk v0 dan v1.

2. Langkah 2 (lakukan sekarang): Pastikan header Reporting-Endpoints ditetapkan di semua respons yang mungkin menghasilkan laporan.

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

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

   Satu pengecualian: jika Anda memerlukan laporan Logging Error Jaringan, pertahankan Report-To hingga mekanisme baru diterapkan untuk Logging Error Jaringan.

Lihat contoh kode di cookbook migrasi.

Langkah-langkah migrasi untuk pelaporan CSP

Ada dua cara untuk mengonfigurasi laporan pelanggaran Content-Security-Policy:

• Dengan header CSP saja melalui perintah report-uri. Fitur ini memiliki dukungan browser yang luas, di Chrome, Firefox, Safari, dan Edge. Laporan dikirim dengan jenis konten application/csp-report dan memiliki format yang khusus untuk CSP. Laporan ini disebut "Laporan CSP Level 2" dan tidak bergantung pada Reporting API.
• Dengan Reporting API, yaitu melalui header Report-To (lama) atau Reporting-Endpoints yang lebih baru (v1). Fitur 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.

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

Namun, hanya beberapa browser yang mendukung report-to. Oleh karena itu, sebaiknya Anda tetap menggunakan report-uri bersama 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 ada. 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 yang lebih lama dan lebih baru.

2. Langkah 3 (mulai nanti): Setelah semua atau sebagian besar pengguna Anda mengupdate ke penginstalan Chrome atau Edge yang lebih baru (96 dan yang lebih baru), hapus Report-To (v0) dan hanya pertahankan Reporting-Endpoints. Simpan report-uri agar 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 lama (v0) 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 ini sendiri saat bermigrasi ke Reporting API v1. Yang Anda perlukan adalah bermigrasi dari header Report-To lama ke header Reporting-Endpoints baru.

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

Migrasi dasar

Kode lama (dengan v0)

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

Kode baru (kode transisi dengan v0 bersama v1)

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" }] }

Jika Anda sudah memiliki fungsi pelaporan di situs, pertahankan Report-To hanya untuk sementara (hingga sebagian besar klien Chrome dan Edge telah diupdate) untuk menghindari hilangnya laporan.

Jika Anda memerlukan Logging Error Jaringan, pertahankan Report-To hingga pengganti Logging Error Jaringan tersedia.

Kode baru (khusus v1)

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

Ini adalah tampilan kode Anda pada masa mendatang, setelah sebagian besar klien Chrome dan Edge telah diupdate dan mendukung API v1.

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

Mengamati semua halaman

Kode lama (dengan v0), misalnya dengan Express

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

Dengan v0, Anda dapat menetapkan endpoint pelaporan hanya pada beberapa respons. Dokumen (halaman) lain di origin tersebut secara otomatis menggunakan endpoint standby ini. Di sini, endpoint yang ditetapkan untuk "/" digunakan untuk semua respons, misalnya untuk page1.

Kode baru (dengan v1), misalnya dengan 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(...)
});

Dengan v1, Anda perlu menetapkan header Reporting-Endpoints di semua respons yang mungkin menghasilkan laporan.

Migrasi pelaporan CSP

Kode lama, hanya dengan report-uri

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

Hanya menggunakan report-uri tidak lagi direkomendasikan. Jika kode Anda terlihat seperti di atas, lakukan migrasi. Lihat contoh Kode baru di bawah (berwarna hijau).

Kode lama yang lebih baik, dengan report-uri dan perintah report-to dengan header Report-To (v0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Ini lebih baik: kode ini menggunakan report-to, pengganti yang lebih baru untuk report-uri. Report-uri masih ada untuk kompatibilitas mundur; beberapa browser tidak mendukung report-to, tetapi mendukung report-uri.

Namun, ini bisa lebih baik: kode ini menggunakan Reporting API v0 (header Report-To). Bermigrasi ke v1: lihat contoh 'Kode baru' di bawah (berwarna hijau).

Kode baru, dengan report-uri dan perintah report-to dengan header 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: ...

Pertahankan perintah report-uri bersama perintah report-to hingga perintah report-to didukung di seluruh browser. Lihat tabel kompatibilitas browser.

Simpan Report-To bersama Reporting-Endpoints untuk sementara. Setelah sebagian besar pengunjung Chrome dan Edge Anda mengupgrade ke versi browser 96+, hapus Report-To.

Bacaan lebih lanjut

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

Terima kasih banyak kepada Ian Clelland, Eiji Kitamura, dan Milica Mihajlija atas ulasan dan saran mereka tentang artikel ini.