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

option	type	default	deskripsi
appKey	string	—	Wajib. Kunci aplikasi Fraud Prevention Anda.
domain	string	signal-v1.world-dynamic.com	Domain signal tempat SDK mengirim data.
tokenParam	string	_ctk	Parameter query URL tempat SDK membaca click token.
onVerdict	(v) => void	—	Dipanggil sekali dengan verdict akhir. Titik integrasi utama. init() juga mengembalikan Promise<BotVerdict>.
onError	(err) => void	—	Dipanggil jika terjadi kegagalan apa pun. SDK tidak pernah melempar exception ke halaman Anda.
onChallenge	(v) => creds | null | Promise<…>	—	Menimpa kredensial eskalasi: kembalikan { appKey, serverToken } milik Anda sendiri (serverToken diterbitkan oleh backend Anda), atau null untuk melewati eskalasi. Jika tidak diatur, kredensial default terbitan backend di verdict.escalate yang digunakan (tanpa konfigurasi).
challengeConfig	object	—	Tampilan/penempatan captcha: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Dipanggil ketika captcha eskalasi ditampilkan.
onEscalateDone	(passed, detail) => void	—	Dipanggil setelah eskalasi. passed = pengunjung berhasil melewatinya; detail = { token, challengeId, cid } untuk verifikasi sisi server atas kelulusan tersebut.

Eskalasi digerakkan oleh server. SDK menampilkan captcha hanya ketika action pada verdict server bernilai challenge dan aplikasi dikonfigurasi dengan aksi eskalasi yang sesuai — tidak ada sakelar sisi klien untuknya. Gunakan onChallenge untuk menyediakan kredensial Anda sendiri atau untuk melewati eskalasi, dan challengeConfig untuk mengatur tampilannya. Setelah pengunjung lolos, verifikasi hasilnya di backend Anda sendiri dengan detail.token (ditambah challenge_id/cid) — jangan hanya mempercayai flag passed sisi klien.

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 digerakkan oleh verdict server, bukan flag sisi klien — ia berjalan setiap kali action pada verdict bernilai challenge dan aplikasi memiliki aksi eskalasi yang dikonfigurasi.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // sebuah verifikasi tambahan sedang ditampilkan kepada pengunjung
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // pengunjung lolos pemeriksaan tambahan — verifikasi detail.token di backend Anda
    } else {
      // tidak lolos — pertahankan rekomendasi dari verdict asli
    }
  },
  onVerdict: function (verdict) {
    // jika pengunjung lolos eskalasi, verdict.is_bot diperbarui menjadi false
  },
});

Catatan:

• Eskalasi hanya terpicu ketika action verdict bernilai challenge. Untuk semua kunjungan lain tidak ada yang ditampilkan dan pengalaman pengunjung tidak terganggu.
• Secara default SDK menggunakan kredensial terbitan backend di verdict.escalate (tanpa konfigurasi). Gunakan onChallenge untuk menyediakan { appKey, serverToken } milik Anda sendiri atau untuk melewati eskalasi, dan challengeConfig untuk mengatur tampilannya.
• Setelah lolos, verifikasi detail.token (ditambah challenge_id/cid) di backend Anda sendiri — jangan hanya mempercayai flag passed sisi klien.
• 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