> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 위치 인증 API: 지오펜싱 및 IP 거리

> Didit의 위치 인증으로 인증 중인 사용자의 실제 위치를 확인하세요. 기기 위치, 지오펜싱, IP 및 문서 거리 확인, 스푸핑 감지를 지원합니다. 검사당 $0.05.

Didit의 위치 인증 단계는 사용자가 인증을 진행하는 동안 기기 위치(브라우저 또는 네이티브 SDK)를 한 번 읽거나 연결된 IP 위치를 확인하여 해당 사용자가 어디에 있는지 검증합니다. 그런 다음 허용 및 차단된 지역, IP 위치 및 문서에 기재된 주소와 대조합니다.
워크플로 및 API에서는 `GEOLOCATION` 기능에 해당하며, 관련 설정은 `geolocation_*` 키이고, 그 결과는 세션 결정의 `geolocation_checks[]`로 반환됩니다.

## 사용 시기

* 특정 관할권에 대해서만 라이선스를 보유하고 있어(도박, 중개, 대출 등) 신청 당시 사용자가 해당 관할권 내에 있었음을 증명해야 하는 경우.
* 제재 대상 지역이나 서비스를 제공하지 않는 주 등 차단된 지역의 사용자를 차단해야 하는 경우.
* IP 위치 또는 신분증 주소와 멀리 떨어진 기기 위치, 조작된 위치, VPN 또는 에뮬레이터 등 추가적인 사기 신호가 필요한 경우.
* 사용자의 이동 경로 또는 기록은 필요하지 않고, 세션 중에 측정된 단 한 번의 위치 값만 필요한 경우.

## 작동 방식

**1. 안내 및 권한 요청**

사용자는 위치 정보가 필요한 이유와 이번 인증을 위해 일회성으로 위치를 조회한다는 안내를 확인합니다.
이후 브라우저나 휴대폰에서 권한을 요청합니다.
Didit은 사용자가 동의한 안내 내역(버전, 언어, 시간)을 결과의 `consent`로 기록합니다.

**2. 시도당 한 번의 위치 측정**

클라이언트는 충분히 정확한 측정값을 얻거나 시도당 타임아웃(기본값 20초)이 만료될 때까지 가장 정확한 측정값을 유지합니다.
각 시도에는 5분 동안 유효하며 세션에 바인딩된 일회용 챌린지가 포함되므로 가로챈 제출 데이터를 재전송할 수 없습니다.

**3. 검사**

Didit은 정확도, 최신성, 대략적 위치 권한 부여 여부, 스푸핑 신호, 지역, IP 위치 및 문서 주소와의 거리, VPN, 프록시, Tor 및 에뮬레이터 탐지 결과, 사용자의 이전 검사 이력을 판별합니다.

**4. 결과**

각 탐지 결과는 [경고](https://docs.didit.me/ko/core-technology/location-verification/warnings-location-verification.md)를 발생시키며, 구성된 작업(`NO_ACTION`, `REVIEW` 또는 `DECLINE`)에 따라 단계 상태가 결정됩니다.
가장 엄격한 작업이 최종 적용됩니다.

## 위치 소스

위치 정보를 가져올 소스는 `geolocation_position_source`로 선택합니다.

| 값 | 동작 방식 |
| - | - |
| `device_and_ip` | 기기 위치를 전송된 연결의 IP 위치와 대조하여 검사합니다. |
| `device_only` | 기기 위치만 확인합니다. IP 위치와는 절대 비교하지 않습니다. |
| `ip_only` | 사용자에게 권한을 요청하지 않습니다. 정확도, 최신성, 대략적 위치 권한 규칙 없이 연결의 IP 위치(도시 수준, 반경 50 km)를 대신 판별합니다. |
| 설정되지 않음 | 기기에 위치를 요청하고, 세션의 기기 및 IP 분석 단계에서 확인된 IP 위치와 기기 위치를 비교합니다. VPN, 프록시 또는 Tor 탐지 결과에 따라 동작하는 노드는 연결을 조회하고 `device_and_ip`처럼 동작합니다. |

기기에 위치를 요청하는 노드에서는 위치 정보가 없는 시도를 거부 또는 실패로 그대로 판별하며, IP 위치가 이를 절대 대체하지 않습니다.

## 구성 기본값 및 제한

모든 키는 선택 사항입니다.
전체 목록은 [워크플로 기능 구성 레퍼런스](https://docs.didit.me/ko/management-api/workflows/feature-configs.md#위치-확인)에서 확인할 수 있습니다.

| 설정 | 기본값 | 제한 |
| - | - | - |
| `geolocation_max_accuracy_radius_m` | 250 m | 10\~50,000 m |
| `geolocation_max_age_seconds` | 120 s | 5\~3,600 s |
| `geolocation_timeout_seconds` | 20 s | 5\~120 s |
| `geolocation_max_attempts` | 3 | 1\~5 |
| `geolocation_accuracy_mode` | `precise` | `precise` 또는 `approximate_allowed` |
| `geolocation_low_accuracy_behavior` | `ask_again` | `ask_again` 또는 `fail` |
| `geolocation_allow_qr_handoff` | on | on 또는 off |
| `geolocation_allow_skip` | off | on 또는 off |
| `geolocation_refusal_path` | `retry_then_handoff` | `retry_then_handoff`, `continue_without_location`, `end_session` |
| `is_geolocation_geofencing_enabled` | off | on 또는 off |
| `geolocation_ip_distance_km` | 200 km | 0 이상, `null` 설정 시 비교 비활성화 |
| `geolocation_document_distance_km` | off | 0 이상 |
| `geolocation_travel_tolerance_enabled` | off | 일상 활동 지역 10~~500 km(기본값 100), 1~~90일(기본값 14) |
| `geolocation_consecutive_mismatch_count` | off | 2\~10 |

### 프리셋

`geolocation_preset`은 직접 설정하지 않은 모든 작업의 기본값을 지정합니다.
`licensing`은 허용된 지역 외부, 차단된 지역 내부, VPN이나 Tor 뒤에 있거나 에뮬레이터에서 얻은 위치를 거부하고, 프록시는 검토 대상으로 처리합니다.
`fraud_screening`은 동일한 탐지 결과를 적용하지만, `licensing`에서 거부할 항목을 모두 검토 대상으로 보냅니다.
명시적으로 구성한 작업이 항상 우선합니다.

## 지오펜싱

`is_geolocation_geofencing_enabled`를 활성화하고 `geolocation_areas`를 지정합니다.
지역은 국가 전체, 한 국가의 행정 구역(ISO 3166-2), 원형 영역(1~~500 km) 또는 다각형 영역(3~~200개 포인트)으로 정의할 수 있습니다.
허용된 지역 내에 있는 위치만 통과하며, 차단된 지역은 항상 허용된 지역보다 우선합니다.
목록에는 최대 50개의 지역을 포함할 수 있으며 최소 하나 이상의 허용된 지역이 필요합니다.

Didit은 위치의 중심점뿐만 아니라 정확도 원 전체를 판별합니다.

* 모든 허용 지역의 완전히 바깥에 위치한 원은 `LOCATION_OUTSIDE_GEOFENCE`입니다.
* 판별 기준이 되는 경계선과 겹치는 원은 "외부"가 아닌 `LOCATION_GEOFENCE_UNDETERMINED`로 처리됩니다.
* 차단된 지역 내부에 완전히 포함된 원은 `LOCATION_IN_BLOCKED_AREA`이며, 이는 허용 지역 판정 결과와 별도로 추가 발생합니다.

국가 또는 지역의 경계는 해안선이 아닌 다른 육지가 시작되는 지점에서 끝납니다.
사용자에게는 서비스 이용이 가능한 지역만 표시되며, 어떤 지역이 차단되었는지는 절대 표시되지 않습니다.
지역 규칙은 `ip_only` 단계에서도 작동하며, IP 위치를 기준으로 판별됩니다.
이전 버전의 `geolocation_geofencing_by_country` 설정도 계속 작동하지만 `geolocation_areas`와 함께 사용할 수는 없습니다.

## 거리 확인

| 확인 항목 | 측정 대상 | 설정 |
| - | - | - |
| IP 거리 | 두 불확실성 반경을 차감한 후 기기 위치와 IP 위치 사이의 거리입니다(0은 서로 겹침을 의미). | `geolocation_ip_distance_km`, `geolocation_ip_distance_action` |
| 문서 거리 | 위치와 대략적으로 지오코딩된 주소 사이의 거리이므로 약한 신호입니다. | `geolocation_document_distance_km`, `geolocation_document_distance_basis`, `geolocation_document_distance_action` |
| 연속 불일치 | 허용 구역 밖, 차단 구역 내, 또는 주소에서 너무 멀리 떨어진 사용자의 이전 확인 기록(동일한 `vendor_data`)입니다. | `geolocation_consecutive_mismatch_count` |

`geolocation_document_distance_basis`는 주소를 선택합니다. `document`(신분증, 그다음 주소 증명), `proof_of_address`, 또는 `declared`(세션 생성 시의 `expected_details.address`) 중 선택할 수 있습니다.
`geolocation_travel_tolerance_enabled`가 활성화되어 있으면, 지난 `geolocation_travel_max_days`일 이내에 주소 근처에서 확인된 사용자는 현재 주소에서 멀리 떨어져 있더라도 플래그가 지정되지 않습니다.
여행 허용 오차는 VPN, 스푸핑된 위치, 차단된 구역 또는 허용 구역 외부의 위치를 결코 예외로 처리하지 않습니다.

## 스푸핑 및 무결성 신호

* **모의 위치 제공자**: Android 및 iOS는 위치가 실제로 측정되지 않고 시뮬레이션된 경우 이를 보고합니다.
* **기기 증명**: 네이티브 SDK는 기기 증명을 첨부할 수 있습니다. 증명에 실패하면 항상 거부됩니다. 증명이 누락된 경우 기록되며 기본값은 작업 없음입니다. 브라우저는 증명할 수 없으므로 실패가 아닌 `unsupported`로 기록됩니다.
* **VPN, 프록시 및 Tor**: 위치를 공유한 연결에서 감지됩니다. 이 중 하나에 대한 작업이 `NO_ACTION`이 아닌 경우, 시도 횟수가 남아 있는 동안 사용자에게 이를 끄고 다시 확인하도록 요청합니다.
* **에뮬레이터**: 네이티브 앱에서만 보고됩니다. 재시도하더라도 기기가 바뀌지 않으므로 에뮬레이터가 감지되면 해당 시도에서 단계가 종료됩니다.
* **리플레이**: 다른 세션에 제시된 챌린지는 항상 거부됩니다.

## 결과

단계에서 수락된 시도에는 하나의 `outcome`이 부여됩니다.

| 결과 | 의미 |
| - | - |
| `verified` | 모든 규칙을 충족한 위치입니다. |
| `low_accuracy` / `accuracy_undetermined` | 반경이 제한값보다 넓거나 기기에서 반경을 보고하지 않았습니다. |
| `stale` | 위치가 `geolocation_max_age_seconds`보다 오래되었습니다. |
| `approximate` | 정확한 위치가 필요했으나 대략적인 위치만 허용되었습니다. |
| `denied` / `restricted` | 사용자가 거부했거나 시스템에서 위치를 차단했습니다. |
| `unavailable` / `timeout` | 기기가 위치를 찾지 못했거나 제시간에 찾지 못했습니다. |
| `mock_detected` | 시스템에서 위치가 시뮬레이션된 것으로 보고했습니다. |
| `outside_geofence` / `in_blocked_area` | 위치가 모든 허용 구역 외부에 있거나 차단된 구역 내에 있습니다. |
| `anonymizer_detected` | VPN, 프록시, Tor 출구 노드 또는 에뮬레이터가 감지되었으며 워크플로가 이에 대응하도록 설정되어 있습니다. |
| `skipped` | 사용자가 위치를 공유하지 않고 계속 진행했습니다. |
| `replay_rejected` | 챌린지가 다른 세션에 속해 있었습니다. |
| `unsupported_client` | 앱 또는 SDK가 너무 오래되어 단계를 표시할 수 없습니다. |

시도 횟수가 남아 있는 동안 반경이 넓거나, 오래되었거나, 대략적이거나, 거부되었거나, 구역 관련 문제가 발견되면 사용자에게 다시 시도하도록 요청하며, 마지막 시도에서만 경고가 발생합니다.
시뮬레이션된 위치나 워크플로가 조치하도록 설정된 에뮬레이터의 경우, 이를 보고한 해당 시도에서 단계가 즉시 종료됩니다.

## 사용자 경험

### 동의 및 권한

사용자가 안내를 수락하고 시스템 프롬프트에 응답하기 전에는 어떠한 정보도 읽지 않습니다.
안내에는 이번 인증을 위해 위치를 한 번만 확인하며 이동 기록을 저장하지 않는다는 내용이 명시됩니다.
이를 거부한 사용자는 `geolocation_refusal_path`에 따라 처리됩니다.

* `retry_then_handoff`는 시도 횟수가 남아 있는 동안 다시 요청한 후 휴대폰에서 계속 진행할 수 있는 옵션을 제공합니다.
* `continue_without_location`은 위치 정보 없이 계속 진행할 수 있도록 안내하고 거부를 결과로 기록합니다.
* `end_session`은 첫 번째 거부 시 단계와 세션을 종료합니다. 이를 사용하려면 `geolocation_permission_denied_action`이 `REVIEW` 또는 `DECLINE`으로 설정되어 있어야 하며, 세션은 절대 승인되지 않습니다.

`geolocation_allow_skip`이 활성화되어 있으면 사용자는 언제든지 위치 정보 없이 계속 진행할 수 있으며, 이 단계는 `geolocation_unavailable_action`에 따라 판정됩니다.

### 브라우저

호스팅 플로우는 브라우저에 위치를 요청하며, 사이트의 위치 권한이 꺼져 있는 경우 Chrome 및 Safari에 대한 단계별 안내를 표시합니다.
브라우저는 정확한 위치 권한과 대략적인 위치 권한을 구분할 수 없으므로 웹 결과에서는 `LOCATION_APPROXIMATE_ONLY`가 발생하지 않으며, 모의 위치 제공자, 에뮬레이터 또는 증명도 보고하지 않습니다.
컴퓨터는 정확한 위치를 공유할 수 없으므로 사용자의 휴대폰에서 동일한 인증을 계속 진행할 수 있는 QR 코드를 제공하며(`geolocation_allow_qr_handoff`, 기본적으로 활성화됨), 휴대폰에서 완료되면 컴퓨터가 자동으로 다음 단계로 이동합니다.
플로우를 iframe에 삽입할 때는 `allow` 속성에 `geolocation`을 포함해야 합니다. 자세한 내용은 [인컨텍스트 iframe](https://docs.didit.me/ko/integration/web-sdks/incontext-iframe.md)을 참조하세요.
위치 정보 권한 정책을 차단하는 페이지는 사용자의 거부가 아닌 사이트 측의 결정으로 처리됩니다.

### 네이티브 SDK

iOS 및 Android SDK는 운영체제에 요청하며 기기 증명 및 모의 위치 플래그를 첨부할 수 있습니다.
iOS에서는 `Info.plist`에 `NSLocationWhenInUseUsageDescription`을 추가해야 하며, Android에서는 SDK가 `ACCESS_FINE_LOCATION` 및 `ACCESS_COARSE_LOCATION`을 선언하고 워크플로에 이 단계가 포함된 경우에만 런타임 시 요청합니다.
자세한 내용은 [네이티브 SDK](https://docs.didit.me/ko/integration/native-sdks/overview.md)를 참조하세요.
`geolocation_accuracy_mode`가 `approximate_allowed`가 아닌 경우, iOS 또는 Android에서 대략적인 위치 권한을 부여하면 `LOCATION_APPROXIMATE_ONLY`가 발생합니다.
해당 단계가 도입되기 전의 앱 또는 SDK 빌드는 세션이 멈춘 상태로 방치되지 않고 `unsupported_client`로 종료 처리됩니다.

## 결정이 반환하는 내용

[세션 결정](https://docs.didit.me/ko/sessions-api/retrieve-session.md)과 `status.updated` webhook에는 두 가지 목록이 포함됩니다.

* `geolocation_checks[]`: Location 단계당 하나의 항목으로, 해당 단계에서 승인된 시도와 그에 따른 `warnings`를 포함합니다.
* `geolocation_attempts[]`: 모든 Location 단계의 모든 시도가 가장 오래된 순서대로 포함됩니다.

모든 필드에 대한 자세한 내용은 [위치 인증 보고서](https://docs.didit.me/ko/core-technology/location-verification/report-location-verification.md)를 참조하십시오.
좌표, 정확도, 도시 및 국가는 최종 사용자의 개인정보이므로, 워크플로의 응답 속성을 설정하여 결정에서 반환할 `geolocation_checks` 필드를 제한할 수 있습니다.

## 요금

위치 인증 비용은 **검사당 \$0.05**이며, 무료 요금제에는 포함되지 않습니다.
검사가 실행되어 결과를 반환했으므로, Didit은 결과와 관계없이 세션 내 Location 단계당 한 번 요금을 부과합니다.
동일한 단계 내에서의 재시도는 무료입니다.
해당 단계를 다시 완료하는 재제출에는 요금이 다시 부과됩니다.

## 샌드박스

샌드박스 세션은 동일한 호스팅 흐름에서 동일한 단계를 실행하며, 기기 또는 브라우저는 여전히 실제 위치를 보고합니다.
샌드박스 세션은 IP 조회 서비스에 접근하지 않으므로, IP 비교 시 세션에 이미 포함된 정보만 사용합니다.
사용량은 가격이 0으로 기록되므로 샌드박스 세션에는 요금이 청구되지 않습니다.
이 단계에는 매직 입력이 없습니다.

## 관련 문서

* [위치 인증 보고서](https://docs.didit.me/ko/core-technology/location-verification/report-location-verification.md) - `geolocation_checks[]` 및 `geolocation_attempts[]`의 모든 필드.
* [위치 인증 경고](https://docs.didit.me/ko/core-technology/location-verification/warnings-location-verification.md) - 모든 `LOCATION_*` 코드 및 해당 작업.
* [워크플로 기능 설정](https://docs.didit.me/ko/management-api/workflows/feature-configs.md#위치-확인) - 모든 `geolocation_*` 키.
* [기기 및 IP 분석](https://docs.didit.me/ko/core-technology/ip-analysis/overview.md) - 세션에 대한 IP 위치 확인 및 VPN 검사.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.