Setup

Installation

CordovaIonic

cordova plugin add cordova-background-geolocation-lt

ionic cordova plugin add cordova-background-geolocation-lt

Configure your license

Purchase a license

The SDK requires a license for release builds. Debug builds work without one — you will see a Toast message "License Validation Failure" which can be ignored. Purchase at docs.transistorsoft.com.

Android Setup

config.xml — Android namespace

Add the xmlns:android namespace attribute to the root <widget> element:

<widget
  id="com.foo.bar"
  version="1.0.0"
  xmlns="http://www.w3.org/ns/widgets"
+ xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:cdv="http://cordova.apache.org/ns/1.0">

config.xml — License key

Within the <platform name="android"> container, add the license key using a <config-file> element:

<platform name="android">
    <config-file parent="/manifest/application" target="app/src/main/AndroidManifest.xml">
        <meta-data
            android:name="com.transistorsoft.locationmanager.license"
            android:value="YOUR_LICENSE_KEY_JWT" />
    </config-file>
</platform>

Gradle variables (optional)

The plugin reads optional variables to pin Android dependency versions. There are two ways to provide them — gradle ext vars take precedence if both are set.

Cordova --variableGradle ext

cordova plugin add cordova-background-geolocation-lt \
    --variable GOOGLE_API_VERSION=21.3.0 \
    --variable TSLOCATIONMANAGER_VERSION=4.1.+

Warning

After changing --variable values, remove and re-add the platform:

cordova platform remove android
cordova platform add android

Set ext vars in your root platforms/android/build.gradle:

ext {
    playServicesLocationVersion = "21.3.0"
    tslocationmanagerVersion    = "4.1.+"
}

Variable	Gradle ext	Default	Description
GOOGLE_API_VERSION	playServicesLocationVersion	21.3.0	com.google.android.gms:play-services-location version. Versions ≥ 21 use tslocationmanager; versions < 21 use tslocationmanager-gms20. Browse: maven.google.com
TSLOCATIONMANAGER_VERSION	tslocationmanagerVersion	4.1.+	Transistor Android SDK version. Pin to a specific version to roll back if needed. Browse: central.sonatype.com

iOS Setup

config.xml — License key

<platform name="ios">
    <config-file parent="TSLocationManagerLicense" target="*-Info.plist">
        <string>YOUR_LICENSE_KEY_JWT</string>
    </config-file>
</platform>

config.xml — Location usage descriptions

iOS renders these strings on the authorization dialogs shown to the user. Write descriptions relevant to your app — they can affect App Store review.

<platform name="ios">
    <config-file parent="NSLocationAlwaysAndWhenInUseUsageDescription" target="*-Info.plist">
        <string>[CHANGEME] Background location tracking is required so we can...</string>
    </config-file>
    <config-file parent="NSLocationWhenInUseUsageDescription" target="*-Info.plist">
        <string>[CHANGEME] Location access is required while the app is in use.</string>
    </config-file>
    <config-file parent="NSMotionUsageDescription" target="*-Info.plist">
        <string>[CHANGEME] Motion detection helps save power by turning off location when stationary.</string>
    </config-file>
</platform>

Significant Changes Only (optional)

If Apple denied your use of the background location capability, you can disable it and rely on useSignificantChangesOnly: true:

cordova plugin add cordova-background-geolocation-lt \
    --variable BACKGROUND_MODE_LOCATION=""

Example

Ionic / AngularTypeScript

import { Injectable, OnDestroy } from '@angular/core';
import BackgroundGeolocation, {
  Subscription,
} from 'cordova-background-geolocation-lt';

@Injectable({ providedIn: 'root' })
export class BackgroundGeolocationService implements OnDestroy {
  private subscriptions: Subscription[] = [];

  init() {
    // Register event listeners *before* calling ready()
    this.subscriptions.push(
      BackgroundGeolocation.onLocation(location => {
        console.log('[onLocation]', location);
      })
    );

    // ready() configures the SDK and restores persisted state.
    // It does NOT start tracking — call start()/stop() separately.
    BackgroundGeolocation.ready({
        geolocation: {
          desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
          distanceFilter: 10,
        },
        app: {
          stopOnTerminate: false,
          startOnBoot: true,
        },
        logger: {
          debug: true,
          logLevel: BackgroundGeolocation.LogLevel.Verbose,
        },
    });
  }

  // e.g. wired to a toggle button in your template
  async onToggleTracking() {
    const state = await BackgroundGeolocation.getState();
    if (state.enabled) {
      await BackgroundGeolocation.stop();
    } else {
      await BackgroundGeolocation.start();
    }
    console.log('[state]', state.enabled, state.trackingMode);
  }

  ngOnDestroy() {
    this.subscriptions.forEach(s => s.remove());
  }
}

import BackgroundGeolocation, {
  Subscription,
} from 'cordova-background-geolocation-lt';

const subscriptions: Subscription[] = [];

document.addEventListener('deviceready', () => {
  // Register event listeners *before* calling ready()
  subscriptions.push(
    BackgroundGeolocation.onLocation(location => {
      console.log('[onLocation]', location);
    })
  );

  // ready() configures the SDK and restores persisted state.
  // It does NOT start tracking — call start()/stop() separately.
  BackgroundGeolocation.ready({
      geolocation: {
        desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
        distanceFilter: 10,
      },
      app: {
        stopOnTerminate: false,
        startOnBoot: true,
      },
      logger: {
        debug: true,
        logLevel: BackgroundGeolocation.LogLevel.Verbose,
      },
  });
});

// e.g. wired to a toggle button in your UI
async function onToggleTracking() {
  const state = await BackgroundGeolocation.getState();
  if (state.enabled) {
    await BackgroundGeolocation.stop();
  } else {
    await BackgroundGeolocation.start();
  }
  console.log('[state]', state.enabled, state.trackingMode);
}