Fraud Prevention Web SDK

Fraud Prevention Web SDK berjalan pada halaman anda — halaman pendaratan, skrin pendaftaran atau log masuk, atau mana-mana sumber yang dilindungi. Ia meminta keputusan untuk lawatan semasa dan menyerahkannya semula kepada kod anda, supaya anda boleh memutuskan apa yang hendak dilakukan dengan trafik itu — rekodkannya, tandainya, atau minta pelawat satu pengesahan tambahan.

Mula pantas

<!-- Load the Fraud Prevention SDK -->
<script src="https://cdn.captcha-cdn.net/bot-signal.js"></script>

<script>
  BotSignal.init({
    appKey: 'YOUR_APP_KEY',
    onVerdict: function (verdict) {
      // verdict.is_bot, verdict.score, verdict.action — see Verdict Reference
      if (verdict.is_bot) {
        // exclude this visit from your funnel / suppress conversions
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>

BotSignal.init() juga mengembalikan Promise<BotVerdict>, jadi anda boleh await ia dan bukannya menggunakan onVerdict — kedua-duanya menerima objek keputusan yang sama.

const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });

Pilihan

Pilihan	Jenis	Lalai	Keterangan
appKey	string	—	Kunci aplikasi Fraud Prevention anda (diperlukan).
domain	string	lalai perkhidmatan	Titik akhir perkhidmatan keputusan. Biarkan tidak ditetapkan melainkan anda diberi domain khusus.
escalate	boolean	false	Benarkan Fraud Prevention meminta pelawat satu pengesahan tambahan apabila sesuatu lawatan kelihatan berisiko tinggi. Lihat Escalation.
collectWindowMs	number	1200	Berapa lama (ms) SDK memerhati lawatan sebelum meminta keputusan. Tetingkap yang lebih panjang menghasilkan keputusan yang lebih yakin dengan kos sedikit kelewatan.
onVerdict	(v) => void	—	Dipanggil sekali dengan keputusan akhir. Titik integrasi utama.
onError	(err) => void	—	Dipanggil jika ada apa-apa yang tidak kena. SDK tidak pernah membuang ralat ke halaman anda.
onEscalate	(displayType) => void	—	Dipanggil apabila pengesahan tambahan dipaparkan (hanya apabila escalate: true).
onEscalateDone	(passed) => void	—	Dipanggil selepas pengesahan tambahan selesai; passed ialah true jika pelawat melepasinya.

Senario sumber trafik

Jika pihak ketiga menghantar pelawat kepada anda dan kedua-dua belah pihak perlu menyelaras pada kesimpulan per klik, SDK juga boleh membaca token klik daripada URL halaman. Itu khusus untuk aliran trafik berbayar — lihat panduan Ad fraud.

Menggunakan keputusan

onVerdict menerima objek BotVerdict. Dua medan yang paling kerap anda gunakan:

• verdict.is_bot — true apabila lawatan dinilai sebagai automatik/tidak sah.
• verdict.action — apa yang kami cadangkan anda lakukan: record_only, challenge, atau flag.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // normal-looking traffic — proceed, just log the verdict
        break;
      case 'flag':
        // suspicious — keep serving the page but mark this visit as low quality
        markLowQuality(verdict);
        break;
      case 'challenge':
        // high risk — handled by escalation if enabled (see below)
        break;
    }
  },
});

Lihat senarai medan penuh dan pengendalian yang disyorkan dalam Verdict Reference.

Escalation

Apabila sesuatu lawatan kelihatan berisiko tinggi, Fraud Prevention boleh meminta pelawat melengkapkan satu pengesahan tambahan sebelum anda melayan mereka sebagai pengguna sebenar. Ini bersifat pilihan masuk (opt-in).

Dayakannya dengan escalate: true:

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to false
  },
});

Nota:

• Escalation hanya dicetuskan apabila action keputusan ialah challenge. Untuk semua lawatan lain, tiada apa yang dipaparkan dan pengalaman pelawat tidak terjejas.
• Jika pelawat melepasi pengesahan tambahan, keputusan yang dihantar ke onVerdict mencerminkan perkara itu (dilayan sebagai manusia).
• Escalation gagal terbuka (fails open): jika pengesahan tambahan tidak dapat dimuat atau dipaparkan, SDK mengekalkan keputusan asal dan bukannya menyekat halaman anda.

INFO

Fraud Prevention tidak pernah membuat keputusan untuk anda. Walaupun pada challenge/flag, kod anda kekal mengawal sama ada lawatan itu diteruskan — SDK hanya mengetengahkan keputusan dan, secara pilihan, menjalankan pengesahan tambahan.

Daya tahan

Jika perkhidmatan keputusan tidak dapat dicapai atau sebarang ralat berlaku, SDK mengembalikan keputusan degraded (degraded: true) dan bukannya menggagalkan halaman anda. Keputusan degraded bersifat konservatif (is_bot: false, action: record_only) supaya ia tidak pernah menyekat pengguna sebenar. Semak verdict.degraded jika anda mahu melayan lawatan tersebut secara khas.

Langkah seterusnya

• Verdict Reference — setiap medan dan cara bertindak ke atasnya
• Data API — tarik dan selaras keputusan di bahagian pelayan