反詐欺 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' });

選項

option	type	default	說明
appKey	string	—	必填。你的反詐欺應用 Key。
domain	string	signal-v1.world-dynamic.com	SDK 上報的 Signal 網域。
tokenParam	string	_ctk	SDK 從該 URL 查詢參數讀取點擊 token。
onVerdict	(v) => void	—	在取得最終裁決時呼叫一次。主要的接入點。init() 同時回傳 Promise<BotVerdict>。
onError	(err) => void	—	任何失敗時呼叫。SDK 絕不會向你的頁面拋出例外。
onChallenge	(v) => creds | null | Promise<…>	—	覆寫升級驗證所用的憑證:回傳你自己的 { appKey, serverToken }(serverToken 由你的後端簽發),或回傳 null 跳過升級。未設定時使用 verdict.escalate 中後端簽發的預設憑證(零設定)。
challengeConfig	object	—	驗證碼外觀/位置:product(popup/float/embed)、container、theme、lang。
onEscalate	(displayType) => void	—	顯示升級驗證碼時呼叫。
onEscalateDone	(passed, detail) => void	—	升級驗證結束後呼叫。passed = 訪客是否通過;detail = { token, challengeId, cid },用於在伺服器端校驗本次通過。

升級是伺服器端驅動的。 只有當伺服器裁決的 action 為 challenge,且該 app 設定了對應的升級處理動作時,SDK 才會彈出驗證碼——不存在用戶端開關來控制它。可透過 onChallenge 傳入你自己的憑證或跳過升級,透過 challengeConfig 控制其樣式。訪客通過後,用 detail.token(以及 challenge_id/cid)在你自己的後端校驗——不要只信用戶端的 passed 旗標。

流量來源場景

若由第三方把訪客送給你,且雙方需要就一份逐點擊的結論對帳,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;
    }
  },
});

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

升級驗證

當一次訪問看起來高風險時,反詐欺可以在你把訪客當作真人之前,要求其完成一次額外驗證。這由伺服器端裁決驅動,而非用戶端開關——只要裁決的 action 為 challenge 且該 app 設定了升級處理動作,它就會執行。

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // 正在向訪客顯示一次額外驗證
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // 訪客通過了額外驗證 —— 在你的後端校驗 detail.token
    } else {
      // 未通過 —— 沿用原裁決的建議
    }
  },
  onVerdict: function (verdict) {
    // 若訪客通過了升級驗證,verdict.is_bot 會被更新為 false
  },
});

注意:

• 升級驗證僅在裁決的 action 為 challenge 時觸發。其它訪問不會顯示任何東西,訪客體驗完全不受影響。
• 預設情況下 SDK 使用 verdict.escalate 中後端簽發的憑證(零設定)。可透過 onChallenge 傳入你自己的 { appKey, serverToken } 或跳過升級,透過 challengeConfig 控制其樣式。
• 通過後,用 detail.token(以及 challenge_id/cid)在你自己的後端校驗——不要只信用戶端的 passed 旗標。
• 若訪客通過了額外驗證,交給 onVerdict 的裁決會隨之更新(當作真人)。
• 升級驗證失敗放行:如果額外驗證無法載入或顯示,SDK 會沿用原裁決,而不會阻斷你的頁面。

INFO

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

容錯

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

下一步

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