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

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

​

사용 시기

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

​

작동 방식

​

위치 소스

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

​

구성 기본값 및 제한

모든 키는 선택 사항입니다. 전체 목록은 워크플로 기능 구성 레퍼런스에서 확인할 수 있습니다.

​

프리셋

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

​

지오펜싱

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

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

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

​

거리 확인

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

​

사용자 경험

​

동의 및 권한

사용자가 안내를 수락하고 시스템 프롬프트에 응답하기 전에는 어떠한 정보도 읽지 않습니다. 안내에는 이번 인증을 위해 위치를 한 번만 확인하며 이동 기록을 저장하지 않는다는 내용이 명시됩니다. 이를 거부한 사용자는 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을 참조하세요. 위치 정보 권한 정책을 차단하는 페이지는 사용자의 거부가 아닌 사이트 측의 결정으로 처리됩니다.

​

네이티브 SDK

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

​

결정이 반환하는 내용

세션 결정과 status.updated webhook에는 두 가지 목록이 포함됩니다.

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

모든 필드에 대한 자세한 내용은 위치 인증 보고서를 참조하십시오. 좌표, 정확도, 도시 및 국가는 최종 사용자의 개인정보이므로, 워크플로의 응답 속성을 설정하여 결정에서 반환할 geolocation_checks 필드를 제한할 수 있습니다.

​

요금

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

​

샌드박스

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

​

관련 문서

• 위치 인증 보고서 - geolocation_checks[] 및 geolocation_attempts[]의 모든 필드.
• 위치 인증 경고 - 모든 LOCATION_* 코드 및 해당 작업.
• 워크플로 기능 설정 - 모든 geolocation_* 키.
• 기기 및 IP 분석 - 세션에 대한 IP 위치 확인 및 VPN 검사.