백그라운드 Geolocation Capacitor 플러그인

@capgo/background-geolocation 사용하기

iOS 및 Android용 Capacitor 앱을 위한 정밀한 백그라운드 위치 정보 및 네이티브 geofencing을 제공합니다. 정밀한 위치 업데이트 스트리밍, 특정 영역 모니터링, geofence 진입/이탈 이벤트를 JavaScript나 백엔드로 전달하는 데 사용하세요.

설치

bun add @capgo/background-geolocation
bunx cap sync

플러그인이 제공하는 기능

• start - 정확한 포그라운드 또는 백그라운드 위치 업데이트를 스트리밍합니다.
• stop - 진행 중인 위치 추적 중지
• openSettings - 위치 권한 수정이 필요한 경우 네이티브 설정 열기
• setPlannedRoute - 사용자가 계획된 경로를 벗어날 때 네이티브 사운드 재생
• setupGeofencing - 네이티브 geofence 기본값 및 선택적 transition webhook 전달 설정
• addGeofence - iOS 또는 Android의 원형 geofence 영역 모니터링
• removeGeofence / removeAllGeofences - 등록된 영역 하나 또는 전체 모니터링 중지
• getMonitoredGeofences - 모니터링 중인 영역 식별자 목록 조회
• geofenceTransition listener - 앱이 활성 상태인 동안 enter 및 exit 이벤트 수신
• geofenceError listener - transition 이벤트와 별개로 네이티브 모니터링 에러 처리

사용 예시

start

기기의 위치 변경 사항을 감지하려면 이 메서드를 호출하세요. 호출이 완료되면 Promise가 반환됩니다. 새로운 위치가 확인되거나 메서드 호출 중 오류가 발생할 때마다 콜백이 실행됩니다. 오류 처리를 위해 Promise rejection에만 의존하지 마세요.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.start(
  {
    backgroundMessage: "App is using your location in the background",
    backgroundTitle: "Location Service",
    requestPermissions: true,
    stale: false,
    distanceFilter: 10
  },
  (location, error) => {
    if (error) {
      console.error('Location error:', error);
      return;
    }
    if (location) {
      console.log('New location:', location.latitude, location.longitude);
    }
  }
);

stop

위치 업데이트를 중단합니다.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.stop();

openSettings

기기의 위치 설정 페이지를 엽니다. 사용자가 위치 서비스를 활성화하거나 권한을 조정하도록 안내할 때 유용합니다.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

// Direct user to location settings
await BackgroundGeolocation.openSettings();

setPlannedRoute

사용자가 계획된 경로를 벗어나면 사운드 파일을 재생합니다. 백그라운드에서도 사운드를 재생할 때 사용하세요 (Native 환경 전용).

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setPlannedRoute({
  soundFile: "notification.mp3",
  route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});

네이티브 지오펜싱

iOS 및 Android의 Native geofence를 사용하여 매장, 작업 현장, 배송 구역, 캠퍼스 또는 체크인 구역을 모니터링하세요. HTTP 또는 HTTPS를 추가하여 url WebView가 중단된 동안 Native code가 POST transition payload를 전송할 수 있도록 합니다.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofences',
  notifyOnEntry: true,
  notifyOnExit: true,
  payload: { userId: '123' },
});

await BackgroundGeolocation.addGeofence({
  identifier: 'warehouse',
  latitude: 40.7128,
  longitude: -74.006,
  radius: 200,
});

const listener = await BackgroundGeolocation.addListener(
  'geofenceTransition',
  (event) => console.log(event.identifier, event.transition),
);

const errorListener = await BackgroundGeolocation.addListener(
  'geofenceError',
  (event) => console.error(event.identifier, event.message),
);

await BackgroundGeolocation.removeGeofence({ identifier: 'warehouse' });
await listener.remove();
await errorListener.remove();

Android의 경우, ACCESS_BACKGROUND_LOCATION 백그라운드 geofencing이 필요한 경우에만 앱 매니페스트에 추가하세요:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

전체 레퍼런스

• GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
• 문서: /docs/plugins/background-geolocation/

@capgo/background-geolocation 사용하기 계속 보기

사용 중이라면 @capgo/background-geolocation 사용하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/background-geolocation @capgo/background-geolocation의 구현 세부 사항은 시작하기 Getting Started의 구현 상세 내용은 Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor Plugins 구현 세부 사항 및 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항은.