사기 방지 Web SDK

사기 방지 Web SDK는 당신의 페이지 — 랜딩 페이지, 가입 또는 로그인 화면, 또는 보호 대상 리소스 — 에서 동작합니다. 현재 방문에 대한 판정을 요청하여 당신의 코드로 돌려주므로, 그 트래픽으로 무엇을 할지 결정할 수 있습니다 — 기록하거나, 표시(flag)하거나, 방문자에게 추가 검증을 한 번 요청하거나.

빠른 시작

html

<!-- Load the 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 — see Verdict Reference
      if (verdict.is_bot) {
        // exclude this visit from your funnel / suppress conversions
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>

BotSignal.init()는 Promise<BotVerdict>도 반환하므로, onVerdict를 사용하는 대신 await로 기다릴 수도 있습니다 — 둘 다 동일한 판정 객체를 받습니다.

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

옵션

option	type	default	설명
`appKey`	string	—	필수. 사기 방지 애플리케이션 키.
`domain`	string	`signal-v1.world-dynamic.com`	SDK가 요청을 보내는 Signal 도메인.
`tokenParam`	string	`_ctk`	SDK가 클릭 토큰을 읽어 오는 URL 쿼리 파라미터.
`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 }`.

에스컬레이션은 서버 주도입니다. SDK는 서버 판정의 action이 challenge이고 그리고 해당 앱에 대응하는 에스컬레이션 액션이 설정되어 있을 때만 캡차를 표시합니다 — 이를 위한 클라이언트 측 토글은 없습니다. 직접 만든 자격 증명을 제공하거나 에스컬레이션을 건너뛰려면 onChallenge를, 외형을 제어하려면 challengeConfig를 사용하세요. 방문자가 통과한 후에는 detail.token(및 challenge_id/cid)으로 당신의 백엔드에서 결과를 검증하세요 — 클라이언트 측 passed 플래그만 믿지 마세요.

트래픽 소스 시나리오

제3자가 당신에게 방문자를 전달하고 양측이 클릭별 결론으로 대조해야 한다면, SDK는 페이지 URL에서 클릭 토큰을 읽을 수도 있습니다. 이는 유료 트래픽 흐름에 한정된 내용입니다 — 광고 사기 가이드를 참조하세요.

판정 사용하기

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':
        // normal-looking traffic — proceed, just log the verdict
        break;
      case 'flag':
        // suspicious — keep serving the page but mark this visit as low quality
        markLowQuality(verdict);
        break;
      case 'challenge':
        // high risk — handled by escalation if enabled (see below)
        break;
    }
  },
});

전체 필드 목록과 권장 처리 방법은 Verdict Reference를 참조하세요.

Escalation

방문이 고위험으로 보일 때, 사기 방지는 방문자를 실제 사용자로 취급하기 전에 추가 검증을 한 번 완료하도록 요청할 수 있습니다. 이는 클라이언트 측 플래그가 아니라 서버 판정에 의해 주도됩니다 — 판정의 action이 challenge이고 해당 앱에 에스컬레이션 액션이 설정되어 있을 때마다 실행됩니다.

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로 갱신됩니다
  },
});

참고:

Escalation은 판정의 action이 challenge일 때만 트리거됩니다. 그 밖의 모든 방문에서는 아무것도 표시되지 않으며 방문자 경험은 그대로 유지됩니다.
기본적으로 SDK는 verdict.escalate에 담긴 백엔드 발급 자격 증명을 사용합니다(무설정). 직접 만든 { appKey, serverToken }을 제공하거나 에스컬레이션을 건너뛰려면 onChallenge를, 외형을 제어하려면 challengeConfig를 사용하세요.
통과 이후에는 detail.token(및 challenge_id/cid)을 당신의 백엔드에서 검증하세요 — 클라이언트 측 passed 플래그만 믿지 마세요.
방문자가 추가 검증을 통과하면, onVerdict로 전달되는 판정이 그것을 반영합니다(사람으로 취급).
Escalation은 fail open입니다. 추가 검증을 로드하거나 표시할 수 없으면, SDK는 당신의 페이지를 막는 대신 원래 판정을 유지합니다.

INFO

사기 방지는 결코 당신을 대신해 결정하지 않습니다. challenge/flag인 경우에도 방문을 진행시킬지 여부는 당신의 코드가 통제합니다 — SDK는 판정을 드러내고, 선택적으로 추가 검증을 실행할 뿐입니다.

에스컬레이션을 발동하는 위험 수준(기본 고위험, 엄격 모드에서는 중위험)과 최소 CAPTCHA 유형은 대시보드에서 앱별로 설정합니다. 챌린지 임계값과 유형을 참고하세요. onEscalate에는 실제로 표시되는 유형이 전달됩니다.

복원력

판정 서비스에 도달할 수 없거나 어떤 오류가 발생하면, SDK는 당신의 페이지를 실패시키는 대신 degraded 판정(degraded: true)을 반환합니다. degraded 판정은 보수적이어서 (is_bot: false, action: record_only) 실제 사용자를 결코 막지 않습니다. 그런 방문을 특별하게 다루고 싶다면 verdict.degraded를 확인하세요.

다음 단계

Verdict Reference — 모든 필드와 대응 방법
Data API — 서버 측에서 판정을 가져오고 대조하기

사기 방지 Web SDK ​

빠른 시작 ​

옵션 ​

판정 사용하기 ​

Escalation ​

복원력 ​

다음 단계 ​

사기 방지 Web SDK

빠른 시작

옵션

판정 사용하기

Escalation

복원력

다음 단계