Reporting API versi baru telah tersedia. Cara ini lebih pribadi dan cenderung didukung di berbagai browser.
Reporting API memberi tahu Anda tentang error yang terjadi di situs saat pengunjung menggunakannya. Dasbor ini memberi Anda visibilitas terkait intervensi browser, error browser, pelanggaran Kebijakan Keamanan Konten, pelanggaran COOP/COEP, peringatan penghentian, dan lainnya.
Reporting API versi baru telah tersedia. API baru lebih ramping dan lebih mungkin didukung di berbagai browser.
Ringkasan
Developer situs
Jika Anda sudah memiliki fungsi pelaporan untuk situs: bermigrasilah ke v1 menggunakan header baru (Reporting-Endpoints
), tetapi pertahankan 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
menghasilkan laporan.
Melaporkan developer layanan
Jika Anda mengelola layanan endpoint atau mengoperasikan layanan endpoint sendiri, Anda akan mendapatkan lebih banyak traffic saat Anda
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 Pencatatan Log Kesalahan Jaringan akan dikembangkan. Setelah tersedia, beralihlah dari Reporting API v0 ke mekanisme baru tersebut.
Demo dan kode
- Situs demo: Reporting API baru (v1)
- Kode untuk situs demo
Perbedaan antara v0 dan v1
Yang berubah
- Platform API 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 laporan berbeda.
Dengan v0, Anda dapat menetapkan endpoint pelaporan hanya pada beberapa respons. Dokumen lain (halaman) di origin tersebut akan otomatis menggunakan endpoint standby ini.
Dengan v1, Anda perlu menetapkan header Reporting-Endpoints
pada 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 migrasi.
- v0 tidak dan tidak akan didukung di semua browser. v1 kemungkinan besar akan didukung di beberapa browser pada masa mendatang.
Yang tidak berubah
- Format dan struktur laporan tidak berubah.
- Permintaan yang dikirim oleh browser ke endpoint tetap merupakan permintaan
POST
dariContent-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
terus mendapatkan akses ke semua laporan yang dapat diamati, dan formatnya identik.
Semua perbedaan antara v0 dan v1
Header Reporting API lama (v0)Report-To |
Header Reporting API (v1) baruReporting-Endpoints |
|
---|---|---|
Dukungan browser | Chrome 69+ dan Edge 69+. | Chrome 96+ dan Edge 96+. Firefox mendukung. Safari tidak keberatan. Lihat sinyal browser. |
Endpoints | Mengirim laporan ke beberapa pengumpul laporan (beberapa URL yang ditentukan per grup endpoint). | Mengirim laporan ke pengumpul 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 |
|
Tidak berubah, kecuali dari Network Error Logging (NEL): hal ini tidak didukung di Reporting API (v1) baru. |
Cakupan laporan | Asal Anda. Header Report-To dokumen memengaruhi dokumen (halaman) lain dari asal tersebut.
Kolom url laporan masih bervariasi per dokumen.
|
Dokumen. Header Reporting-Endpoints dokumen hanya memengaruhi dokumen tersebut.
Kolom url laporan masih bervariasi per dokumen.
|
Isolasi laporan (pengelompokan) | Berbagai dokumen (halaman) atau situs/origin yang menghasilkan laporan pada waktu yang hampir bersamaan dan yang memiliki endpoint pelaporan yang sama akan digabungkan. Dokumen tersebut akan dikirim dalam pesan yang sama ke endpoint pelaporan. |
|
Dukungan untuk load balancing / prioritas | Ya | Tidak |
Developer endpoint: Dapatkan lebih banyak traffic
Jika Anda telah menyiapkan server Anda sendiri sebagai endpoint pelaporan, atau jika mengembangkan atau mempertahankan kolektor laporan sebagai layanan, Anda akan mendapatkan lebih banyak traffic ke endpoint tersebut.
Hal ini karena laporan tidak dikelompokkan dalam Reporting API v1 seperti pada Reporting API v0. Oleh karena itu, saat developer aplikasi mulai bermigrasi ke Reporting API v1, jumlah laporan akan tetap sama, tetapi volume permintaan ke server endpoint akan meningkat.
Developer aplikasi: Bermigrasi ke Reporting-Endpoints
(v1)
Apa yang perlu Anda lakukan?
Menggunakan Reporting API (v1) yang baru memiliki beberapa manfaat ✅:
- Sinyal browser bersifat positif, yang berarti bahwa dukungan lintas browser dapat diharapkan untuk v1 (tidak seperti v0 yang hanya didukung di Chrome dan Edge).
- API-nya lebih ramping.
- Alat sedang dikembangkan untuk Reporting API (v1) yang 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 spesifik untuk pelaporan CSP. - Jika situs Anda belum menggunakan Reporting API, dan Anda kini menambahkan fungsi pelaporan:
gunakan Reporting API (v1) baru (header
Reporting-Endpoints
). Ada satu pengecualian untuk ini: jika Anda perlu menggunakan Network Error Logging, gunakanReport-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, gunakanReport-To
(v0) danReporting-Endpoints
(v1). v0 memberi Anda Network Error Logging dan v1 memberi Anda laporan tentang semua jenis lainnya.
Langkah migrasi
Sasaran Anda dalam migrasi ini adalah tidak kehilangan laporan yang sebelumnya Anda gunakan dengan v0.
Langkah 1 (lakukan sekarang): Gunakan kedua header:
Report-To
(v0) danReporting-Endpoints
(v1).Dengan ini, Anda akan 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 menggunakanReporting-Endpoints
, dan instance yang tidak akan dikembalikan keReport-To
. Format permintaan dan laporan sama untuk v0 dan v1.- Laporan dari klien Chrome dan Edge yang lebih baru berkat
Langkah 2 (lakukan sekarang): Pastikan header
Reporting-Endpoints
ditetapkan pada semua respons yang dapat menghasilkan laporan.Dengan v0, Anda dapat memilih untuk menetapkan endpoint pelaporan hanya pada beberapa respons, dan dokumen (halaman) lain di origin tersebut akan menggunakan endpoint "ambient" ini. Dengan v1, karena adanya perbedaan cakupan, Anda perlu menetapkan header
Reporting-Endpoints
pada semua respons yang mungkin menghasilkan laporan.Langkah 3 (mulai nanti): Setelah semua atau sebagian besar pengguna mengupdate ke penginstalan Chrome atau Edge yang lebih baru (96 dan yang lebih baru), hapus
Report-To
(v0) dan simpanReporting-Endpoints
saja.Satu pengecualian: jika Anda memerlukan laporan Pencatatan Log Error Jaringan, pertahankan
Report-To
hingga ada mekanisme baru untuk Logging Error Jaringan.
Lihat contoh kode di buku resep migrasi.
Langkah-langkah migrasi untuk pelaporan CSP
Ada dua cara untuk mengonfigurasi laporan pelanggaran Kebijakan Keamanan Konten:
- Dengan header CSP saja melalui perintah
report-uri
. Layanan ini memiliki dukungan browser yang luas, di Chrome, Firefox, Safari, dan Edge. Laporan dikirim dengan jenis kontenapplication/csp-report
dan memiliki format yang spesifik untuk CSP. Laporan ini disebut "Laporan CSP Level 2" dan tidak bergantung pada Reporting API. - Dengan Reporting API, Anda dapat melakukannya melalui header
Report-To
(lama) atauReporting-Endpoints
yang lebih baru (v1). Fitur ini hanya didukung di Chrome dan Edge. Permintaan laporan memiliki format yang sama dengan permintaan Reporting API lainnya, danapplication/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 untuk semua jenis laporan serta menetapkan endpoint generik (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 pendekatan Reporting API (Report-To
atau lebih baik lagi, Reporting-Endpoints
) untuk mendapatkan laporan pelanggaran CSP dari beberapa browser. Dalam browser yang mengenali report-uri
dan report-to
, report-uri
akan diabaikan jika ada report-to
. Di browser yang hanya mengenali report-uri
, hanya report-uri
yang akan dipertimbangkan.
Langkah 1 (lakukan sekarang): Jika Anda belum menambahkannya, tambahkan
report-to
bersamareport-uri
. Browser yang hanya mendukungreport-uri
(Firefox) akan menggunakanreport-uri
, dan browser yang juga mendukungreport-to
(Chrome, Edge) akan menggunakanreport-to
. Untuk menentukan endpoint bernama yang akan Anda gunakan direport-to
, gunakan headerReport-To
danReporting-Endpoints
. Tindakan ini akan memastikan Anda mendapatkan laporan dari klien Chrome dan Edge versi lama dan baru.Langkah 3 (mulai nanti): Setelah semua atau sebagian besar pengguna mengupdate ke penginstalan Chrome atau Edge yang lebih baru (96 dan yang lebih baru), hapus
Report-To
(v0) dan simpanReporting-Endpoints
saja. Simpanreport-uri
agar Anda masih mendapatkan laporan untuk browser yang hanya mendukungnya.
Lihat contoh kode untuk langkah-langkah tersebut dalam Migrasi pelaporan CSP.
Migrasi: kode contoh
Ringkasan
Jika Anda menggunakan Reporting API (v0) lama guna 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 sendiri header kebijakan ini saat bermigrasi
ke Reporting API v1. Yang Anda butuhkan adalah melakukan migrasi dari header Report-To
lama ke header
Reporting-Endpoints
yang baru.
Jika menggunakan Reporting API (v0) lama untuk mendapatkan laporan pelanggaran CSP (header Content-Security-Policy
), Anda mungkin perlu menyesuaikan Content-Security-Policy
sebagai bagian dari migrasi 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"
Perlu diketahui bahwa dengan v1, Anda tetap dapat mengirim jenis laporan tertentu ke endpoint tertentu. Namun, 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 dengan Reporting API (postingan utama di Reporting API)
- Spesifikasi: Reporting API lama (v0)
- Spesifikasi: Reporting API baru (v1)
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 dalam artikel ini.