Verdict Reference

Setiap keputusan Fraud Prevention — sama ada dihantar ke panggil balik onVerdict anda dalam Web SDK atau ditarik daripada Data API — ialah objek BotVerdict yang sama. Halaman ini mendokumenkan setiap medan dan cara bertindak ke atasnya.

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

Medan

Medan	Jenis	Keterangan
is_bot	boolean	Keputusan utama. true = lawatan dinilai sebagai trafik automatik atau tidak sah; false = ia kelihatan seperti orang sebenar. Inilah medan tunggal yang kebanyakan integrasi bercabang ke atasnya.
score	number (0–100)	Betapa mencurigakan lawatan itu. Lebih tinggi bermakna lebih mencurigakan. Gunakannya untuk menetapkan ambang anda sendiri — cth. kecualikan lawatan melebihi had potong yang anda pilih. Nilai tepatnya dihasilkan oleh model risiko kami dan tidak bertujuan untuk dirungkai-balik.
level	enum	Jalur kasar bagi score: low, medium, high, critical. Mudah apabila anda mahukan baldi (bucket) dan bukannya nombor mentah.
action	enum	Pengendalian yang disyorkan kami untuk lawatan itu: record_only, challenge, flag, atau deny. Lihat di bawah. Layan nilai yang tidak dikenali sebagai flag, supaya integrasi anda terus berfungsi jika nilai baharu ditambah.
reasons	string[]	Sehingga tiga kategori sebab umum yang menerangkan keputusan berisiko. Kosong untuk lawatan bersih.
consistency	object	Kesimpulan konsistensi merentas isyarat. Baca consistency.ok (boolean): true = isyarat lawatan sepadan seperti yang dijangka; false = sesuatu tidak menjadi dan lawatan itu wajar diteliti dengan lebih lanjut. Pecahan dalaman di sebalik kesimpulan ini tidak didedahkan.
degraded	boolean	true apabila keputusan tidak dapat dikira sepenuhnya (perkhidmatan tidak dapat dicapai, ralat, dsb.) dan sandaran konservatif dikembalikan. Layan keputusan degraded sebagai "tidak diketahui", bukan "bersih".
verdict_id	string	Id unik keputusan ini. Gunakannya untuk mencari keputusan kemudian dengan Data API.
verdict_token	string	Bukti bertandatangan bagi keputusan ini, untuk disahkan oleh pelayan anda. Lihat Pengesahan sebelah pelayan. Tiada pada keputusan sandaran.
verdict_token_exp	number	Masa Unix (saat) apabila verdict_token tamat tempoh.

action — apa yang perlu dilakukan

action ialah cadangan kami; anda kekal mengawal keputusan akhir.

action	Maksud	Apa yang perlu dilakukan
record_only	Lawatan kelihatan normal.	Teruskan seperti biasa. Cuma log keputusan untuk pelaporan dan penyelarasan.
flag	Lawatan mencurigakan tetapi tidak pasti buruk secara muktamad.	Terus layan halaman, tetapi tandakan lawatan sebagai berkualiti rendah — kecualikannya daripada metrik anda, asingkannya daripada aliran hiliran, dan timbangkannya dalam keputusan anda sendiri (cth. atribusi penukaran atau sejauh mana anda mempercayai lawatan itu).
challenge	Lawatan mencapai ambang challenge anda (risiko tinggi secara lalai).	Minta satu pengesahan tambahan sebelum melayan pelawat sebagai manusia. Apabila tindakan pengendalian aplikasi anda ditetapkan kepada challenge, Web SDK menjalankannya untuk anda (lihat Escalation); jika tidak, gunakan pintu kawalan anda sendiri.
deny	Lawatan sepadan dengan peraturan sekatan — contohnya entri senarai sekat atau polisi yang anda konfigurasikan untuk menyekat.	Jangan layan kandungan yang dilindungi. Tiada challenge ditawarkan. Versi SDK lama menghantar nilai ini tanpa perubahan, jadi kendalikannya dalam onVerdict.

Tindakan pengendalian yang boleh dikonfigurasi

Apa yang action laporkan untuk lawatan berisiko tinggi ialah konfigurasi setiap aplikasi, ditetapkan dalam papan pemuka di bawah butiran aplikasi anda. Keputusan bersifat berwibawa-pelayan (server-authoritative): action hanya menjadi challenge atau flag apabila lawatan mencapai jalur berisiko tinggi dan aplikasi anda dikonfigurasi dengan tindakan yang sepadan. Di bawah jalur itu, keputusan kekal record_only.

Tetapan	action dikembalikan pada risiko tinggi	Maksud
record_only (lalai)	record_only	Rekod sahaja. Keputusan dilog untuk pelaporan dan penyelarasan; tiada apa yang diminta daripada pelawat.
challenge	challenge	Cetuskan CAPTCHA pengesahan semula. Web SDK memunculkan satu challenge (gaya dikawal oleh challengeConfig SDK).
flag	flag	Tandakan lawatan. Keputusan membawa flag; integrasi anda memutuskan cara bertindak ke atasnya (sekat / asing / kendalikan).

Kerana keputusan dibuat di bahagian pelayan, kod anda kekal mudah: baca verdict.action dalam onVerdict dan bertindak ke atasnya — teruskan, sekat, atau biarkan SDK mempersembahkan satu challenge. Anda tidak perlu menerbitkan semula risiko itu sendiri.

Ambang dan jenis pengesahan

Apabila tindakan ialah challenge, dua lagi tetapan muncul di bahagian papan pemuka yang sama:

• Ambang pengesahan — tahap risiko yang mula mengembalikan tindakan yang dikonfigurasi. Lalai ialah risiko tinggi ke atas. Mod ketat turut menggunakannya pada lawatan berisiko sederhana: lebih banyak pengikis dan ejen AI dihalang, tetapi lebih ramai pelawat sebenar melihat pengesahan.
• Jenis pengesahan — jenis CAPTCHA minimum yang dipaparkan semasa eskalasi: gelangsar (lalai), putar, klik atau klik 3D. Jenis yang lebih kuat lebih sukar diselesaikan oleh alat automasi dan AI.

escalate_result

Hadir selepas eskalasi captcha terurus berjalan — iaitu apabila action ialah challenge dan SDK menjalankan captcha. null apabila tiada eskalasi berjalan. Turut dihantar ke onEscalateDone(passed, detail).

medan	penerangan
passed	sama ada pelawat lulus captcha
token	captcha pass token — sahkannya di pihak pelayan untuk mengesahkan kelulusan (jangan hanya percaya passed daripada klien)
challenge_id	id challenge captcha
cid	click id yang dikaitkan dengan eskalasi ini, jika click token hadir

reasons — kategori sebab

reasons memberitahu anda, secara umum, mengapa sesuatu lawatan kelihatan berisiko. Ia memegang paling banyak tiga kategori, yang paling kuat dahulu. Ia tidak pernah mengandungi isyarat individu atau pecahan skor.

Kategori	Maksud
automation	Tanda-tanda alat automatik, seperti pelayar berskrip atau headless.
network	Rangkaian kelihatan berisiko atau tidak konsisten, seperti proksi, pusat data atau rangkaian penyamaran, atau alamat yang disekat.
abnormal_requests	Corak permintaan luar biasa, seperti terlalu banyak permintaan, kegagalan berulang, atau sejarah trafik automatik.
device	Peranti atau persekitarannya tidak boleh dipercayai, atau tidak dapat dikenali.
behavior	Lawatan tidak berkelakuan seperti manusia, contohnya langsung tiada interaksi atau pautan yang digunakan semula.
other	Sebarang sebab lain, termasuk peraturan anda sendiri dan keputusan sandaran.

Layan senarai ini sebagai penjelasan untuk pelaporan, bukan sebagai isyarat untuk membina peraturan. Sebaliknya, bercabang pada is_bot, action atau score. Kategori baharu mungkin ditambah kemudian.

Pengesahan sebelah pelayan

Apa sahaja yang diterima halaman boleh diubah oleh pelawat. Jika anda mengawal akses kandungan (hanya orang sebenar boleh melihat halaman, respons API atau muat turun), jangan percaya bendera is_bot dalam pelayar. Hantar verdict_token ke pelayan anda sendiri dan sahkannya di sana:

1. Dalam onVerdict, hantar verdict.verdict_token ke backend anda, contohnya dalam pengepala atau kuki.
2. Backend anda memanggil POST /v1/bot/verdict/verify dengan token dan alamat IP pelawat.
3. Layan kandungan hanya apabila respons mempunyai valid: true dan keputusan itu boleh diterima oleh anda (contohnya verdict.is_bot ialah false).

Token terikat kepada aplikasi anda, kepada keputusan ini dan kepada rangkaian pelawat, dan tamat tempoh selepas masa yang singkat (10 minit secara lalai). Secara lalai token boleh disemak berkali-kali, jadi satu token boleh meliputi paparan halaman bagi satu lawatan. Hantar consume: true apabila token mesti digunakan sekali sahaja, seperti untuk penghantaran borang.

Jika pelawat kemudian lulus challenge eskalasi, token masih menunjukkan keputusan asal. Sahkan juga captcha pass token daripada escalate_result dengan API captcha sebelah pelayan.

level lwn score

level hanyalah penjaluran bagi score, disediakan untuk kemudahan:

level	Gunakannya apabila
low	Layan sebagai trafik bersih.
medium	Sempadan — baik untuk direkod, pertimbangkan untuk mengecualikan daripada corong bernilai tinggi.
high	Sangat mencurigakan — tandai dan kecualikan.
critical	Hampir pasti tidak sah — tandai/kecualikan dan, idealnya, eskalasikan.

Pilih medan yang sesuai dengan saluran paip anda

• Pintu ya/tidak yang mudah → bercabang pada is_bot.
• Dipacu cadangan → bercabang pada action.
• Ambang tersuai → bercabang pada score (atau level untuk baldi).

Mengendalikan keputusan degraded

Apabila degraded ialah true, keputusan tidak dikira sepenuhnya. Sandaran sengaja dibuat konservatif (is_bot: false, action: record_only) supaya pengguna sebenar tidak pernah disekat. Untuk pelaporan, layan ini sebagai tidak diketahui dan bukan mengiranya sebagai trafik yang disahkan-bersih.

Langkah seterusnya

• Web SDK — terima keputusan pada halaman anda
• Data API — tarik keputusan dan statistik di bahagian pelayan