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

option	type	default	keterangan
appKey	string	—	Diperlukan. Kunci aplikasi Fraud Prevention anda.
domain	string	signal-v1.world-dynamic.com	Domain signal yang SDK menghantar permintaan kepadanya.
tokenParam	string	_ctk	Parameter pertanyaan URL tempat SDK membaca token klik.
onVerdict	(v) => void	—	Dipanggil sekali dengan keputusan akhir. Titik integrasi utama. init() juga mengembalikan Promise<BotVerdict>.
onError	(err) => void	—	Dipanggil pada sebarang kegagalan. SDK tidak pernah membuang ralat ke halaman anda.
onChallenge	(v) => creds | null | Promise<…>	—	Ganti kelayakan escalation: kembalikan { appKey, serverToken } anda sendiri (serverToken dikeluarkan oleh backend anda), atau null untuk melangkau escalation. Jika tidak ditetapkan, kelayakan lalai yang dikeluarkan backend dalam verdict.escalate digunakan (tanpa konfigurasi).
challengeConfig	object	—	Penampilan/penempatan captcha: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Dipanggil apabila captcha escalation dipaparkan.
onEscalateDone	(passed, detail) => void	—	Dipanggil selepas escalation. passed = pelawat melepasinya; detail = { token, challengeId, cid } untuk pengesahan di bahagian pelayan bagi lulus tersebut.

Escalation dipacu oleh pelayan. SDK hanya memaparkan captcha apabila action keputusan pelayan ialah challenge dan aplikasi dikonfigurasikan dengan tindakan escalation yang sepadan — tiada togol di bahagian klien untuknya. Gunakan onChallenge untuk membekalkan kelayakan anda sendiri atau untuk melangkau escalation, dan challengeConfig untuk mengawal penampilannya. Selepas pelawat melepasinya, sahkan hasil pada backend anda sendiri dengan detail.token (serta challenge_id/cid) — jangan percaya hanya pada bendera passed di bahagian klien.

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 dipacu oleh keputusan pelayan, bukan bendera di bahagian klien — ia berjalan apabila action keputusan ialah challenge dan aplikasi mempunyai tindakan escalation yang dikonfigurasikan.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // pengesahan tambahan sedang dipaparkan kepada pelawat
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // pelawat melepasi semakan tambahan — sahkan detail.token pada backend anda
    } else {
      // tidak lepas — kekalkan cadangan keputusan asal
    }
  },
  onVerdict: function (verdict) {
    // jika pelawat melepasi escalation, verdict.is_bot dikemas kini kepada false
  },
});

Nota:

• Escalation hanya dicetuskan apabila action keputusan ialah challenge. Untuk semua lawatan lain, tiada apa yang dipaparkan dan pengalaman pelawat tidak terjejas.
• Secara lalai SDK menggunakan kelayakan yang dikeluarkan backend dalam verdict.escalate (tanpa konfigurasi). Gunakan onChallenge untuk membekalkan { appKey, serverToken } anda sendiri atau untuk melangkau escalation, dan challengeConfig untuk mengawal penampilannya.
• Selepas lulus, sahkan detail.token (serta challenge_id/cid) pada backend anda sendiri — jangan percaya hanya pada bendera passed di bahagian klien.
• 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