사기 방지 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' });

옵션

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는 판정을 드러내고, 선택적으로 추가 검증을 실행할 뿐입니다.

복원력

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

다음 단계

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