Web SDK Pencegahan penipuan

Web SDK Fraud Prevention berjalan pada halaman Anda — landing page, layar pendaftaran atau login, atau sumber daya terlindungi apa pun. Ia meminta verdict untuk kunjungan saat ini dan menyerahkannya kembali ke kode Anda, sehingga Anda dapat memutuskan apa yang harus dilakukan dengan trafik tersebut — mencatatnya, menandainya, atau meminta pengunjung satu verifikasi tambahan.

Mulai cepat

<!-- 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 sebuah Promise<BotVerdict>, sehingga Anda dapat pula meng-await alih-alih menggunakan onVerdict — keduanya menerima objek verdict yang sama.

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

Opsi

Opsi	Tipe	Default	Deskripsi
appKey	string	—	Kunci aplikasi Fraud Prevention Anda (wajib).
domain	string	default layanan	Endpoint layanan verdict. Biarkan tidak diatur kecuali Anda diberi domain khusus.
escalate	boolean	false	Mengizinkan Fraud Prevention meminta pengunjung satu verifikasi tambahan ketika sebuah kunjungan tampak berisiko tinggi. Lihat Eskalasi.
collectWindowMs	number	1200	Berapa lama (ms) SDK mengamati kunjungan sebelum meminta verdict. Jendela lebih panjang menghasilkan verdict yang lebih meyakinkan dengan biaya sedikit penundaan.
onVerdict	(v) => void	—	Dipanggil sekali dengan verdict akhir. Titik integrasi utama.
onError	(err) => void	—	Dipanggil jika terjadi kesalahan apa pun. SDK tidak pernah melempar exception ke halaman Anda.
onEscalate	(displayType) => void	—	Dipanggil ketika verifikasi tambahan ditampilkan (hanya saat escalate: true).
onEscalateDone	(passed) => void	—	Dipanggil setelah verifikasi tambahan selesai; passed bernilai true jika pengunjung lolos.

Skenario sumber trafik

Jika pihak ketiga mengirimkan pengunjung kepada Anda dan kedua belah pihak perlu merekonsiliasi pada kesimpulan per-klik, SDK juga dapat membaca click token dari URL halaman. Itu spesifik untuk alur trafik berbayar — lihat panduan Penipuan iklan.

Menggunakan verdict

onVerdict menerima sebuah objek BotVerdict. Dua field yang paling sering Anda pakai:

• verdict.is_bot — true ketika kunjungan dinilai sebagai otomatis/tidak valid.
• verdict.action — apa yang kami rekomendasikan untuk 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 daftar field lengkap dan penanganan yang direkomendasikan di Referensi verdict.

Eskalasi

Ketika sebuah kunjungan tampak berisiko tinggi, Fraud Prevention dapat meminta pengunjung menyelesaikan satu verifikasi tambahan sebelum Anda memperlakukan mereka sebagai pengguna nyata. Ini bersifat opt-in.

Aktifkan 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
  },
});

Catatan:

• Eskalasi hanya terpicu ketika action verdict bernilai challenge. Untuk semua kunjungan lain tidak ada yang ditampilkan dan pengalaman pengunjung tidak terganggu.
• Jika pengunjung lolos verifikasi tambahan, verdict yang dikirim ke onVerdict mencerminkan hal itu (diperlakukan sebagai manusia).
• Eskalasi fail open: jika verifikasi tambahan tidak dapat dimuat atau ditampilkan, SDK mempertahankan verdict asli alih-alih memblokir halaman Anda.

INFO

Fraud Prevention tidak pernah memutuskan untuk Anda. Bahkan pada challenge/flag, kode Anda tetap mengendalikan apakah kunjungan diteruskan — SDK hanya menampilkan verdict dan, opsional, menjalankan verifikasi tambahan.

Ketahanan

Jika layanan verdict tidak terjangkau atau terjadi kesalahan apa pun, SDK mengembalikan verdict degraded (degraded: true) alih-alih menggagalkan halaman Anda. Verdict degraded bersifat konservatif (is_bot: false, action: record_only) sehingga tidak pernah memblokir pengguna nyata. Periksa verdict.degraded jika Anda ingin memperlakukan kunjungan tersebut secara khusus.

Langkah berikutnya

• Referensi verdict — setiap field dan cara menindaknya
• Data API — tarik dan rekonsiliasi verdict di sisi server