Referensi verdict

Setiap verdict Fraud Prevention — baik yang dikirim ke callback onVerdict Anda di Web SDK maupun yang ditarik dari Data API — adalah objek BotVerdict yang sama. Halaman ini mendokumentasikan setiap field dan cara menindaknya.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "consistency": { "ok": true },
  "reasons": [],
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Field

Field	Tipe	Deskripsi
is_bot	boolean	Verdict utama. true = kunjungan dinilai sebagai trafik otomatis atau tidak valid; false = tampak seperti orang sungguhan. Ini adalah field tunggal yang menjadi dasar percabangan sebagian besar integrasi.
score	number (0–100)	Seberapa mencurigakan kunjungan tersebut. Semakin tinggi berarti semakin mencurigakan. Gunakan untuk menetapkan ambang batas Anda sendiri — mis. mengeluarkan kunjungan di atas titik potong yang Anda pilih. Nilai persisnya dihasilkan oleh model risiko kami dan tidak dimaksudkan untuk direkayasa balik.
level	enum	Pita kasar dari score: low, medium, high, critical. Praktis ketika Anda menginginkan kelompok alih-alih angka mentah.
action	enum	Penanganan yang kami rekomendasikan untuk kunjungan: record_only, challenge, flag, atau deny. Lihat di bawah. Perlakukan nilai yang tidak dikenal sebagai flag, agar integrasi Anda tetap berfungsi jika nilai baru ditambahkan.
consistency	object	Kesimpulan konsistensi lintas-sinyal. Baca consistency.ok (boolean): true = sinyal kunjungan selaras sebagaimana diharapkan; false = ada yang tidak cocok dan kunjungan layak diperiksa lebih lanjut. Rincian internal di balik kesimpulan ini tidak diekspos.
degraded	boolean	true ketika verdict tidak dapat dihitung sepenuhnya (layanan tidak terjangkau, error, dll.) dan fallback konservatif dikembalikan. Perlakukan verdict degraded sebagai "tidak diketahui", bukan "bersih".
reasons	string[]	Hingga tiga kategori alasan umum yang menjelaskan verdict berisiko. Kosong untuk kunjungan bersih.
verdict_id	string	Id unik verdict ini. Gunakan untuk mencari verdict ini nanti dengan Data API.
verdict_token	string	Bukti bertanda tangan atas verdict ini, untuk diverifikasi oleh server Anda. Lihat Verifikasi sisi server. Tidak ada pada verdict fallback.
verdict_token_exp	number	Waktu Unix (detik) saat verdict_token kedaluwarsa.

action — apa yang harus dilakukan

action adalah rekomendasi kami; Anda tetap mengendalikan keputusan akhir.

action	Arti	Apa yang harus dilakukan
record_only	Kunjungan tampak normal.	Lanjutkan seperti biasa. Cukup catat verdict untuk pelaporan dan rekonsiliasi.
flag	Kunjungan mencurigakan tetapi belum pasti buruk.	Tetap sajikan halaman, tetapi tandai kunjungan sebagai kualitas rendah — keluarkan dari metrik Anda, pisahkan dari alur hilir, dan pertimbangkan dalam keputusan Anda sendiri (mis. atribusi konversi atau seberapa besar Anda mempercayai kunjungan tersebut).
challenge	Kunjungan mencapai ambang verifikasi Anda (risiko tinggi secara default).	Minta satu verifikasi tambahan sebelum memperlakukan pengunjung sebagai manusia. Jika action penanganan aplikasi Anda diatur ke challenge, Web SDK menjalankannya untuk Anda (lihat Eskalasi); jika tidak, terapkan gerbang Anda sendiri.
deny	Kunjungan cocok dengan aturan blokir — misalnya entri blocklist atau kebijakan yang Anda konfigurasikan untuk memblokir.	Jangan sajikan konten yang dilindungi. Tidak ada challenge yang ditawarkan. Versi SDK lama meneruskan nilai ini apa adanya, jadi tangani di onVerdict.

Action penanganan yang dapat dikonfigurasi

Apa yang dilaporkan action untuk kunjungan berisiko tinggi adalah konfigurasi per-aplikasi, diatur di dashboard pada detail aplikasi Anda. Verdict bersifat otoritatif di server: action baru menjadi challenge atau flag ketika kunjungan mencapai pita berisiko tinggi dan aplikasi Anda dikonfigurasi dengan action yang sesuai. Di bawah pita itu, verdict tetap record_only.

Pengaturan	action yang dikembalikan pada risiko tinggi	Arti
record_only (default)	record_only	Hanya mencatat. Verdict dicatat untuk pelaporan dan rekonsiliasi; tidak ada yang diminta dari pengunjung.
challenge	challenge	Memicu CAPTCHA verifikasi ulang. Web SDK memunculkan challenge (penataannya dikendalikan oleh challengeConfig SDK).
flag	flag	Menandai kunjungan. Verdict membawa flag; integrasi Anda memutuskan cara menindaknya (blokir / pisahkan / tangani).

Karena keputusan dibuat di sisi server, kode Anda tetap sederhana: baca verdict.action di onVerdict dan tindaki — lanjutkan, blokir, atau biarkan SDK menampilkan challenge. Anda tidak perlu menurunkan ulang risiko sendiri.

Ambang dan jenis verifikasi

Saat tindakan adalah challenge, dua pengaturan lagi muncul di bagian dasbor yang sama:

• Ambang verifikasi — tingkat risiko mulai dari mana tindakan yang dikonfigurasi dikembalikan. Default-nya risiko tinggi ke atas. Mode ketat juga menerapkannya pada kunjungan berisiko sedang: lebih banyak scraper dan agen AI dihentikan, tetapi lebih banyak pengunjung nyata melihat verifikasi.
• Jenis verifikasi — jenis CAPTCHA minimum yang ditampilkan saat eskalasi: penggeser (default), putar, klik, atau klik 3D. Jenis yang lebih kuat lebih sulit dipecahkan alat otomatis dan AI.

escalate_result

Muncul setelah eskalasi captcha terkelola berjalan — yaitu ketika action bernilai challenge dan SDK menjalankan captcha. null jika tidak ada eskalasi yang berjalan. Juga dikirim ke onEscalateDone(passed, detail).

field	deskripsi
passed	apakah pengunjung lolos captcha
token	captcha pass token — verifikasi di sisi server untuk memastikan kelulusan (jangan hanya percaya passed dari klien)
challenge_id	id challenge captcha
cid	click id yang terkait dengan eskalasi ini, jika ada click token

reasons — kategori alasan

reasons menjelaskan secara umum mengapa sebuah kunjungan tampak berisiko. Isinya paling banyak tiga kategori, dari yang terkuat. Isinya tidak pernah berupa sinyal individual atau rincian skor.

Kategori	Arti
automation	Tanda-tanda alat otomatis, seperti browser yang dijalankan skrip atau headless.
network	Jaringan tampak berisiko atau tidak konsisten, seperti proxy, jaringan data center atau anonimisasi, atau alamat yang diblokir.
abnormal_requests	Pola permintaan yang tidak biasa, seperti terlalu banyak permintaan, kegagalan berulang, atau riwayat trafik otomatis.
device	Perangkat atau lingkungannya tidak dapat dipercaya, atau tidak dapat dikenali.
behavior	Kunjungan tidak berperilaku seperti manusia, misalnya tidak ada interaksi sama sekali atau link yang dipakai ulang.
other	Alasan lainnya, termasuk aturan Anda sendiri dan verdict fallback.

Perlakukan daftar ini sebagai penjelasan untuk pelaporan, bukan sebagai sinyal untuk membangun aturan. Lakukan percabangan berdasarkan is_bot, action, atau score. Kategori baru dapat ditambahkan nanti.

Verifikasi sisi server

Apa pun yang diterima halaman dapat diubah oleh pengunjung. Jika Anda membatasi akses konten (hanya orang sungguhan yang boleh melihat halaman, respons API, atau unduhan), jangan mempercayai flag is_bot di browser. Kirim verdict_token ke server Anda sendiri dan verifikasi di sana:

1. Di onVerdict, kirim verdict.verdict_token ke backend Anda, misalnya di header atau cookie.
2. Backend Anda memanggil POST /v1/bot/verdict/verify dengan token dan alamat IP pengunjung.
3. Sajikan konten hanya jika respons berisi valid: true dan verdict dapat Anda terima (misalnya verdict.is_bot bernilai false).

Token terikat ke aplikasi Anda, ke verdict ini, dan ke jaringan pengunjung, serta kedaluwarsa setelah waktu singkat (10 menit secara default). Secara default token dapat diperiksa berkali-kali, sehingga satu token dapat mencakup tampilan halaman dalam satu kunjungan. Kirim consume: true jika token hanya boleh dipakai sekali, misalnya untuk pengiriman formulir.

Jika pengunjung kemudian lolos challenge eskalasi, token tetap menunjukkan verdict asli. Verifikasi juga pass token captcha dari escalate_result dengan API sisi server captcha.

level vs score

level hanyalah pengelompokan dari score, disediakan untuk kemudahan:

level	Gunakan ketika
low	Perlakukan sebagai trafik bersih.
medium	Ambang — boleh dicatat, pertimbangkan mengeluarkan dari funnel bernilai tinggi.
high	Sangat mencurigakan — tandai dan keluarkan.
critical	Hampir pasti tidak valid — tandai/keluarkan dan, idealnya, eskalasikan.

Pilih field yang sesuai dengan pipeline Anda

• Gerbang ya/tidak sederhana → bercabang pada is_bot.
• Berbasis rekomendasi → bercabang pada action.
• Ambang kustom → bercabang pada score (atau level untuk kelompok).

Menangani verdict degraded

Ketika degraded bernilai true, verdict tidak dihitung sepenuhnya. Fallback-nya sengaja dibuat konservatif (is_bot: false, action: record_only) sehingga pengguna nyata tidak pernah diblokir. Untuk pelaporan, perlakukan ini sebagai tidak diketahui alih-alih menghitungnya sebagai trafik yang dipastikan bersih.

Langkah berikutnya

• Web SDK — menerima verdict pada halaman Anda
• Data API — tarik verdict dan statistik di sisi server