---
title: 사기 방지 — Web SDK
---

# 사기 방지 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`로 기다릴 수도 있습니다 — 둘 다 동일한 판정 객체를 받습니다.

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

## 옵션

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

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

## 판정 사용하기

`onVerdict`는 `BotVerdict` 객체를 받습니다. 가장 많이 사용하게 될 두 필드는 다음과 같습니다.

- **`verdict.is_bot`** — 방문이 자동화/무효로 판정되면 `true`.
- **`verdict.action`** — 우리가 권장하는 처리: `record_only`, `challenge`, 또는 `flag`.

```js
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](./verdict-reference)를 참조하세요.

## Escalation

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

`escalate: true`로 활성화합니다.

```js
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](./verdict-reference) — 모든 필드와 대응 방법
- [Data API](./data-api) — 서버 측에서 판정을 가져오고 대조하기