反詐欺 Web SDK

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

快速開始

<!-- 載入反詐欺 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——兩者拿到的是同一個裁決物件。

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

選項

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

流量來源場景

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

使用裁決

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

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

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

完整欄位列表與建議處理方式見裁決欄位參考。

升級驗證

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

用 escalate: true 開啟:

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。

下一步

• 裁決欄位參考 —— 每個欄位及處理方式
• 資料 API —— 伺服器端拉取與對帳裁決