Getting Started

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

설치

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

__CAPGO_KEEP_0__을(를) 열어 기기의 위치 설정 페이지를 엽니다. 사용자가 위치 서비스를 활성화하거나 권한을 조정하는 데 도움이 됩니다.

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

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

setPlannedRoute

__CAPGO_KEEP_0__을(를) 재생하면 사용자가 계획된 경로에서 벗어났을 때 사운드 파일을 재생합니다. 이 기능은 네이티브에서만 사용할 수 있으며, 배경에서도 재생할 수 있습니다.

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

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

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__은 네이티브 레이어에서 작동하므로 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" />

__CAPGO_KEEP_0__

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;
}

__CAPGO_KEEP_0__의 원천

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

Getting Started에서 계속

__CAPGO_KEEP_0__을 사용하는 경우 Getting Started을 사용하여 __CAPGO_KEEP_0__을 사용하여 capgo을 사용하여 @capgo/background-geolocation의 네이티브 기능을 연결하세요. capgo/background-geolocation을 사용하는 경우 @capgo의 네이티브 기능을 연결하세요. Capgo 플러그인 디렉토리 Capgo 제품 워크플로우 디렉토리에서 제품 워크플로우를 위한 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 사항을 위한 플러그인 추가 또는 업데이트 __CAPGO_KEEP_0__ 플러그인들에 의해 __CAPGO_KEEP_1__의 구현 세부 사항을 위한 플러그인 추가 또는 업데이트, 그리고 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체의 제품 워크플로우를 위한