background-location-update

A Capacitor plugin which lets you receive location updates even while the app is backgrounded.

Install

npm install background-location-update
npx cap sync

Usage

import { BackgroundLocation, Location } from 'background-location-update';

iOS

Add the following keys to Info.plist.:

<dict>
  ...
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>We need to track your location</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>We need to track your location while your device is locked.</string>
  <key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>
  ...
</dict>

Android

Configure AndroidManifest.xml:

<manifest>
    <application>
        <service
            android:name="com.viewtrak.plugins.backgroundlocation.BackgroundLoctionService"
            android:enabled="true"
            android:exported="true"
            android:foregroundServiceType="location" />
    </application>

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-feature android:name="android.hardware.location.gps" />
</manifest>

Configration specific to Android can be made in strings.xml:

<resources>
    <!--
        The channel name for the background notification. This will be visible
        when the user presses & holds the notification. It defaults to
        "Background Tracking".
    -->
    <string name="capacitor_background_location_notification_channel_name">
        Background Tracking
    </string>

    <!--
        The icon to use for the background notification. Note the absence of a
        leading "@". It defaults to "mipmap/ic_launcher", the app's launch icon.

        If a raster image is used to generate the icon (as opposed to a vector
        image), it must have a transparent background. To make sure your image
        is compatible, select "Notification Icons" as the Icon Type when
        creating the image asset in Android Studio.
    -->
    <string name="capacitor_background_location_notification_icon">
        drawable/ic_tracking
    </string>
</resources>

API

• addWatcher(...)
• removeWatcher(...)
• openSettings()
• addListener('onlineNotificationAction', ...)
• Interfaces

addWatcher(...)

addWatcher(options: WatcherOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<string>

| Param | Type | | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | options | WatcherOptions | | callback | (position?: Location, error?: CallbackError) => void |

Returns: Promise<string>

removeWatcher(...)

removeWatcher(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

openSettings()

openSettings() => Promise<void>

addListener('onlineNotificationAction', ...)

addListener(eventName: 'onlineNotificationAction', listenerFunc: (data: { isOnline: boolean; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when onlineNotificationAction set to true in addWatcher() and result received

Provides onlineNotificationAction result.

| Param | Type | | ------------------ | ------------------------------------------------------ | | eventName | 'onlineNotificationAction' | | listenerFunc | (data: { isOnline: boolean; }) => void |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 2.0.2

Interfaces

WatcherOptions

| Prop | Type | | ------------------------------ | -------------------- | | backgroundMessage | string | | backgroundTitle | string | | requestPermissions | boolean | | stale | boolean | | distanceFilter | number | | onlineNotificationAction | boolean | | isOnline | boolean | | actionOnline | string | | actionOffline | string |

Location

| Prop | Type | | ---------------------- | --------------------------- | | latitude | number | | longitude | number | | accuracy | number | | altitude | number | null | | altitudeAccuracy | number | null | | simulated | boolean | | bearing | number | null | | speed | number | null | | time | number | null |

CallbackError

| Prop | Type | | ---------- | ------------------- | | code | string |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |