본문으로 건너뛰기

location

기기의 위치를 한 번만 가져오거나, 사용자가 움직이는 동안 실시간으로 구독하는 네임스페이스입니다. 가까운 매장 찾기, 배달 주소 자동 채우기, 산책 거리 측정 같은 위치 기반 UX에 쓰입니다.

비공식 문서

이 페이지는 커뮤니티가 작성한 설명입니다. SDK의 동작은 상위의 @apps-in-toss/web-framework 배포본을 기준으로 합니다.

메서드​

메서드용도
getCurrentLocation현재 위치를 한 번만 조회합니다.
startUpdateLocation위치 변화를 콜백으로 구독하고, 해제 함수를 반환합니다.

권한​

네임스페이스 전체가 단일 geolocation 권한을 공유합니다. 두 메서드 모두 같은 PermissionName에 바인딩되어 있어, 한쪽에서 승인받으면 다른 쪽도 즉시 사용 가능합니다.

  • denied 상태에서 호출하면 에러가 throw 되니, 호출 전 권한 상태를 먼저 확인하세요.
  • notDetermined 상태에서는 시스템 다이얼로그를 띄워 사용자에게 승인을 받을 수 있습니다.
  • 정확도(accuracy)와 권한 등급(accessLocation: FINE / COARSE)은 별개의 개념입니다. iOS/Android 모두 사용자가 "대략적인 위치"만 허용한 경우 COARSE가 반환될 수 있고, 이때는 좌표의 오차 범위가 큽니다.

두 메서드 모두 getPermission() / openPermissionDialog() 유틸이 함수 객체에 붙어 있습니다 — 각 페이지의 "권한" 섹션을 참고하세요.

좌표 페이로드​

두 메서드 모두 동일한 Location 형태의 객체를 반환합니다.

interface Location {
  coords: {
    latitude: number;       // 위도
    longitude: number;      // 경도
    altitude: number;       // 고도(m). 플랫폼이 측정 불가로 보고하면 0으로 정규화됩니다 — 0이 곧 "측정 불가"를 의미하지는 않습니다(해수면도 0).
    accuracy: number;       // 위·경도 오차 반경(m). 작을수록 정확
    altitudeAccuracy: number; // 고도 오차(m)
    heading: number;        // 진행 방향(0~360°). 정지 상태이거나 측정 불가일 때 0이 반환되므로 "정북"과 구분되지 않습니다.
  };
  timestamp: number;        // 측정 시각 (ms epoch)
  accessLocation?: 'FINE' | 'COARSE';
}

UX 가이드​

  • 권한 요청 전에 이유를 보여 주세요. "근처 매장을 찾으려면 위치가 필요해요" 같은 한 줄이 권한 승인률을 크게 바꿉니다.
  • 단발성 조회면 getCurrentLocation을, 이동 추적이면 startUpdateLocation을 쓰세요. 1회면 충분한데 watch를 걸면 배터리/데이터를 낭비하고 OS가 백그라운드에서 호출을 throttle 할 수 있습니다.
  • 반환된 unsubscribe 함수를 반드시 호출하세요. React라면 useEffect의 cleanup에서 호출하는 것이 표준 패턴입니다.
  • accuracy 값을 항상 검사하세요. 실내·터널·GPS 미수신 상황에서는 수백 미터까지 벌어질 수 있습니다.
  • 사용자에게 좌표를 그대로 보여 주지 말고 reverse geocoding을 거쳐 주소·동네 이름으로 표현하는 것이 일반적입니다.

직접 실행해 보기​

sdk-example의 Location 페이지에서 두 메서드를 모두 실험해 볼 수 있습니다.

sdk-example에서 실행해 보기

외부 참조​