Verdict Reference
모든 사기 방지 판정은 — Web SDK의 onVerdict 콜백으로 전달되든 Data API에서 가져오든 — 동일한 BotVerdict 객체입니다. 이 페이지는 각 필드와 그것에 대응하는 방법을 문서화합니다.
{
"is_bot": false,
"score": 18,
"level": "low",
"action": "record_only",
"reasons": [],
"consistency": { "ok": true },
"degraded": false,
"verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
"verdict_token": "vt1.eyJ2Ijoi...",
"verdict_token_exp": 1767225600
}필드
| 필드 | 타입 | 설명 |
|---|---|---|
is_bot | boolean | 핵심 판정. true = 방문이 자동화 또는 무효 트래픽으로 판정됨; false = 실제 사람으로 보임. 대부분의 연동이 분기하는 단일 필드입니다. |
score | number (0–100) | 방문이 얼마나 의심스러운지. 높을수록 더 의심스럽습니다. 자신만의 임계값을 설정하는 데 사용하세요 — 예: 선택한 컷오프 이상의 방문을 제외. 정확한 값은 우리의 위험 모델이 산출하며, 역설계할 목적이 아닙니다. |
level | enum | score의 거친 구간: low, medium, high, critical. 원시 숫자 대신 버킷을 원할 때 편리합니다. |
action | enum | 그 방문에 대한 우리의 권장 처리: record_only, challenge, flag, 또는 deny. 아래를 참조하세요. 새 값이 추가되어도 연동이 계속 동작하도록 알 수 없는 값은 flag로 다루세요. |
reasons | string[] | 위험한 판정을 설명하는 최대 세 개의 넓은 사유 카테고리. 깨끗한 방문에서는 비어 있습니다. |
consistency | object | 신호 간 일관성 결론. consistency.ok(boolean)을 읽으세요: true = 방문의 신호가 예상대로 들어맞음; false = 무언가 맞지 않아 추가 검토가 필요함. 이 결론 이면의 내부 분해는 노출되지 않습니다. |
degraded | boolean | 판정을 완전히 계산할 수 없어(서비스 도달 불가, 오류 등) 보수적 폴백이 반환되었을 때 true. degraded 판정은 "깨끗함"이 아니라 "알 수 없음"으로 다루세요. |
verdict_id | string | 이 판정의 고유 ID. 나중에 Data API로 판정을 조회할 때 사용합니다. |
verdict_token | string | 이 판정의 서명된 증명으로, 서버에서 검증하기 위한 것입니다. 서버 측 검증을 참조하세요. 폴백 판정에는 없습니다. |
verdict_token_exp | number | verdict_token이 만료되는 Unix 시각(초). |
action — 무엇을 할지
action은 우리의 권장 사항입니다. 최종 결정은 당신이 통제합니다.
action | 의미 | 무엇을 할지 |
|---|---|---|
record_only | 방문이 정상으로 보임. | 평소대로 진행하세요. 보고와 대조를 위해 판정만 기록하면 됩니다. |
flag | 의심스럽지만 확정적으로 나쁘지는 않음. | 페이지는 계속 제공하되, 그 방문을 저품질로 표시하세요 — 지표에서 제외하고, 후속 흐름에서 분리하고, 자신의 판단에 반영하세요(예: 전환 귀속, 또는 그 방문을 얼마나 신뢰할지). |
challenge | 방문이 챌린지 임계값에 도달했습니다(기본값은 고위험). | 방문자를 사람으로 취급하기 전에 추가 검증을 한 번 요청하세요. 앱의 처리 동작이 challenge로 설정되어 있으면 Web SDK가 대신 실행합니다(Escalation 참조). 그렇지 않으면 자체 게이트를 적용하세요. |
deny | 방문이 차단 규칙(예: 차단 목록 항목이나 차단하도록 구성한 정책)에 일치함. | 보호된 콘텐츠를 제공하지 마세요. 챌린지는 제공되지 않습니다. 이전 SDK 버전은 이 값을 그대로 전달하므로 onVerdict에서 처리하세요. |
구성 가능한 처리 액션
고위험 방문에 대해 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가 챌린지를 제시하도록 두거나. 위험을 직접 다시 산출할 필요가 없습니다.
챌린지 임계값과 유형
처리 동작이 challenge이면 대시보드의 같은 위치에 설정 두 가지가 더 표시됩니다.
- 챌린지 임계값 — 설정한 동작을 반환할 위험 수준입니다. 기본값은 고위험 이상입니다. 엄격 모드에서는 중위험 방문에도 적용됩니다. 스크레이퍼와 AI 에이전트를 더 많이 막지만, 챌린지를 보는 실제 방문자도 늘어납니다.
- 챌린지 유형 — 에스컬레이션 시 표시할 최소 CAPTCHA 유형: 슬라이더(기본값), 회전, 클릭, 3D 클릭. 강한 유형일수록 자동화·AI 도구가 풀기 어렵습니다.
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이 있었던 경우) |
reasons — 사유 카테고리
reasons는 방문이 왜 위험해 보였는지를 넓은 범주로 알려 줍니다. 최대 세 개의 카테고리를 강한 것부터 순서대로 담습니다. 개별 신호나 점수 분해는 절대 포함하지 않습니다.
| 카테고리 | 의미 |
|---|---|
automation | 스크립트화된 브라우저나 헤드리스 브라우저 같은 자동화 도구의 징후. |
network | 프록시, 데이터센터 또는 익명화 네트워크, 차단된 주소 등 네트워크가 위험하거나 일관되지 않아 보임. |
abnormal_requests | 과도한 요청, 반복된 실패, 자동화 트래픽 이력 등 비정상적인 요청 패턴. |
device | 기기나 그 환경을 신뢰할 수 없거나 인식할 수 없음. |
behavior | 상호작용이 전혀 없거나 재사용된 링크 등 방문이 사람처럼 행동하지 않음. |
other | 자체 규칙과 폴백 판정을 포함한 기타 사유. |
이 목록은 규칙을 만들 신호가 아니라 보고용 설명으로 다루세요. 대신 is_bot, action, score로 분기하세요. 향후 새 카테고리가 추가될 수 있습니다.
서버 측 검증
페이지가 받는 모든 것은 방문자가 변경할 수 있습니다. 콘텐츠 접근을 제어한다면(실제 사람만 페이지, API 응답, 다운로드를 볼 수 있도록), 브라우저의 is_bot 플래그를 신뢰하지 마세요. verdict_token을 자신의 서버로 보내 그곳에서 검증하세요.
onVerdict에서verdict.verdict_token을 백엔드로 보냅니다(예: 헤더나 쿠키로).- 백엔드가 토큰과 방문자의 IP 주소로
POST /v1/bot/verdict/verify를 호출합니다. - 응답이
valid: true이고 판정이 허용 가능한 경우(예:verdict.is_bot이false)에만 콘텐츠를 제공합니다.
토큰은 사용자의 앱, 이 판정, 방문자의 네트워크에 묶이며 짧은 시간(기본 10분) 후에 만료됩니다. 기본적으로 토큰은 여러 번 검증할 수 있으므로 하나의 토큰으로 한 방문의 여러 페이지 뷰를 처리할 수 있습니다. 폼 제출처럼 토큰을 한 번만 사용해야 할 때는 consume: true를 전달하세요.
방문자가 이후 에스컬레이션 챌린지를 통과하더라도 토큰은 원래 판정을 그대로 보여 줍니다. escalate_result의 captcha pass token도 captcha 서버 측 API로 함께 검증하세요.
level 대 score
level은 편의를 위해 제공되는 score의 구간 분류일 뿐입니다.
level | 사용 시점 |
|---|---|
low | 깨끗한 트래픽으로 취급. |
medium | 경계선 — 기록은 괜찮으나, 고가치 퍼널에서는 제외를 고려. |
high | 강하게 의심됨 — 표시하고 제외. |
critical | 거의 확실히 무효 — 표시/제외하고, 가능하면 escalate. |
파이프라인에 맞는 필드 선택
- 단순 예/아니오 게이트 → **
is_bot**으로 분기. - 권장 기반 → **
action**으로 분기. - 맞춤 임계값 →
score(또는 버킷용level)로 분기.
degraded 판정 처리
degraded가 true이면 판정이 완전히 계산되지 않은 것입니다. 폴백은 의도적으로 보수적이어서(is_bot: false, action: record_only) 실제 사용자가 결코 차단되지 않습니다. 보고 시에는 이를 확정적으로 깨끗한 트래픽으로 집계하지 말고 알 수 없음으로 다루세요.