Start tracking geofence

This method allows you to start tracking the geofence of your users.

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

Android Geofence details

According to the Google Play Policy for tracking geofence, app owners should have two different permissions.

First, app owners should get users' consent to collect their location. After users give consent or not, app owners need to update the value of the location opt-in on Insider accordingly. It has to be true to make geofence tracing work for a user. You can set up location opt-in accordingly from here.

To set up Insider location opt-in to true, Android's location consent should be allowed first.

To understand how to collect consent and what to do, please refer to Play Console-User Data.

Secondly, after collecting opt-in, we need to trigger the method below to track geofence. 

Method signature

startTrackingGeofence(): void;

Method example

window.Insider.startTrackingGeofence();

setAllowsBackgroundLocationUpdates

Use setAllowsBackgroundLocationUpdates to let your iOS app receive location updates while it runs in the background, so geofence tracking continues when the app is not in the foreground. Natively, the method calls InsiderGeofence.setAllowsBackgroundLocationUpdates(_:).

This method is available on Cordova SDK 4.1.0 or higher (cordova-plugin-insider 4.1.0 and later).

This method works on iOS only. On Android, the call does nothing. Refer to Behavior on Android for details.

Method signature

Insider.setAllowsBackgroundLocationUpdates(allowsBackgroundLocationUpdates: boolean): void;

• The method returns nothing and does not return a Promise.

• If you pass a non-boolean value, the SDK makes no native call and logs a parameter warning to the console.

iOS prerequisites (Apple requirements)

Apple requires the following before background location updates can work:

• In Info.plist, the UIBackgroundModes array must contain location. Without it, you cannot enable background location updates.

• The NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationWhenInUseUsageDescription descriptions must be present, and the user must have granted Always location permission.

• Call the method after Insider.init(...). The SDK ignores a call made before initialization.

In a Cordova project, add these values to your config.xml file.

<platform name="ios">
    <edit-config file="*-Info.plist" target="UIBackgroundModes" mode="merge">
        <array>
            <string>location</string>
        </array>
    </edit-config>
    <edit-config file="*-Info.plist" target="NSLocationAlwaysAndWhenInUseUsageDescription" mode="merge">
        <string>We use your location to notify you about nearby stores.</string>
    </edit-config>
    <edit-config file="*-Info.plist" target="NSLocationWhenInUseUsageDescription" mode="merge">
        <string>We use your location to notify you about nearby stores.</string>
    </edit-config>
</platform>

Method example

document.addEventListener('deviceready', () => {
    Insider.init('your_partner_name', 'group.com.your.app', (callback) => {
        // notification callbacks
    });

    Insider.startTrackingGeofence();
    Insider.setAllowsBackgroundLocationUpdates(true);
}, false);

To turn background location updates off, pass false.

Insider.setAllowsBackgroundLocationUpdates(false);

Behavior on Android

• setAllowsBackgroundLocationUpdates does nothing on Android. You do not need to wrap the call in a platform check.

• In 4.0.1 and earlier, the native Android side never answered the call, so it had no effect either. Version 4.1.0 fixes this by returning early on the JavaScript side.

On Android, background geofence tracking depends on permissions, not on an SDK flag. To enable it, follow these steps:

1. Add the location permissions to your manifest. The plugin adds only ACCESS_FINE_LOCATION, so your app must add ACCESS_COARSE_LOCATION and, for Android 10 and later, ACCESS_BACKGROUND_LOCATION. Geofence tracking does not start if either is missing.

   <platform name="android">
       <config-file target="AndroidManifest.xml" parent="/manifest" xmlns:android="http://schemas.android.com/apk/res/android">
           <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
           <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
       </config-file>
   </platform>

2. Request the location permissions in your app, for example with a permissions plugin. On Android 11 and later, users can grant background permission only by choosing Allow all the time in Settings.

3. Enable the location opt-in and start tracking.

   Insider.getCurrentUser().setLocationOptin(true);
   Insider.startTrackingGeofence();

Cross-platform example

The following example works on both platforms. The last call takes effect on iOS only.

Insider.getCurrentUser().setLocationOptin(true);       // Required on Android
Insider.startTrackingGeofence();                       // Both platforms
Insider.setAllowsBackgroundLocationUpdates(true);      // Takes effect on iOS only