본문 바로가기
@capgo/background-geolocation 위치 오픈 소스

백그라운드 Geolocation Capacitor 플러그인

iOS 및 Android 네이티브 지오펜싱과 transition webhook을 지원하는 정확한 백그라운드 위치 추적

설치

bun add @capgo/background-geolocation bunx cap sync
npm, pnpm 또는 yarn
  • npm install @capgo/background-geolocation
  • pnpm add @capgo/background-geolocation
  • yarn add @capgo/background-geolocation

가이드

Capacitor에서 Background Geolocation 사용 방법

@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

사용자가 계획된 경로에서 벗어날 때 사운드 파일을 재생합니다. 이는 사운드를 재생하는 데 사용해야 합니다(백그라운드에서도, 네이티브 전용).

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

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

네이티브 지오펜싱

네이티브 iOS 및 Android 지오펜스를 사용하여 매장, 작업 현장, 배송 구역, 캠퍼스 또는 체크인 지역을 모니터링하세요. HTTP 또는 HTTPS를 추가하여 url WebView가 일시 중지된 동안 네이티브 code가 전환 페이로드를 POST하도록 하세요.

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 을(를) 추가하세요:

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

전체 레퍼런스

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

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

자주 묻는 질문

Background Geolocation 플러그인 FAQ

Capacitor 앱에 Background Geolocation 플러그인을 어떻게 설치하나요?

"bun add @capgo/background-geolocation"(또는 "npm install @capgo/background-geolocation")을 실행한 뒤 "bunx cap sync"를 실행해 iOS와 Android 프로젝트가 네이티브 code를 가져오도록 하세요. 앱 code에서 "@capgo/background-geolocation"에서 import 하면 됩니다.

@capgo/background-geolocation가 React, Vue, Angular와 호환되나요?

네. Background Geolocation은 Capacitor 패키지이므로 Ionic, React, Vue, Angular, Svelte 및 일반 JavaScript를 포함해 Capacitor 안에서 실행되는 모든 웹 프레임워크와 호환됩니다.

@capgo/background-geolocation은 어떤 Capacitor 버전을 지원하나요?

Capgo 플러그인은 Capacitor의 메이저 버전을 따릅니다. 사용 중인 Capacitor 메이저 버전과 일치하는 플러그인 메이저 버전을 사용하세요 (예: Capacitor 8에는 플러그인 v8). 유지 관리되는 버전은 GitHub README의 호환성 표에서 확인할 수 있습니다.

@capgo/background-geolocation는 무료이며 오픈 소스인가요?

네. code 소스는 GitHub의 https://github.com/Cap-go/capacitor-background-geolocation/에 공개되어 있고, npm에서 무료로 설치할 수 있습니다. 버그 리포트와 pull request를 환영합니다.

App Store 심사 없이 Background Geolocation을 사용하는 code를 업데이트할 수 있나요?

플러그인을 설치하거나 업그레이드하면 네이티브 code가 변경되므로 새로운 스토어 빌드가 필요합니다. 그 이후에는 플러그인을 호출하는 JavaScript, HTML, CSS 변경 사항을 Capgo live updates로 즉시 배포할 수 있습니다.

앱 심사 기다리지 않고 Background Geolocation 변경 사항을 배포하세요

스토어 빌드에 플러그인이 포함되면, Capgo live updates로 JavaScript, HTML, CSS 변경 사항을 몇 분 만에 사용자에게 푸시할 수 있습니다.

Capgo로 시작하기