---
title: 反詐欺 — Web SDK
---

# 反詐欺 Web SDK

反詐欺 Web SDK 執行在**你的頁面**上——著陸頁、註冊或登入頁,或任何需要保護的資源。
它為當前訪問請求一份裁決,並交回給你的程式碼,讓你決定如何處理這次流量——記錄、標記,
或要求訪客額外做一次驗證。

## 快速開始

```html
<!-- 載入反詐欺 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 —— 見裁決欄位參考
      if (verdict.is_bot) {
        // 把該次訪問從漏斗中剔除 / 抑制其轉換
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>
```

`BotSignal.init()` 同時回傳 `Promise<BotVerdict>`,所以你也可以用 `await` 代替
`onVerdict`——兩者拿到的是同一個裁決物件。

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

## 選項

| 選項 | 型別 | 預設值 | 說明 |
| --- | --- | --- | --- |
| `appKey` | string | — | 你的反詐欺應用程式 Key(必填)。 |
| `domain` | string | 服務預設值 | 裁決服務端點。除非你拿到了專用網域,否則保持預設即可。 |
| `escalate` | boolean | `false` | 允許反詐欺在訪問看起來高風險時,要求訪客**額外做一次驗證**。見[升級驗證](#escalation)。 |
| `collectWindowMs` | number | `1200` | SDK 在請求裁決前觀察訪問的時長(毫秒)。視窗越長裁決越有把握,代價是輕微延遲。 |
| `onVerdict` | `(v) => void` | — | 在拿到最終裁決時呼叫一次。主要的接入點。 |
| `onError` | `(err) => void` | — | 出錯時呼叫。SDK 絕不會向你的頁面拋出例外。 |
| `onEscalate` | `(displayType) => void` | — | 展示額外驗證時呼叫(僅當 `escalate: true`)。 |
| `onEscalateDone` | `(passed) => void` | — | 額外驗證結束後呼叫;訪客通過則 `passed` 為 `true`。 |

::: tip 流量來源場景
若由第三方把訪客送給你,且雙方需要就一份逐點擊的結論對帳,SDK 還能從頁面 URL 讀取
一個點擊 token。這是付費流量場景特有的——見[廣告反作弊](./scenarios/ad-fraud)指南。
:::

## 使用裁決

`onVerdict` 收到一個 `BotVerdict` 物件。你最常用到的兩個欄位:

- **`verdict.is_bot`** —— 當訪問被判定為自動化/無效流量時為 `true`。
- **`verdict.action`** —— 我們建議你怎麼做:`record_only`、`challenge` 或 `flag`。

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // 看起來正常的流量 —— 正常放行,記錄裁決即可
        break;
      case 'flag':
        // 可疑 —— 繼續展示頁面,但把該次訪問標為低品質
        markLowQuality(verdict);
        break;
      case 'challenge':
        // 高風險 —— 若開啟升級驗證則自動處理(見下文)
        break;
    }
  },
});
```

完整欄位列表與建議處理方式見[裁決欄位參考](./verdict-reference)。

## 升級驗證 {#escalation}

當一次訪問看起來高風險時,反詐欺可以在你把訪客當作真人之前,要求其完成
**一次額外驗證**。這是可選項。

用 `escalate: true` 開啟:

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // 正在向訪客展示一次額外驗證
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // 訪客通過了額外驗證 —— 當作真人處理
    } else {
      // 未通過 —— 沿用原裁決的建議
    }
  },
  onVerdict: function (verdict) {
    // 若訪客通過了升級驗證,verdict.is_bot 會被更新為 false
  },
});
```

注意:

- 升級驗證僅在裁決的 `action` 為 `challenge` 時觸發。其他訪問不會展示任何東西,
  訪客體驗完全不受影響。
- 若訪客通過了額外驗證,交給 `onVerdict` 的裁決會隨之更新(當作真人)。
- 升級驗證**失敗放行**:如果額外驗證無法載入或展示,SDK 會沿用原裁決,而不會阻斷你的頁面。

::: info
反詐欺從不替你做決定。即便在 `challenge`/`flag` 下,是否放行該次訪問仍由你的程式碼
掌控——SDK 只負責呈現裁決,並(可選地)執行額外驗證。
:::

## 容錯

如果裁決服務無法連線或發生任何錯誤,SDK 會回傳一份**降級(degraded)**裁決
(`degraded: true`),而不是讓你的頁面失敗。降級裁決是保守的(`is_bot: false`、
`action: record_only`),因此永遠不會誤傷真實使用者。若你想對這類訪問特殊處理,
檢查 `verdict.degraded`。

## 下一步

- [裁決欄位參考](./verdict-reference) —— 每個欄位及處理方式
- [資料 API](./data-api) —— 伺服器端拉取與對帳裁決