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

Tùy chọn	Kiểu	Mặc định	Mô tả
appKey	string	—	Khóa ứng dụng Fraud Prevention của bạn (bắt buộc).
domain	string	mặc định của dịch vụ	Điểm cuối dịch vụ phán quyết. Cứ để mặc định trừ khi bạn được cấp một domain riêng.
escalate	boolean	false	Cho phép Fraud Prevention yêu cầu khách truy cập làm thêm một lần xác minh khi lượt truy cập trông có rủi ro cao. Xem Nâng cấp xác minh.
collectWindowMs	number	1200	Khoảng thời gian (ms) SDK quan sát lượt truy cập trước khi yêu cầu phán quyết. Cửa sổ dài hơn cho phán quyết chắc chắn hơn, đổi lại một độ trễ nhỏ.
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.
onError	(err) => void	—	Được gọi nếu có gì đó sai sót. SDK không bao giờ ném ngoại lệ vào trang của bạn.
onEscalate	(displayType) => void	—	Được gọi khi một lần xác minh bổ sung được hiển thị (chỉ khi escalate: true).
onEscalateDone	(passed) => void	—	Được gọi sau khi lần xác minh bổ sung kết thúc; passed là true nếu khách truy cập vượt qua.

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. Đây là tùy chọn bật theo ý muốn.

Bật nó bằng escalate: true:

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  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) {
    if (passed) {
      // khách truy cập đã vượt qua kiểm tra bổ sung — coi như người thật
    } 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.
• 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ủ