사기 방지 Web SDK

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

빠른 시작

<!-- 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' });

옵션

옵션	타입	기본값	설명
appKey	string	—	사기 방지 애플리케이션 키(필수).
domain	string	서비스 기본값	판정 서비스 엔드포인트. 전용 도메인을 받지 않았다면 설정하지 마세요.
escalate	boolean	false	방문이 고위험으로 보일 때 사기 방지가 방문자에게 추가 검증을 한 번 요청하도록 허용합니다. Escalation을 참조하세요.
collectWindowMs	number	1200	SDK가 판정을 요청하기 전에 방문을 관찰하는 시간(ms). 더 긴 창은 약간의 지연을 대가로 더 확신 있는 판정을 산출합니다.
onVerdict	(v) => void	—	최종 판정과 함께 한 번 호출됩니다. 주요 연동 지점입니다.
onError	(err) => void	—	문제가 발생하면 호출됩니다. SDK는 당신의 페이지로 예외를 던지지 않습니다.
onEscalate	(displayType) => void	—	추가 검증이 표시될 때 호출됩니다(escalate: true일 때만).
onEscalateDone	(passed) => void	—	추가 검증이 끝난 후 호출됩니다. 방문자가 통과했다면 passed는 true입니다.

트래픽 소스 시나리오

제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

방문이 고위험으로 보일 때, 사기 방지는 방문자를 실제 사용자로 취급하기 전에 추가 검증을 한 번 완료하도록 요청할 수 있습니다. 이는 선택(opt-in) 기능입니다.

escalate: true로 활성화합니다.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to false
  },
});

참고:

• Escalation은 판정의 action이 challenge일 때만 트리거됩니다. 그 밖의 모든 방문에서는 아무것도 표시되지 않으며 방문자 경험은 그대로 유지됩니다.
• 방문자가 추가 검증을 통과하면, onVerdict로 전달되는 판정이 그것을 반영합니다(사람으로 취급).
• Escalation은 fail open입니다. 추가 검증을 로드하거나 표시할 수 없으면, SDK는 당신의 페이지를 막는 대신 원래 판정을 유지합니다.

INFO

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

복원력

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

다음 단계

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