Capacitor Background Location Plugin

Capacitor plugin for background location tracking

Current version 0.0.1

See our detailed changelog for the latest features, improvements and bug fixes.

Installation

npm

npm install @triplesense/capacitor-background-location
npx cap sync

Usage example

import { BgLocation } from '@triplesense/capacitor-background-location';

@Component({
  selector: 'home-page',
  templateUrl: 'home.page.html',
})
export class HomePage {
  /**
   *
   */
  onStartClick = async (): Promise<void> => {
    return BgLocation.start()
      .then(() => {
        console.log(`👍 [BackgroundGeolocation] started `);
      })
      .catch(error => {
        console.error(`❌ [BackgroundGeolocation] not started `, error);

        if (error?.message === 'PERMISSION_DENIED_ERROR') {
          this.onPermissionDenied();
        }
      });
  };

  /**
   *
   */
  onStopClick = (): Promise<void> => {
    const onComplete = () => {
      console.log(`[BackgroundGeolocation] stopped`);
    };

    const onError = () => {
      console.error(`[BackgroundGeolocation] not stopped`);
    };

    return BgLocation.stop().then(onComplete).catch(onError);
  };

  /**
   *
   */
  enableActivities = (): Promise<void> => {
    return BgLocation.enableActivities()
      .then(() => {
        console.log(`👍 [BackgroundGeolocation] activities enabled `);
      })
      .catch(error => {
        console.error(
          `❌ [BackgroundGeolocation] activities not enabled `,
          error,
        );
      });
  };

  /**
   *
   */
  disableActivities = (): Promise<void> => {
    return BgLocation.disableActivities()
      .then(() => {
        console.log(`👍 [BackgroundGeolocation] activities disabled `);
      })
      .catch(error => {
        console.error(
          `❌ [BackgroundGeolocation] activities not disabled `,
          error,
        );
      });
  };

  /**
   *
   */
  hasBackgroundLocationPermission = () => {
    return this.locationSettings.isBackgroundLocationGranted();
  };

  /**
   *
   */
  isEnabled = async (): Promise<boolean> => {
    return (await BgLocation.isRequestingLocations()).result;
  };
}

Android

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• $playServicesLocationVersion: version of com.google.android.gms:play-services-location (default: 17.1.0)
• $firebaseMessagingVersion: version of com.google.firebase:firebase-messaging (default: 21.0.1)
• $workVersion: version of androidx.work:work-runtime (default: 2.4.0)

Permissions

Add the following permissions to the application's AndroidManifest.xml:

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

  <!-- Required only when requesting background location access on
      Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />


   <!-- Required for Android 9 (API level 28) and below. -->
  <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
  <!-- Required for Android 10+ (API level 29+)-->
  <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>

The permissions above are for access device location and activity recognition.

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

How permissions work

Android 9 and bellow

TODO

Android 10

TODO

Android 11 and above

TODO

Notification Color

You can customize notification's colors by editing res/values.colors.xml on you app project:

<resources>
  <color name="notificationColor">#02de82</color>
</resources>

Notification's localization

You can localize notification's messages by editing res/values.strings.xml on you app project:

<resources>
    <plurals name="num_locations_reported">
        <item quantity="zero">No location reported</item>
        <item quantity="one">One location reported</item>
        <item quantity="other">%d locations reported</item>
    </plurals>
</resources>

iOS

TODO

API

• start()
• stop()
• hasPermissionGranted()
• enableActivities()
• disableActivities()
• isRequestingLocations()
• addListener(string, ...)
• Interfaces
• Type Aliases

start()

start() => Promise<void>

Starts tracking location

platforms: android, ios

Since: 1.0.0

stop()

stop() => Promise<void>

Stops tracking location

platforms: android, ios

Since: 1.0.0

hasPermissionGranted()

hasPermissionGranted() => Promise<{ result: boolean; }>

Check if required location permissions are granted

platforms: android, ios

Returns: Promise<{ result: boolean; }>

Since: 1.0.0

enableActivities()

enableActivities() => Promise<void>

Starts tracking activities

platforms: android, ios

Since: 1.0.0

disableActivities()

disableActivities() => Promise<void>

Stops tracking activities

platforms: android, ios

Since: 1.0.0

isRequestingLocations()

isRequestingLocations() => Promise<{ result: boolean; }>

Check if tracking is enabled (locations are being emitted)

platforms: android, ios

Returns: Promise<{ result: boolean; }>

Since: 1.0.0

addListener(string, ...)

addListener(eventName: string, listenerFunc: ListenerCallback) => Promise<PluginListenerHandle> & PluginListenerHandle

platforms: android, ios

| Param | Type | | ------------------ | ------------------------------------------------------------- | | eventName | string | | listenerFunc | ListenerCallback |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0

Interfaces

PluginListenerHandle

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

Type Aliases

ListenerCallback

(err: any, ...args: any[]): void