---
title: 사기 방지 — Verdict Reference
---

# Verdict Reference

모든 사기 방지 판정은 — [Web SDK](./web-sdk)의 `onVerdict` 콜백으로 전달되든
[Data API](./data-api)에서 가져오든 — 동일한 `BotVerdict` 객체입니다. 이 페이지는 각
필드와 그것에 대응하는 방법을 문서화합니다.

```json
{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "consistency": { "ok": true },
  "degraded": false
}
```

## 필드

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `is_bot` | boolean | 핵심 판정. `true` = 방문이 자동화 또는 무효 트래픽으로 판정됨; `false` = 실제 사람으로 보임. 대부분의 연동이 분기하는 단일 필드입니다. |
| `score` | number (0–100) | 방문이 얼마나 의심스러운지. **높을수록 더 의심스럽습니다.** 자신만의 임계값을 설정하는 데 사용하세요 — 예: 선택한 컷오프 이상의 방문을 제외. 정확한 값은 우리의 위험 모델이 산출하며, 역설계할 목적이 아닙니다. |
| `level` | enum | `score`의 거친 구간: `low`, `medium`, `high`, `critical`. 원시 숫자 대신 버킷을 원할 때 편리합니다. |
| `action` | enum | 그 방문에 대한 우리의 **권장 처리**: `record_only`, `challenge`, 또는 `flag`. 아래를 참조하세요. |
| `consistency` | object | 신호 간 일관성 결론. `consistency.ok`(boolean)을 읽으세요: `true` = 방문의 신호가 예상대로 들어맞음; `false` = 무언가 맞지 않아 추가 검토가 필요함. 이 결론 이면의 내부 분해는 노출되지 않습니다. |
| `degraded` | boolean | 판정을 완전히 계산할 수 없어(서비스 도달 불가, 오류 등) 보수적 폴백이 반환되었을 때 `true`. degraded 판정은 "깨끗함"이 아니라 "알 수 없음"으로 다루세요. |

## `action` — 무엇을 할지

`action`은 우리의 권장 사항입니다. 최종 결정은 당신이 통제합니다.

| `action` | 의미 | 무엇을 할지 |
| --- | --- | --- |
| `record_only` | 방문이 정상으로 보임. | 평소대로 진행하세요. 보고와 대조를 위해 판정만 기록하면 됩니다. |
| `flag` | 의심스럽지만 확정적으로 나쁘지는 않음. | 페이지는 계속 제공하되, 그 방문을 저품질로 표시하세요 — 지표에서 제외하고, 후속 흐름에서 분리하고, 자신의 판단에 반영하세요(예: 전환 귀속, 또는 그 방문을 얼마나 신뢰할지). |
| `challenge` | 방문이 고위험. | 방문자를 사람으로 취급하기 전에 추가 검증을 한 번 요청하세요. Web SDK의 `escalate: true`를 사용하면 자동으로 처리됩니다([Escalation](./web-sdk#escalation) 참조). 그렇지 않으면 자체 게이트를 적용하세요. |

## 구성 가능한 처리 액션

**고위험** 방문에 대해 `action`이 무엇을 보고하는지는 **앱별 구성**으로, 대시보드의
애플리케이션 상세에서 설정합니다. 판정은 **서버 권위적(server-authoritative)**입니다.
`action`은 방문이 고위험 구간에 도달하고 **또한** 당신의 앱이 해당 액션으로 구성되어
있을 때만 `challenge` 또는 `flag`가 됩니다. 그 구간 아래에서는 판정이 `record_only`로
유지됩니다.

| 설정 | 고위험 시 반환되는 `action` | 의미 |
| --- | --- | --- |
| `record_only` (기본값) | `record_only` | 기록만 함. 판정은 보고와 대조를 위해 기록되며, 방문자에게 아무것도 요구하지 않습니다. |
| `challenge` | `challenge` | 재검증 CAPTCHA를 트리거합니다. Web SDK가 챌린지를 띄웁니다(스타일은 SDK의 `challengeConfig`로 제어). |
| `flag` | `flag` | 방문을 표시합니다. 판정이 `flag`를 담으며, 그것에 어떻게 대응할지는 당신의 연동이 결정합니다(차단 / 분리 / 처리). |

결정이 서버 측에서 이루어지므로 당신의 코드는 단순하게 유지됩니다. `onVerdict`에서
`verdict.action`을 읽고 그에 따라 대응하세요 — 진행하거나, 차단하거나, SDK가 챌린지를
제시하도록 두거나. 위험을 직접 다시 산출할 필요가 없습니다.

### `escalate_result`

관리형 captcha 에스컬레이션이 실행된 뒤에 존재합니다 — 즉 `action`이 `challenge`였고 SDK가 captcha를 실행했을 때입니다. 에스컬레이션이 실행되지 않았으면 `null`입니다. `onEscalateDone(passed, detail)`로도 전달됩니다.

| 필드 | 설명 |
|---|---|
| `passed` | 방문자가 captcha를 통과했는지 여부 |
| `token` | captcha pass token — 통과를 확인하려면 **서버 측에서 검증하세요**(클라이언트의 `passed`만 신뢰하지 마세요) |
| `challenge_id` | captcha challenge id |
| `cid` | 이 에스컬레이션이 연결된 click id(click token이 있었던 경우) |

## `level` 대 `score`

`level`은 편의를 위해 제공되는 `score`의 구간 분류일 뿐입니다.

| `level` | 사용 시점 |
| --- | --- |
| `low` | 깨끗한 트래픽으로 취급. |
| `medium` | 경계선 — 기록은 괜찮으나, 고가치 퍼널에서는 제외를 고려. |
| `high` | 강하게 의심됨 — 표시하고 제외. |
| `critical` | 거의 확실히 무효 — 표시/제외하고, 가능하면 escalate. |

::: tip 파이프라인에 맞는 필드 선택
- 단순 예/아니오 게이트 → **`is_bot`**으로 분기.
- 권장 기반 → **`action`**으로 분기.
- 맞춤 임계값 → **`score`**(또는 버킷용 **`level`**)로 분기.
:::

## degraded 판정 처리

`degraded`가 `true`이면 판정이 완전히 계산되지 않은 것입니다. 폴백은 의도적으로
보수적이어서(`is_bot: false`, `action: record_only`) 실제 사용자가 결코 차단되지
않습니다. 보고 시에는 이를 확정적으로 깨끗한 트래픽으로 집계하지 말고 **알 수 없음**으로
다루세요.

## 다음 단계

- [Web SDK](./web-sdk) — 페이지에서 판정 받기
- [Data API](./data-api) — 서버 측에서 판정과 통계 가져오기