Verdict Reference
모든 사기 방지 판정은 — Web SDK의 onVerdict 콜백으로 전달되든 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 참조). 그렇지 않으면 자체 게이트를 적용하세요. |
구성 가능한 처리 액션
고위험 방문에 대해 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가 챌린지를 제시하도록 두거나. 위험을 직접 다시 산출할 필요가 없습니다.
level 대 score
level은 편의를 위해 제공되는 score의 구간 분류일 뿐입니다.
level | 사용 시점 |
|---|---|
low | 깨끗한 트래픽으로 취급. |
medium | 경계선 — 기록은 괜찮으나, 고가치 퍼널에서는 제외를 고려. |
high | 강하게 의심됨 — 표시하고 제외. |
critical | 거의 확실히 무효 — 표시/제외하고, 가능하면 escalate. |
파이프라인에 맞는 필드 선택
- 단순 예/아니오 게이트 → **
is_bot**으로 분기. - 권장 기반 → **
action**으로 분기. - 맞춤 임계값 →
score(또는 버킷용level)로 분기.
degraded 판정 처리
degraded가 true이면 판정이 완전히 계산되지 않은 것입니다. 폴백은 의도적으로 보수적이어서(is_bot: false, action: record_only) 실제 사용자가 결코 차단되지 않습니다. 보고 시에는 이를 확정적으로 깨끗한 트래픽으로 집계하지 말고 알 수 없음으로 다루세요.