위치 추적

네이버 지도 SDK의 위치 추적 기능을 사용하면 사용자의 현재 위치를 지도에 표시하고, 카메라가 위치를 따라가도록 설정할 수 있습니다.

LocationTrackingMode

모드	설명
`'None'`	위치 추적 비활성화
`'NoFollow'`	현위치 오버레이만 이동, 카메라는 고정
`'Follow'`	현위치 오버레이와 카메라가 위치 따라 이동. 제스처 또는 API로 카메라 이동 시 `NoFollow`로 전환
`'Face'`	현위치 오버레이, 카메라 좌표, 방위각이 위치/방향 따라 이동. 제스처 또는 API로 카메라 이동 시 `NoFollow`로 전환

기본 설정

위치 권한 요청

위치 추적을 사용하기 전에 OS 위치 권한을 요청해야 합니다.

import { PermissionsAndroid, Platform } from 'react-native';

async function requestLocationPermission() {
  if (Platform.OS === 'android') {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
    );
    return granted === PermissionsAndroid.RESULTS.GRANTED;
  }
  // iOS는 Info.plist 설정 후 SDK가 자동으로 권한 요청
  return true;
}

위치 추적 모드 설정

NaverMapViewRef의 setLocationTrackingMode로 위치 추적 모드를 변경합니다.

import React, { useRef, useEffect } from 'react';
import { NaverMapView, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

export default function LocationTrackingMap() {
  const mapRef = useRef<NaverMapViewRef>(null);

  const startTracking = async () => {
    const hasPermission = await requestLocationPermission();
    if (hasPermission) {
      mapRef.current?.setLocationTrackingMode('Follow');
    }
  };

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{ latitude: 37.5, longitude: 126.9, zoom: 14 }}
      isShowLocationButton
      locationOverlay={{
        isVisible: true,
      }}
      onInitialized={startTracking}
      onOptionChanged={({ locationTrackingMode }) => {
        console.log('추적 모드 변경:', locationTrackingMode);
      }}
    />
  );
}

위치 오버레이 커스터마이징

현위치 오버레이의 외관을 locationOverlay prop으로 커스터마이징할 수 있습니다.

<NaverMapView
  locationOverlay={{
    isVisible: true,
    // 커스텀 아이콘
    image: require('./assets/my-location-icon.png'),
    imageWidth: 40,
    imageHeight: 40,
    anchor: { x: 0.5, y: 0.5 },
    // 서브 아이콘 (방향 표시 등)
    subImage: require('./assets/direction-arrow.png'),
    subImageWidth: 20,
    subImageHeight: 20,
    subAnchor: { x: 0.5, y: 0.5 },
    // 정확도 원
    circleRadius: 80,
    circleColor: 'rgba(66, 133, 244, 0.15)',
    circleOutlineWidth: 1,
    circleOutlineColor: 'rgba(66, 133, 244, 0.5)',
  }}
/>

locationOverlay 속성

속성	타입	기본값	설명
`isVisible`	`boolean`	`false`	현위치 오버레이 표시 여부
`position`	`Coord`	-	수동으로 위치 지정 (추적 모드와 함께 사용 시 SDK가 업데이트)
`bearing`	`number`	`0`	방향 각도
`image`	`MapImageProp`	-	메인 아이콘 이미지
`imageWidth`	`number`	`SIZE_AUTO`	메인 아이콘 너비
`imageHeight`	`number`	`SIZE_AUTO`	메인 아이콘 높이
`anchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	앵커 포인트
`subImage`	`MapImageProp`	-	서브 아이콘 이미지
`subImageWidth`	`number`	`SIZE_AUTO`	서브 아이콘 너비
`subImageHeight`	`number`	`SIZE_AUTO`	서브 아이콘 높이
`subAnchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	서브 아이콘 앵커
`circleRadius`	`number`	`0`	정확도 원 반경 (픽셀)
`circleColor`	`ColorValue`	-	정확도 원 색상
`circleOutlineWidth`	`number`	`0`	정확도 원 테두리 두께
`circleOutlineColor`	`ColorValue`	-	정확도 원 테두리 색상

추적 모드 버튼 (isShowLocationButton)

isShowLocationButton={true}로 설정하면 화면에 현위치 버튼이 표시됩니다. 사용자가 버튼을 탭하면 추적 모드가 순환 변경됩니다.

<NaverMapView
  isShowLocationButton
  locationOverlay={{ isVisible: true }}
/>

추적 모드 변경 감지

onOptionChanged를 사용하면 추적 모드가 변경될 때 알림을 받을 수 있습니다. 사용자가 제스처로 카메라를 이동하면 Follow 또는 Face 모드가 자동으로 NoFollow로 전환되는데, 이를 감지하는 데 유용합니다.

<NaverMapView
  onOptionChanged={({ locationTrackingMode }) => {
    if (locationTrackingMode === 'NoFollow') {
      // 사용자가 지도를 직접 이동함 -> Follow 모드 복구 버튼 표시 등
      showReturnToCurrentLocationButton();
    }
  }}
/>

전체 예제

import React, { useRef, useState } from 'react';
import { Button, PermissionsAndroid, Platform, StyleSheet, View } from 'react-native';
import {
  NaverMapView,
  type LocationTrackingMode,
  type NaverMapViewRef,
} from '@boostbrothers/react-native-naver-map';

export default function LocationTrackingExample() {
  const mapRef = useRef<NaverMapViewRef>(null);
  const [trackingMode, setTrackingMode] = useState<LocationTrackingMode>('None');

  const requestPermission = async () => {
    if (Platform.OS === 'android') {
      const result = await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
      );
      return result === PermissionsAndroid.RESULTS.GRANTED;
    }
    return true;
  };

  const toggleTracking = async () => {
    const hasPermission = await requestPermission();
    if (!hasPermission) return;

    const nextMode: LocationTrackingMode = trackingMode === 'None' ? 'Follow' : 'None';
    mapRef.current?.setLocationTrackingMode(nextMode);
    setTrackingMode(nextMode);
  };

  return (
    <View style={styles.container}>
      <NaverMapView
        ref={mapRef}
        style={styles.map}
        initialCamera={{ latitude: 37.5666102, longitude: 126.9783881, zoom: 14 }}
        isShowLocationButton
        locationOverlay={{
          isVisible: trackingMode !== 'None',
          circleRadius: 60,
          circleColor: 'rgba(66, 133, 244, 0.15)',
          circleOutlineWidth: 1,
          circleOutlineColor: 'rgba(66, 133, 244, 0.5)',
        }}
        onOptionChanged={({ locationTrackingMode }) => {
          setTrackingMode(locationTrackingMode);
        }}
      />
      <Button
        title={trackingMode === 'None' ? '위치 추적 시작' : '위치 추적 중지'}
        onPress={toggleTracking}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  map: { flex: 1 },
});

위치 추적 기능을 사용하려면 반드시 사용자에게 위치 권한을 요청해야 합니다. iOS에서는 Info.plist에 권한 설명 문자열을 추가해야 합니다. Android에서는 런타임 권한 요청이 필요합니다.

위치 추적

네이버 지도 SDK의 위치 추적 기능을 사용하면 사용자의 현재 위치를 지도에 표시하고, 카메라가 위치를 따라가도록 설정할 수 있습니다.

LocationTrackingMode

모드	설명
`'None'`	위치 추적 비활성화
`'NoFollow'`	현위치 오버레이만 이동, 카메라는 고정
`'Follow'`	현위치 오버레이와 카메라가 위치 따라 이동. 제스처 또는 API로 카메라 이동 시 `NoFollow`로 전환
`'Face'`	현위치 오버레이, 카메라 좌표, 방위각이 위치/방향 따라 이동. 제스처 또는 API로 카메라 이동 시 `NoFollow`로 전환

기본 설정

위치 권한 요청

위치 추적을 사용하기 전에 OS 위치 권한을 요청해야 합니다.

import { PermissionsAndroid, Platform } from 'react-native';

async function requestLocationPermission() {
  if (Platform.OS === 'android') {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
    );
    return granted === PermissionsAndroid.RESULTS.GRANTED;
  }
  // iOS는 Info.plist 설정 후 SDK가 자동으로 권한 요청
  return true;
}

위치 추적 모드 설정

NaverMapViewRef의 setLocationTrackingMode로 위치 추적 모드를 변경합니다.

import React, { useRef, useEffect } from 'react';
import { NaverMapView, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

export default function LocationTrackingMap() {
  const mapRef = useRef<NaverMapViewRef>(null);

  const startTracking = async () => {
    const hasPermission = await requestLocationPermission();
    if (hasPermission) {
      mapRef.current?.setLocationTrackingMode('Follow');
    }
  };

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{ latitude: 37.5, longitude: 126.9, zoom: 14 }}
      isShowLocationButton
      locationOverlay={{
        isVisible: true,
      }}
      onInitialized={startTracking}
      onOptionChanged={({ locationTrackingMode }) => {
        console.log('추적 모드 변경:', locationTrackingMode);
      }}
    />
  );
}

위치 오버레이 커스터마이징

현위치 오버레이의 외관을 locationOverlay prop으로 커스터마이징할 수 있습니다.

<NaverMapView
  locationOverlay={{
    isVisible: true,
    // 커스텀 아이콘
    image: require('./assets/my-location-icon.png'),
    imageWidth: 40,
    imageHeight: 40,
    anchor: { x: 0.5, y: 0.5 },
    // 서브 아이콘 (방향 표시 등)
    subImage: require('./assets/direction-arrow.png'),
    subImageWidth: 20,
    subImageHeight: 20,
    subAnchor: { x: 0.5, y: 0.5 },
    // 정확도 원
    circleRadius: 80,
    circleColor: 'rgba(66, 133, 244, 0.15)',
    circleOutlineWidth: 1,
    circleOutlineColor: 'rgba(66, 133, 244, 0.5)',
  }}
/>

locationOverlay 속성

속성	타입	기본값	설명
`isVisible`	`boolean`	`false`	현위치 오버레이 표시 여부
`position`	`Coord`	-	수동으로 위치 지정 (추적 모드와 함께 사용 시 SDK가 업데이트)
`bearing`	`number`	`0`	방향 각도
`image`	`MapImageProp`	-	메인 아이콘 이미지
`imageWidth`	`number`	`SIZE_AUTO`	메인 아이콘 너비
`imageHeight`	`number`	`SIZE_AUTO`	메인 아이콘 높이
`anchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	앵커 포인트
`subImage`	`MapImageProp`	-	서브 아이콘 이미지
`subImageWidth`	`number`	`SIZE_AUTO`	서브 아이콘 너비
`subImageHeight`	`number`	`SIZE_AUTO`	서브 아이콘 높이
`subAnchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	서브 아이콘 앵커
`circleRadius`	`number`	`0`	정확도 원 반경 (픽셀)
`circleColor`	`ColorValue`	-	정확도 원 색상
`circleOutlineWidth`	`number`	`0`	정확도 원 테두리 두께
`circleOutlineColor`	`ColorValue`	-	정확도 원 테두리 색상

추적 모드 버튼 (isShowLocationButton)

isShowLocationButton={true}로 설정하면 화면에 현위치 버튼이 표시됩니다. 사용자가 버튼을 탭하면 추적 모드가 순환 변경됩니다.

<NaverMapView
  isShowLocationButton
  locationOverlay={{ isVisible: true }}
/>

추적 모드 변경 감지

<NaverMapView
  onOptionChanged={({ locationTrackingMode }) => {
    if (locationTrackingMode === 'NoFollow') {
      // 사용자가 지도를 직접 이동함 -> Follow 모드 복구 버튼 표시 등
      showReturnToCurrentLocationButton();
    }
  }}
/>

전체 예제

import React, { useRef, useState } from 'react';
import { Button, PermissionsAndroid, Platform, StyleSheet, View } from 'react-native';
import {
  NaverMapView,
  type LocationTrackingMode,
  type NaverMapViewRef,
} from '@boostbrothers/react-native-naver-map';

export default function LocationTrackingExample() {
  const mapRef = useRef<NaverMapViewRef>(null);
  const [trackingMode, setTrackingMode] = useState<LocationTrackingMode>('None');

  const requestPermission = async () => {
    if (Platform.OS === 'android') {
      const result = await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
      );
      return result === PermissionsAndroid.RESULTS.GRANTED;
    }
    return true;
  };

  const toggleTracking = async () => {
    const hasPermission = await requestPermission();
    if (!hasPermission) return;

    const nextMode: LocationTrackingMode = trackingMode === 'None' ? 'Follow' : 'None';
    mapRef.current?.setLocationTrackingMode(nextMode);
    setTrackingMode(nextMode);
  };

  return (
    <View style={styles.container}>
      <NaverMapView
        ref={mapRef}
        style={styles.map}
        initialCamera={{ latitude: 37.5666102, longitude: 126.9783881, zoom: 14 }}
        isShowLocationButton
        locationOverlay={{
          isVisible: trackingMode !== 'None',
          circleRadius: 60,
          circleColor: 'rgba(66, 133, 244, 0.15)',
          circleOutlineWidth: 1,
          circleOutlineColor: 'rgba(66, 133, 244, 0.5)',
        }}
        onOptionChanged={({ locationTrackingMode }) => {
          setTrackingMode(locationTrackingMode);
        }}
      />
      <Button
        title={trackingMode === 'None' ? '위치 추적 시작' : '위치 추적 중지'}
        onPress={toggleTracking}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  map: { flex: 1 },
});

위치 추적

위치 추적

LocationTrackingMode

기본 설정

위치 권한 요청

위치 추적 모드 설정

위치 오버레이 커스터마이징

locationOverlay 속성

추적 모드 버튼 (isShowLocationButton)

추적 모드 변경 감지

전체 예제

On this page

위치 추적

위치 추적

LocationTrackingMode

기본 설정

위치 권한 요청

위치 추적 모드 설정

위치 오버레이 커스터마이징

locationOverlay 속성

추적 모드 버튼 (isShowLocationButton)

추적 모드 변경 감지

전체 예제

On this page