Halaman ini diterjemahkan oleh Cloud Translation API.

Memantau aplikasi web dengan Reporting API

Gunakan Reporting API untuk memantau pelanggaran keamanan, panggilan API yang tidak digunakan lagi, dan lainnya.

Maud Nalpas

Beberapa error hanya terjadi dalam produksi. Anda tidak akan melihatnya secara lokal atau selama karena pengguna nyata, jaringan nyata, dan perangkat nyata mengubah permainan. Reporting API membantu mendeteksi beberapa error tersebut, seperti karena pelanggaran keamanan atau API yang tidak digunakan lagi dan akan segera dihentikan panggilan di situs Anda, dan mengirimkannya ke endpoint yang telah yang ditentukan.

Ini memungkinkan Anda mendeklarasikan apa yang ingin Anda pantau melalui header HTTP, dan dioperasikan oleh browser.

Dengan menyiapkan Reporting API, Anda bisa merasa tenang karena saat pengguna jenis kesalahan ini, yang akan Anda ketahui, sehingga Anda dapat memperbaikinya.

Postingan ini membahas apa yang dapat dilakukan API ini dan cara menggunakannya. Ayo kita mulai!

Demo dan kode

Lihat cara kerja Reporting API mulai dari Chrome 96 dan yang lebih baru (Chrome Beta atau Canary, per Oktober 2021).

Ringkasan

Diagram yang merangkum langkah-langkah di bawah ini, mulai dari pembuatan laporan hingga akses laporan oleh developer — Cara laporan dibuat dan dikirim.

Anggaplah situs Anda, site.example, memiliki Kebijakan Keamanan Konten dan Kebijakan Dokumen. Tidak tahu apa fungsinya? Tidak apa-apa, Anda masih akan memahami contoh ini.

Anda memutuskan untuk memantau situs untuk mengetahui kapan kebijakan tersebut dilanggar, tetapi juga karena Anda ingin memperhatikan API yang tidak digunakan lagi atau yang akan segera tidak digunakan lagi oleh codebase Anda.

Untuk melakukannya, konfigurasikan header Reporting-Endpoints, dan petakan endpoint ini nama melalui perintah report-to dalam kebijakan Anda jika diperlukan.

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

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

Sesuatu yang tidak terduga terjadi, dan kebijakan ini dilanggar untuk beberapa pelanggan.

Contoh pelanggaran

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, dimuat oleh index.html

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

Browser menghasilkan laporan pelanggaran CSP, laporan pelanggaran Kebijakan Dokumen, dan Penghentian Penggunaan yang mencatat masalah tersebut.

Dengan penundaan singkat—hingga satu menit—browser kemudian mengirimkan laporan ke endpoint yang dikonfigurasi untuk jenis pelanggaran ini. Laporan dikirim out-of-band oleh browser itu sendiri (bukan oleh server atau situs Anda).

Endpoint menerima laporan ini.

Anda kini dapat mengakses laporan di endpoint tersebut dan memantau apa yang salah. Anda siap untuk mulai memecahkan masalah yang memengaruhi pengguna Anda.

Contoh laporan

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

Kasus penggunaan dan jenis laporan

Reporting API dapat dikonfigurasi untuk membantu Anda memantau berbagai jenis peringatan atau masalah yang menarik yang terjadi di seluruh situs Anda:

Jenis laporan	Contoh situasi saat laporan akan dibuat
Pelanggaran CSP (khusus Level 3)	Anda telah menetapkan `Content-Security-Policy` (CSP) di salah satu halaman, tetapi halaman tersebut mencoba memuat skrip yang tidak diizinkan oleh CSP Anda.
Pelanggaran COOP	Anda telah menetapkan `Cross-Origin-Opener-Policy` di halaman, tetapi jendela lintas origin mencoba berinteraksi langsung dengan dokumen.
Pelanggaran COEP	Anda telah menetapkan `Cross-Origin-Embedder-Policy` di sebuah halaman, tetapi dokumen menyertakan iframe lintas origin yang belum ikut dimuat oleh dokumen lintas origin.
Pelanggaran Kebijakan Dokumen	Halaman memiliki kebijakan dokumen yang mencegah penggunaan `document.write`, tetapi skrip mencoba memanggil `document.write`.
Pelanggaran kebijakan izin	Halaman memiliki kebijakan izin yang mencegah penggunaan mikrofon, dan skrip yang meminta input audio.
Peringatan penghentian penggunaan	Halaman menggunakan API yang tidak digunakan lagi atau tidak akan digunakan lagi; layanan itu memanggilnya secara langsung atau melalui skrip pihak ketiga tingkat atas.
Intervensi	Halaman mencoba melakukan sesuatu yang tidak diikuti oleh browser, karena alasan keamanan, performa, atau pengalaman pengguna. Contoh di Chrome: halaman menggunakan `document.write` di jaringan yang lambat atau memanggil `navigator.vibrate` dalam frame lintas origin yang belum berinteraksi dengan pengguna.
Tabrakan	Browser error saat situs Anda dibuka.

Laporan

Seperti apa tampilan laporan?

Browser akan mengirimkan laporan ke endpoint yang telah Anda konfigurasi. Library ini mengirimkan permintaan yang terlihat seperti berikut:

POST
Content-Type: application/reports+json

Payload permintaan ini adalah daftar laporan.

Contoh daftar laporan

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

Berikut ini data yang dapat Anda temukan di setiap laporan tersebut:

Kolom	Deskripsi
`age`	Jumlah milidetik antara stempel waktu laporan dan waktu saat ini.
`body`	Data laporan sebenarnya, diserialisasi ke dalam string JSON. Kolom yang terdapat dalam `body` laporan ditentukan oleh `type` laporan. ⚠️ Laporan berbagai jenis memiliki isi yang berbeda. Untuk melihat isi persis dari setiap jenis laporan, lihat endpoint pelaporan demo dan ikuti petunjuk untuk membuat contoh laporan.
`type`	Jenis laporan, misalnya `csp-violation` atau `coep`.
`url`	Alamat dokumen atau pekerja tempat laporan dibuat. Data sensitif seperti nama pengguna, sandi, dan fragmen akan dihapus dari URL ini.
`user_agent`	Header `User-Agent` permintaan tempat laporan dibuat.

Laporan dengan kredensial

Endpoint pelaporan yang memiliki asal yang sama dengan halaman yang membuat laporan akan menerima kredensial (cookie) dalam permintaan yang berisi laporan.

Kredensial dapat memberikan konteks tambahan yang berguna tentang laporan; untuk misalnya, apakah akun pengguna tertentu memicu error secara konsisten, atau jika suatu urutan tindakan yang dilakukan di halaman lain akan memicu laporan di halaman ini.

Kapan dan bagaimana browser mengirim laporan?

Laporan dikirim secara out-of-band dari situs Anda: browser mengontrol kapan dikirim ke endpoint yang telah dikonfigurasi. Tidak ada cara untuk mengontrol kapan browser mengirim laporan; komputer akan menangkap, mengantrekan, dan mengirimkannya secara otomatis waktu yang tepat.

Artinya, tidak ada masalah performa saat menggunakan Reporting API.

Laporan dikirim dengan penundaan—hingga satu menit—untuk meningkatkan kemungkinan pengiriman laporan dalam beberapa batch. Cara ini menghemat {i>bandwidth<i} untuk menyesuaikan dengan koneksi jaringan pengguna, yang penting untuk seluler. Browser juga dapat menunda pengiriman jika sibuk memproses prioritas yang lebih tinggi berfungsi, atau jika pengguna berada di jaringan yang lambat dan/atau padat pada saat itu.

Masalah pihak ketiga dan pihak pertama

Laporan yang dibuat karena pelanggaran atau penghentian penggunaan yang terjadi di halaman Anda akan dikirim ke endpoint yang telah Anda konfigurasi. Hal ini mencakup pelanggaran yang dilakukan oleh skrip pihak ketiga yang berjalan di halaman Anda.

Pelanggaran atau penghentian yang terjadi dalam iframe lintas origin yang disematkan di halaman Anda akan tidak dilaporkan ke endpoint Anda (setidaknya tidak secara default). iframe dapat disiapkan sendiri pelaporan dan bahkan laporan ke situs Anda—yaitu, layanan pelaporan—pihak pertama; tapi itu sudah habis ke situs yang dibingkai. Perhatikan juga bahwa sebagian besar laporan hanya dibuat jika kebijakan halaman dilanggar, dan bahwa kebijakan halaman serta kebijakan iframe berbeda.

Contoh dengan penghentian penggunaan

Jika header Reporting-Endpoint disiapkan di halaman Anda: API yang tidak digunakan lagi dan dipanggil oleh skrip pihak ketiga yang berjalan di halaman Anda akan dilaporkan ke endpoint. API yang tidak digunakan lagi dan dipanggil oleh iframe yang disematkan di halaman Anda tidak akan dilaporkan ke endpoint Anda. Laporan penghentian hanya akan dibuat jika server iframe telah menyiapkan Titik Akhir Pelaporan, dan laporan ini akan dikirim ke endpoint mana pun yang disiapkan server iframe.

Dukungan browser

Tabel di bawah meringkas dukungan browser untuk Reporting API v1, dengan Header Reporting-Endpoints. Dukungan browser untuk Reporting API v0 (header Report-To) adalah sama, kecuali untuk satu jenis laporan: Logging Error Jaringan tidak didukung di Reporting API yang baru. Baca panduan migrasi untuk mengetahui detailnya.

Jenis laporan	Chrome	iOS Chrome	Safari	Firefox	Edge
Pelanggaran CSP (khusus Level 3)*	✔ Ya	✔ Ya	✔ Ya	✘ Tidak	✔ Ya
Logging Error Jaringan	✘ Tidak	✘ Tidak	✘ Tidak	✘ Tidak	✘ Tidak
Pelanggaran COOP/COEP	✔ Ya	✘ Tidak	✔ Ya	✘ Tidak	✔ Ya
Semua jenis lainnya: Pelanggaran Kebijakan Dokumen, Penghentian Penggunaan, Intervensi, Error	✔ Ya	✘ Tidak	✘ Tidak	✘ Tidak	✔ Ya

Tabel ini hanya merangkum dukungan untuk report-to dengan header Reporting-Endpoints yang baru. Baca Tips migrasi pelaporan CSP jika Anda ingin bermigrasi ke Reporting-Endpoints.

Menggunakan Reporting API

Menentukan tujuan pengiriman laporan

Ada dua opsi:

Kirim laporan ke layanan pengumpul laporan yang sudah ada.
Kirim laporan ke pengumpul pelaporan yang Anda buat dan operasikan sendiri.

Opsi 1: Gunakan layanan pengumpul laporan yang sudah ada

Beberapa contoh layanan pengumpul laporan adalah:

Jika Anda mengetahui ada solusi lain, buka masalah untuk memberi tahu kami, dan kami akan memperbarui postingan ini.

Selain harga, pertimbangkan hal-hal berikut saat memilih pengumpul laporan: 🧐

Apakah kolektor ini mendukung semua jenis laporan? Misalnya, tidak semua solusi endpoint pelaporan mendukung laporan COOP/COEP.
Apakah Anda berkenan membagikan URL aplikasi Anda kepada pengumpul laporan pihak ketiga? Meskipun browser menghapus informasi sensitif dari URL tersebut, informasi sensitif mungkin bocor dengan cara ini. Jika ini terdengar terlalu berisiko untuk aplikasi Anda, operasikan endpoint pelaporan Anda sendiri.

Opsi 2: Membuat dan mengoperasikan pengumpul laporan Anda sendiri

Membangun server Anda sendiri yang menerima laporan bukanlah hal yang sepele. Untuk memulai, Anda dapat menelusuri boilerplate yang ringan. Layanan ini dibuat dengan Express dan dapat menerima dan menampilkan laporan.

Buka pengumpul laporan boilerplate.
Klik Remix to Edit agar project dapat diedit.
Sekarang Anda memiliki clone! Anda dapat menyesuaikannya untuk tujuan Anda sendiri.

Jika Anda tidak menggunakan boilerplate dan membangun server Anda sendiri dari awal:

Periksa permintaan POST dengan Content-Type sebesar application/reports+json untuk mengenali laporan yang dikirim oleh browser ke endpoint Anda.
Jika endpoint berada di asal yang berbeda dengan situs Anda, pastikan endpoint mendukung permintaan preflight CORS.

Opsi 3: Gabungkan Opsi 1 dan 2

Anda mungkin ingin mengizinkan penyedia tertentu menangani beberapa jenis laporan, tetapi memiliki solusi untuk orang lain.

Dalam kasus ini, tetapkan beberapa endpoint sebagai berikut:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Mengonfigurasi header `Reporting-Endpoints`

Tetapkan header respons Reporting-Endpoints. Nilainya harus berupa satu atau rangkaian nilai yang dipisahkan koma pasangan nilai kunci:

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

Jika Anda bermigrasi dari Reporting API versi lama ke Reporting API yang baru, sebaiknya Anda setel kedua Reporting-Endpoints dan Report-To. Lihat detailnya dalam panduan migrasi. Khususnya, jika Anda menggunakan pelaporan untuk Pelanggaran Content-Security-Policy hanya melalui perintah report-uri, periksa langkah-langkah migrasi untuk pelaporan CSP.

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

Kunci (nama endpoint)

Setiap kunci dapat menjadi nama pilihan Anda, seperti main-endpoint atau endpoint-1. Anda dapat memutuskan untuk menetapkan berbagai endpoint bernama untuk laporan yang berbeda yang sama—misalnya, my-coop-endpoint, my-csp-endpoint. Dengannya, Anda dapat merutekan laporan ke endpoint yang berbeda, bergantung pada jenisnya.

Jika Anda ingin menerima intervensi, penghentian, dan/atau error Google Cloud, tetapkan endpoint bernama default.

Jika header Reporting-Endpoints tidak menentukan endpoint default, laporan jenis ini tidak akan dikirim (meskipun laporan akan dibuat).

Poin penting: Meskipun namanya, default bukan pengganti endpoint. Misalnya, jika Anda menyiapkan report-to my-endpoint untuk Document-Policy dan menghilangkan untuk menentukan my-endpoint di Reporting-Endpoints, Document-Policy pelanggaran laporan akan dibuat tetapi tidak akan dikirim karena browser tidak tahu ke mana mereka akan diarahkan.

Nilai (URL)

Setiap nilai adalah URL pilihan Anda yang akan menjadi tujuan pengiriman laporan. URL untuk ditetapkan di sini tergantung pada apa yang Anda putuskan di Langkah 1.

URL endpoint:

Harus diawali dengan garis miring (/). Jalur relatif tidak didukung.
Dapat lintas origin; tetapi dalam hal ini, kredensial tidak dikirim bersama laporan.

Contoh

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Anda kemudian dapat menggunakan setiap endpoint yang dinamai dalam kebijakan yang sesuai, atau menggunakan satu endpoint tunggal di semua kebijakan.

Di mana header harus ditetapkan?

Di Reporting API baru, yang dibahas dalam pasca—laporan tercakup dalam dokumen. Ini berarti bahwa untuk satu model, origin, dokumen yang berbeda, seperti site.example/page1 dan site.example/page2, dapat mengirim laporan ke endpoint yang berbeda.

Untuk menerima laporan atas pelanggaran atau penghentian penggunaan yang dilakukan di halaman mana pun di menetapkan header sebagai middleware pada semua respons.

Berikut contoh di Express:

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

Catatan: Ini berbeda dari Reporting API (header Report-To) lama, tempat Anda dapat menyetel "ambient" endpoint untuk satu halaman, dan otomatis mendapatkan laporan untuk halaman apa pun pada asal yang sama. Jika Anda bermigrasi dari Reporting API lama ke Reporting API baru, lihat panduan migrasi.

Edit kebijakan Anda

Setelah header Reporting-Endpoints dikonfigurasi, tambahkan report-to di setiap header kebijakan yang pelanggarannya ingin Anda terima laporan. Nilai report-to harus berupa salah satu endpoint bernama yang Anda dikonfigurasi.

Anda dapat menggunakan beberapa endpoint untuk beberapa kebijakan, atau menggunakan endpoint di seluruh kebijakan.

Untuk setiap kebijakan, nilai report-to harus berupa salah satu endpoint bernama yang telah Anda konfigurasi.

report-to tidak diperlukan untuk penghentian, intervensi, dan error laporan. Laporan ini tidak terikat pada kebijakan apa pun. Kolom ini dibuat selama endpoint default disiapkan dan dikirim ke endpoint default ini.

Contoh

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

Peringatan: Mendapatkan sintaksis report-to dengan benar bisa menjadi hal yang rumit, karena tidak semua kebijakan menggunakan struktur {i>header<i} yang sama. Tergantung pada kebijakannya, sintaks yang tepat mungkin report-to=main-endpoint atau report-to main-endpoint. Buka demo untuk contoh kode.

Kode contoh

Untuk melihat semua ini dalam konteksnya, berikut adalah contoh server Node yang menggunakan Express dan menyatukan semua hal yang dibahas dalam artikel ini. Ini menunjukkan cara mengonfigurasi pelaporan untuk beberapa jenis laporan yang berbeda dan menampilkan hasilnya.

Men-debug penyiapan pelaporan

Sengaja membuat laporan

Saat menyiapkan Reporting API, Anda mungkin harus sengaja melanggar kebijakan Anda untuk memeriksa apakah laporan dibuat dan dikirim seperti yang diharapkan. Untuk melihat kode contoh yang melanggar kebijakan dan melakukan hal-hal buruk lainnya yang akan membuat laporan dari berbagai jenis, lihat demo.

Hemat waktu

Laporan mungkin dikirim dengan penundaan—sekitar satu menit, yang merupakan waktu lama saat melakukan proses debug. jadi Untungnya, saat {i>debugging<i} di Chrome, Anda dapat menggunakan penanda --short-reporting-delay untuk menerima laporan segera setelah dibuat.

Jalankan perintah ini di terminal Anda untuk mengaktifkan tanda ini:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Menggunakan DevTools

Di Chrome, gunakan DevTools untuk melihat laporan yang telah atau akan terkirim.

Mulai Oktober 2021, fitur ini bersifat eksperimental. Untuk menggunakannya, ikuti langkah-langkah berikut:

Gunakan Chrome versi 96 dan yang lebih baru (periksa dengan mengetik chrome://version di browser Anda)
Ketik atau tempel chrome://flags/#enable-experimental-web-platform-features di kolom URL Chrome.
Klik Enabled.
Mulai ulang browser.
Buka Chrome DevTools.
Di Chrome DevTools, buka Setelan. Di bagian Eksperimen, klik Aktifkan panel Reporting API di panel Application.
Muat ulang DevTools.
Muat ulang halaman Anda. Laporan yang dihasilkan oleh halaman tempat DevTools terbuka akan yang tercantum di Chrome DevTools' Application, di bagian Reporting API.

Screenshot DevTools yang mencantumkan laporan — Chrome DevTools menampilkan laporan yang dihasilkan di halaman Anda dan statusnya.

Status laporan

Kolom Status menunjukkan apakah laporan berhasil dikirim.

Status	Deskripsi
`Success`	Browser telah mengirimkan laporan dan endpoint membalas dengan kode berhasil (`200` atau kode respons sukses lainnya `2xx`).
`Pending`	Browser sedang mencoba mengirim laporan.
`Queued`	Laporan telah dibuat dan saat ini browser tidak mencoba mengirimkannya. Laporan muncul sebagai `Queued` dalam salah satu dari dua kasus berikut: Laporan tersebut baru dan browser menunggu untuk melihat apakah laporan lain tiba sebelum mencoba mengirimkannya. Laporan ini tidak baru; browser sudah mencoba mengirimkan laporan ini dan gagal, serta menunggu sebelum mencoba lagi.
`MarkedForRemoval`	Setelah mencoba beberapa saat (`Queued`), browser berhenti mencoba mengirim laporan dan akan segera menghapusnya dari daftar laporan untuk dikirim.

Laporan akan dihapus setelah beberapa saat, terlepas dari berhasilnya laporan tersebut dikirim.

Poin penting: Status Queued tidak selalu informatif, karena tidak secara tepat menunjukkan apakah pengiriman gagal atau belum dicoba. Menggunakan penundaan pelaporan singkat akan membantu: laporan yang tetap menampilkan Queued dalam kasus tersebut kemungkinan akan menunjukkan bahwa pengiriman gagal.

Pemecahan masalah

Apakah laporan tidak dibuat atau tidak dikirim seperti yang diharapkan ke endpoint Anda? Berikut beberapa tips untuk memecahkan masalah ini.

Laporan tidak dibuat

Laporan yang muncul di DevTools telah dibuat dengan benar. Jika laporan yang Anda harapkan tidak muncul dalam daftar ini:

Lihat report-to di kebijakan Anda. Jika konfigurasinya salah, laporan tidak akan dibuat. Buka bagian Mengedit kebijakan Anda untuk memperbaiki hal ini. Cara tambahan untuk memecahkan masalah ini adalah dengan memeriksa konsol DevTools di Chrome: jika muncul di konsol untuk pelanggaran yang Anda harapkan, ini berarti kebijakan Anda dikonfigurasi dengan benar.
Ingatlah bahwa hanya laporan yang dihasilkan untuk dokumen DevTools yang terbuka akan muncul dalam daftar ini. Salah satu contoh: jika situs Anda, site1.example menyematkan iframe site2.example yang melanggar kebijakan sehingga menghasilkan laporan, laporan ini akan muncul di DevTools hanya jika Anda membuka iframe di jendelanya sendiri dan membuka DevTools untuk jendela tersebut.

Laporan dibuat tetapi tidak dikirim atau tidak diterima

Bagaimana jika Anda dapat melihat laporan di DevTools, tetapi endpoint tidak menerimanya?

Poin penting: Karena laporan dikirim secara out-of-band oleh browser itu sendiri, bukan oleh situs tertentu, permintaan POST yang berisi laporan tidak ditampilkan di panel Jaringan pada Developer Tools.

Pastikan untuk menggunakan penundaan singkat. Mungkin alasan Anda tidak dapat melihat laporan adalah karena belum dikirim!
Periksa konfigurasi header Reporting-Endpoints Anda. Jika ada masalah, sebuah laporan yang yang dibuat dengan benar tidak akan dikirim. Di DevTools, status laporan akan tetap Queued (mungkin akan melompat ke Pending, lalu dengan cepat kembali ke Queued saat upaya pengiriman sebelumnya). Beberapa kesalahan umum yang dapat menyebabkan hal ini:
Endpoint digunakan tetapi tidak dikonfigurasi. Contoh:

Kode dengan kesalahan

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

Laporan pelanggaran Kebijakan Dokumen harus dikirim ke endpoint-1, tetapi nama endpoint ini tidak dikonfigurasi di Reporting-Endpoints.

Endpoint default tidak ada. Beberapa jenis laporan, seperti penghentian penggunaan dan intervensi laporan, hanya akan dikirim ke endpoint yang bernama default. Baca selengkapnya di Mengonfigurasi header Reporting-Endpoint.
Cari masalah di sintaksis header kebijakan Anda, seperti tidak ada tanda kutip. Lihat detail.

Periksa apakah endpoint Anda dapat menangani permintaan masuk.

Pastikan endpoint Anda mendukung permintaan preflight CORS. Jika tidak, aplikasi tidak dapat menerima laporan.
Uji perilaku endpoint Anda. Untuk melakukannya, alih-alih menghasilkan laporan secara manual, Anda dapat mengemulasi browser dengan mengirimkan permintaan endpoint yang terlihat seperti apa yang akan dikirim oleh browser. Jalankan perintah berikut:

curl --header "Content-Type: application/reports+json" \
  --request POST \
  --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
  YOUR_ENDPOINT

Endpoint Anda akan merespons dengan kode berhasil (200 atau kode respons sukses lainnya 2xx). Jika tidak, ada masalah dengan konfigurasinya.

Mekanisme pelaporan terkait

Hanya Laporan

Header kebijakan -Report-Only dan Reporting-Endpoints berfungsi bersama.

Endpoint yang dikonfigurasi di Reporting-Endpoints dan ditentukan di kolom report-to Content-Security-Policy, Cross-Origin-Embedder-Policy dan Cross-Origin-Opener-Policy, akan menerima laporan saat kebijakan ini dilanggar.

Endpoint yang dikonfigurasi di Reporting-Endpoints juga dapat ditentukan di Kolom report-to dari Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only dan Cross-Origin-Opener-Policy-Report-Only. Mereka juga akan menerima laporan jika kebijakan ini dilanggar.

Meskipun laporan dikirim dalam kedua kasus tersebut, header -Report-Only tidak menerapkan kebijakan: tidak ada yang akan rusak atau benar-benar diblokir, tetapi Anda akan menerima laporan tentang apa yang akan rusak atau diblokir.

Catatan: Jika Anda menggunakan header -Report-Only dan telah mengonfigurasi endpoint pelaporan melalui header lama Report-To, migrasikan ke Reporting-Endpoints jika memungkinkan. Baca selengkapnya di panduan migrasi.

`ReportingObserver`

ReportingObserver JavaScript API dapat membantu Anda mengamati peringatan sisi klien.

ReportingObserver dan header Reporting-Endpoints menghasilkan laporan yang terlihat sama, tetapi mereka memungkinkan kasus penggunaan yang sedikit berbeda.

Gunakan ReportingObserver jika:

Anda hanya ingin memantau penghentian penggunaan dan/atau intervensi browser. ReportingObserver menampilkan peringatan sisi klien seperti penghentian penggunaan dan intervensi browser, tetapi tidak seperti Reporting-Endpoints, mode ini tidak merekam jenis laporan lain seperti pelanggaran CSP atau COOP/COEP.
Anda perlu menanggapi pelanggaran ini secara real time. ReportingObserver membuat Anda dapat melampirkan callback ke peristiwa pelanggaran.
Anda perlu melampirkan informasi tambahan ke laporan untuk membantu proses {i>debugging<i}, melalui callback kustom.

Perbedaan lainnya adalah ReportingObserver hanya dikonfigurasi di sisi klien: Anda dapat menggunakannya bahkan jika Anda tidak memiliki kontrol atas {i>header<i} sisi server dan tidak dapat setel Reporting-Endpoints.

Bacaan lebih lanjut

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

Memantau aplikasi web dengan Reporting API

Demo dan kode

Ringkasan

Kasus penggunaan dan jenis laporan

Laporan

Seperti apa tampilan laporan?

Laporan dengan kredensial

Kapan dan bagaimana browser mengirim laporan?

Masalah pihak ketiga dan pihak pertama

Contoh dengan penghentian penggunaan

Dukungan browser

Menggunakan Reporting API

Menentukan tujuan pengiriman laporan

Opsi 1: Gunakan layanan pengumpul laporan yang sudah ada

Opsi 2: Membuat dan mengoperasikan pengumpul laporan Anda sendiri

Opsi 3: Gabungkan Opsi 1 dan 2

Mengonfigurasi header Reporting-Endpoints

Kunci (nama endpoint)

Nilai (URL)

Contoh

Di mana header harus ditetapkan?

Edit kebijakan Anda

Contoh

Kode contoh

Men-debug penyiapan pelaporan

Sengaja membuat laporan

Hemat waktu

Menggunakan DevTools

Status laporan

Pemecahan masalah

Laporan tidak dibuat

Laporan dibuat tetapi tidak dikirim atau tidak diterima

Mekanisme pelaporan terkait

Hanya Laporan

ReportingObserver

Bacaan lebih lanjut

Mengonfigurasi header `Reporting-Endpoints`

`ReportingObserver`