---
title: Fraud Prevention — Web SDK
---

# 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

```html
<!-- 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.

```js
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](#escalation). |
| `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. |

::: tip 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](./scenarios/ad-fraud).
:::

## 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`.

```js
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](./verdict-reference).

## Nâng cấp xác minh {#escalation}

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`:

```js
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](./verdict-reference) — mọi trường và cách hành động với nó
- [Data API](./data-api) — kéo và đối soát phán quyết ở phía máy chủ