Fraud Prevention Web SDK

Fraud Prevention Web SDK chạy trên trang của bạn — một trang đích, màn hình đăng ký hoặc đăng nhập, hay bất kỳ tài nguyên cần bảo vệ nào. Nó yêu cầu một phán quyết cho lượt truy cập hiện tại và trả lại cho mã của bạn, để bạn quyết định làm gì với lưu lượng đó — ghi nhận, gắn cờ, hoặc yêu cầu khách truy cập làm thêm một lần xác minh.

Bắt đầu nhanh

<!-- Tải 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 — xem Tham chiếu phán quyết
      if (verdict.is_bot) {
        // loại lượt truy cập này khỏi phễu / chặn chuyển đổi của nó
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>

BotSignal.init() cũng trả về một Promise<BotVerdict>, nên bạn cũng có thể await nó thay vì dùng onVerdict — cả hai đều nhận cùng một đối tượng phán quyết.

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

Tùy chọn

option	type	default	Mô tả
appKey	string	—	Bắt buộc. Khóa ứng dụng Fraud Prevention của bạn.
domain	string	signal-v1.world-dynamic.com	Domain Signal mà SDK gửi yêu cầu đến.
tokenParam	string	_ctk	Tham số truy vấn trên URL mà SDK đọc click token từ đó.
onVerdict	(v) => void	—	Được gọi một lần với phán quyết cuối cùng. Điểm tích hợp chính. init() cũng trả về một Promise<BotVerdict>.
onError	(err) => void	—	Được gọi khi có bất kỳ lỗi nào. SDK không bao giờ ném ngoại lệ vào trang của bạn.
onChallenge	(v) => creds | null | Promise<…>	—	Ghi đè thông tin xác thực cho nâng cấp: trả về { appKey, serverToken } của riêng bạn (serverToken do backend của bạn cấp), hoặc null để bỏ qua nâng cấp xác minh. Nếu không đặt, sẽ dùng thông tin xác thực mặc định do backend cấp trong verdict.escalate (không cần cấu hình).
challengeConfig	object	—	Giao diện/vị trí của captcha: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Được gọi khi một captcha nâng cấp được hiển thị.
onEscalateDone	(passed, detail) => void	—	Được gọi sau khi nâng cấp xác minh kết thúc. passed = khách truy cập đã vượt qua; detail = { token, challengeId, cid } để xác minh phía máy chủ cho lần vượt qua đó.

Nâng cấp xác minh do máy chủ điều khiển. SDK chỉ hiển thị một captcha khi action trong phán quyết của máy chủ là challenge và ứng dụng được cấu hình với một escalation action tương ứng — không có công tắc phía client để bật/tắt. Dùng onChallenge để cung cấp thông tin xác thực của riêng bạn hoặc để bỏ qua nâng cấp xác minh, và challengeConfig để kiểm soát giao diện của nó. Sau khi khách truy cập vượt qua, hãy xác minh kết quả trên backend của riêng bạn bằng detail.token (cùng với challenge_id/cid) — đừng chỉ tin vào cờ passed ở phía client.

Kịch bản nguồn lưu lượng

Nếu một bên thứ ba gửi khách truy cập đến cho bạn và cả hai bên cần đối soát trên một kết luận theo từng lượt nhấp, SDK cũng có thể đọc một click token từ URL của trang. Điều đó đặc thù cho luồng lưu lượng trả phí — xem hướng dẫn Chống gian lận quảng cáo.

Sử dụng phán quyết

onVerdict nhận một đối tượng BotVerdict. Hai trường bạn sẽ dùng nhiều nhất:

• verdict.is_bot — true khi lượt truy cập bị đánh giá là tự động/không hợp lệ.
• verdict.action — điều chúng tôi khuyến nghị bạn làm: record_only, challenge, hoặc flag.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // lưu lượng trông bình thường — tiếp tục, chỉ ghi lại phán quyết
        break;
      case 'flag':
        // đáng ngờ — vẫn phục vụ trang nhưng đánh dấu lượt truy cập này là chất lượng thấp
        markLowQuality(verdict);
        break;
      case 'challenge':
        // rủi ro cao — được xử lý bởi nâng cấp xác minh nếu bật (xem bên dưới)
        break;
    }
  },
});

Xem danh sách trường đầy đủ và cách xử lý được khuyến nghị trong Tham chiếu phán quyết.

Nâng cấp xác minh

Khi một lượt truy cập trông có rủi ro cao, Fraud Prevention có thể yêu cầu khách truy cập hoàn thành một lần xác minh bổ sung trước khi bạn coi họ là người dùng thật. Điều này do phán quyết của máy chủ điều khiển, không phải bằng một cờ phía client — nó chạy bất cứ khi nào action trong phán quyết là challenge và ứng dụng có một escalation action được cấu hình.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // một lần xác minh bổ sung đang được hiển thị cho khách truy cập
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // khách truy cập đã vượt qua kiểm tra bổ sung — xác minh detail.token trên backend của bạn
    } else {
      // không vượt qua — giữ nguyên khuyến nghị của phán quyết ban đầu
    }
  },
  onVerdict: function (verdict) {
    // nếu khách truy cập vượt qua nâng cấp xác minh, verdict.is_bot được cập nhật thành false
  },
});

Lưu ý:

• Nâng cấp xác minh chỉ kích hoạt khi action của phán quyết là challenge. Với mọi lượt truy cập khác, không có gì được hiển thị và trải nghiệm của khách truy cập không bị động chạm.
• Mặc định SDK dùng thông tin xác thực do backend cấp trong verdict.escalate (không cần cấu hình). Dùng onChallenge để cung cấp { appKey, serverToken } của riêng bạn hoặc để bỏ qua nâng cấp xác minh, và challengeConfig để kiểm soát giao diện của nó.
• Sau khi vượt qua, hãy xác minh detail.token (cùng với challenge_id/cid) trên backend của riêng bạn — đừng chỉ tin vào cờ passed ở phía client.
• Nếu khách truy cập vượt qua lần xác minh bổ sung, phán quyết được chuyển tới onVerdict sẽ phản ánh điều đó (coi như người thật).
• Nâng cấp xác minh fail open: nếu lần xác minh bổ sung không thể tải hoặc hiển thị, SDK giữ nguyên phán quyết ban đầu thay vì chặn trang của bạn.

INFO

Fraud Prevention không bao giờ quyết định thay bạn. Ngay cả với challenge/flag, mã của bạn vẫn nắm quyền kiểm soát việc lượt truy cập có được tiếp tục hay không — SDK chỉ hiển thị phán quyết và, tùy chọn, chạy lần xác minh bổ sung.

Khả năng chịu lỗi

Nếu dịch vụ phán quyết không thể truy cập hoặc xảy ra bất kỳ lỗi nào, SDK trả về một phán quyết suy giảm (degraded) (degraded: true) thay vì làm hỏng trang của bạn. Một phán quyết suy giảm là thận trọng (is_bot: false, action: record_only) nên nó không bao giờ chặn người dùng thật. Hãy kiểm tra verdict.degraded nếu bạn muốn xử lý những lượt truy cập đó một cách đặc biệt.

Bước tiếp theo

• Tham chiếu phán quyết — mọi trường và cách hành động với nó
• Data API — kéo và đối soát phán quyết ở phía máy chủ