시작하기

@capgo/background-geolocation iOS 및 Android에서 원시적인 지오 펜싱과 함께 정확한 배경 위치 추적을 결합합니다. 배송 구역, 매장, 작업 현장, 캠퍼스, 체크인, 경로 알림, WebView가 실행되지 않는 경우에도 입/출 이벤트가 필요한 모든 워크플로우를 위해 사용하십시오.

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 스킬을 추가하려면 다음 명령어를 사용하십시오.

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

다음 명령어를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/background-geolocation` plugin in my project.

만약 Manual Setup을 선호한다면, 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/background-geolocation
bunx cap sync

import

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

API 개요

start

장치의 위치 변경을 감지하기 위해 시작하려면 이 메서드를 호출하세요. 이 메서드 호출이 완료된 후 Promise가 반환됩니다. callback 함수는 새로운 위치가 사용자에게 제공되거나 이 메서드를 호출할 때 오류가 발생할 때마다 호출됩니다. Promise 거부에 의존하지 마세요.

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는 WebView가 깨어있지 않아도 enter와 exit 이벤트를 트리거할 수 있습니다. 백엔드가 전환을 받으려면 앱 UI가 중단된 상태에서도 HTTP 또는 HTTPS 웹후크 URL을 구성해야 합니다.

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: 'store-42',
  latitude: 37.33182,
  longitude: -122.03118,
  radius: 150,
  payload: { storeId: '42' },
});

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

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

const { regions } = await BackgroundGeolocation.getMonitoredGeofences();
console.log(regions);

await BackgroundGeolocation.removeGeofence({ identifier: 'store-42' });
await handle.remove();
await errorHandle.remove();

iOS에서 지오펜싱은 항상 위치 권한이 필요합니다. Android 10 이상에서 백그라운드 지오펜싱이 필요할 때는 앱 매니페스트에 백그라운드 위치 권한을 추가해야 합니다.

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

타입 참조

StartOptions

위치 업데이트 구성 옵션입니다.

export interface StartOptions {
  /**
   * If the "backgroundMessage" option is defined, the plugin will
   * provide location updates whether the app is in the background or the
   * foreground. If it is not defined, location updates are only
   * guaranteed in the foreground. This is true on both platforms.
   *
   * On Android, a notification must be shown to continue receiving
   * location updates in the background. This option specifies the text of
   * that notification.
   *
   * @since 7.0.9
   * @example "Getting your location to provide better service"
   */
  backgroundMessage?: string;
  /**
   * The title of the notification mentioned above.
   *
   * @since 7.0.9
   * @default "Using your location"
   * @example "Location Service"
   */
  backgroundTitle?: string;
  /**
   * Whether permissions should be requested from the user automatically,
   * if they are not already granted.
   *
   * @since 7.0.9
   * @default true
   * @example
   * // Auto-request permissions
   * requestPermissions: true
   *
   * // Don't auto-request, handle manually
   * requestPermissions: false
   */
  requestPermissions?: boolean;
  /**
   * If "true", stale locations may be delivered while the device
   * obtains a GPS fix. You are responsible for checking the "time"
   * property. If "false", locations are guaranteed to be up to date.
   *
   * @since 7.0.9
   * @default false
   * @example
   * // Allow stale locations for faster initial response
   * stale: true
   *
   * // Only fresh locations
   * stale: false
   */
  stale?: boolean;
  /**
   * The distance in meters that the device must move before a new location update is triggered.
   * This is used to filter out small movements and reduce the number of updates.
   *
   * @since 7.0.9
   * @default 0
   * @example
   * // Update every 10 meters
   * distanceFilter: 10
   *
   * // Update on any movement
   * distanceFilter: 0
   */
  distanceFilter?: number;
}

Location

위치에 대한 다양한 특성을 나타내는 지리적 위치입니다. GPS/네트워크 제공자에서 반환하는 표준 위치 속성을 모두 포함합니다.

export interface Location {
  /**
   * Latitude in degrees.
   * Range: -90.0 to +90.0
   *
   * @since 7.0.0
   * @example 40.7128
   */
  latitude: number;
  /**
   * Longitude in degrees.
   * Range: -180.0 to +180.0
   *
   * @since 7.0.0
   * @example -74.0060
   */
  longitude: number;
  /**
   * Radius of horizontal uncertainty in metres, with 68% confidence.
   * Lower values indicate more accurate location.
   *
   * @since 7.0.0
   * @example 5.0
   */
  accuracy: number;
  /**
   * Metres above sea level (or null if not available).
   *
   * @since 7.0.0
   * @example 10.5
   */
  altitude: number | null;
  /**
   * Vertical uncertainty in metres, with 68% confidence (or null if not available).
   *
   * @since 7.0.0
   * @example 3.0
   */
  altitudeAccuracy: number | null;
  /**
   * `true` if the location was simulated by software, rather than GPS.
   * Useful for detecting mock locations in development or testing.
   *
   * @since 7.0.0
   * @example false
   */
  simulated: boolean;
  /**
   * Deviation from true north in degrees (or null if not available).
   * Range: 0.0 to 360.0
   *
   * @since 7.0.0
   * @example 45.5
   */
  bearing: number | null;
  /**
   * Speed in metres per second (or null if not available).
   *
   * @since 7.0.0
   * @example 2.5
   */
  speed: number | null;
  /**
   * Time the location was produced, in milliseconds since the unix epoch.
   * Use this to check if a location is stale when using stale: true.
   *
   * @since 7.0.0
   * @example 1640995200000
   */
  time: number | null;
}

CallbackError

위치 시작 콜백으로 전달될 수 있는 오류 객체입니다. 표준 오류를 확장하고 옵션 오류 코드를 포함합니다.

export interface CallbackError extends Error {
  /**
   * Optional error code for more specific error handling.
   *
   * @since 7.0.0
   * @example "PERMISSION_DENIED"
   */
  code?: string;
}

SetPlannedRouteOptions

export interface SetPlannedRouteOptions {
  /**
   * The name of the sound file to play.
   * Must be a valid sound relative path in the app's public folder to work for both web and native platforms.
   * There's no need to include the public folder in the path.
   * @since 7.0.10
   * @example "notification.mp3"
   * */
  soundFile: string;
  /**
   * The planned route as an array of longitude and latitude pairs.
   * Each pair represents a point on the route.
   * This is used to define a route that the user can follow.
   * The route is used to play a sound when the user deviates from it.
   * @since 7.0.11
   * @example [[-74.0060, 40.7128], [-118.2437, 34.0522]]
   */
  route: [number, number][];

  /**
   * The distance in meters that the user must deviate from the planned route to trigger the sound.
   * This is used to determine how far off the route the user can be before the sound is played.
   * If not specified, a default value of 50 meters is used.
   * @since 7.0.11
   * @default 50
   * @example 50
   */
  distance: number;
}

실제 데이터

이 페이지는 플러그인의 src/definitions.ts공개 API이 업스트림에서 변경될 때 다시 싱크를 실행하세요.

Getting Started에서 계속 진행하세요

만약에 시작하기 native 플러그인 작업을 계획하고 싶다면 @capgo/배경 위치 정보 native 기능을 사용하기 위해 @capgo/background-geolocation Capgo 플러그인 디렉토리 Capgo Plugin Directory Capacitor Plugins by Capgo Capacitor Plugins by Capgo 플러그인 추가 또는 업데이트 Adding or Updating Plugins Ionic Enterprise 플러그인 대체품 Ionic Enterprise 플러그인 대체품의 제품 워크플로우