React Native Android Background Geolocation

A react-native geolocation module for Android, which uses Fused Location Provider API to get location, and use the Service so that can run in the foreground and background even the app is terminated.

Example

See react-native-android-background-geolocation-demo

Installation

1. Install with npm

npm i --save react-native-android-background-geolocation

2. Link the native module

Automatic (Recommend)

Use react-native link to automatic install android module.

react-native link react-native-android-background-geolocation

Manually

• in android/app/build.gradle:

dependencies {
    + compile project(':react-native-android-background-geolocation')
    ...
}

• in android/settings.gradle:

...
include ':app'
+ include ':react-native-android-background-geolocation'
+ project(':react-native-android-background-geolocation').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-android-background-geolocation/android')

• in MainApplication.java:

+ import com.gavin.RNAndroidGeolocationService.RNAndroidGeolocationServicePackage;
...
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
            new MainReactPackage(),
            ...
            + new RNAndroidGeolocationServicePackage()
        );
    }

3. Add the service

Add <service/> to your AndroidManifest.xml.

<application>
    ...
    <service android:name="com.gavin.RNAndroidGeolocationService.LocationService" />
    ...
</application>

Usage

Run in foreground and background

You need to call LocationService.start() and then register a listener by LocationService.onLocationChanged.

export default class App extends Component<{}> {

    async componentDidMount() {
        // 1. Request permissions
        await this._requestLocationPermission();

        // 2. Register a event listener by OnError and onLocationChanged
        LocationService.onError(({code, message}) => {
            console.log('error code', code);
            console.log('error message', message);
        });

        LocationService.onLocationChanged(({coords}) => console.log('coords', coords));
    }

    componentWillUnmount() {
        // 3. Remove All listeners
        LocationService.removeAllListeners();
    }
    
    _startGeolocationService() {
        LocationService.start({
            priority: PriorityModeEnum.PRIORITY_HIGH_ACCURACY,
            stopOnTerminate: false,
            interval: 25 * 1000,
            fastestInterval: 20 * 1000,
            distanceFilter: 0,
        });
    }

    _stopGeolocationService() {
        LocationService.stop();
    }

    render() {
        return (
            <View style={styles.container}>
                <Text style={styles.welcome}>Welcome to React Native!</Text>
                <TouchableOpacity
                    style={styles.button}
                    onPress={() => this._startGeolocationService()}
                >
                    <Text style={styles.buttonText} >Start Location Service</Text>
                </TouchableOpacity>
                <TouchableOpacity
                    style={styles.button}
                    onPress={() => this._stopGeolocationService()}
                >
                    <Text style={styles.buttonText} >Stop Location Service</Text>
                </TouchableOpacity>
            </View>
        );
    }
}

Continuously run when the app is terminated

The react-native-android-background-geolocation will invoke your App in the background when the app is terminated. But that will not execute any react components, which means that only execute your entry file, usually is index.js.

index.js

// @flow
import {AppRegistry} from 'react-native';
import App from './App';
import {name as appName} from './app.json';
import LocationService from 'react-native-android-background-geolocation';

LocationService.onLocationChanged(({coords}) => {
    //do something, like update data
    console.log(coords)
});

AppRegistry.registerComponent(appName, () => App);

Methods

• start
• stop
• onLocationChanged
• onError

start(option?)

LocationService.start(option?);

Start tracking device location with specific options.

Parameters

NAME	TYPE	REQUIRED	DESCRIPTION
option	Option	No	Options for the Fused Location Provider API.

---

stop()

LocationService.stop();

Stop tracking device location.

---

onLocationChanged(listener)

let unsubscribe = LocationService.onLocationChanged(LocationInfo => console.log('LocationInfo', LocationInfo));

Register a location change listener, and return the unsubscribe function.

see the LocationInfo type

---

onError(listener)

let unsubscribe = LocationService.onError(ErrorInfo => console.log('ErrorInfo', ErrorInfo));

Register an error listener, and return the unsubscribe function.

see the ErrorInfo type

---

Types

• Option
• LocationInfo
• ErrorInfo

Option

import LocationService, { PriorityModeEnum } from 'react-native-android-background-geolocation';
...
LocationService.start({
    priority: PriorityModeEnum.PRIORITY_HIGH_ACCURACY,
    stopOnTerminate: false,
    interval: 25 * 1000,
    fastestInterval: 20 * 1000,
    distanceFilter: 0,
});
...

Options for the location service.

Parameters

NAME	TYPE	REQUIRED	DESCRIPTION	DEFAULT
priority	PriorityModeEnum	YES	Set the priority of the request.	PRIORITY_BALANCED_POWER_ACCURACY
stopOnTerminate	boolean	NO	Whether this service is stopped or not when the app is closed.	true
interval	number	YES	The interval that can receive location information, in milliseconds.	25000 ms
fastestInterval	number	YES	The fastest interval that can receive location information, in milliseconds.	20000 ms
distanceFilter	number	YES	Set the minimum displacement between location updates in meters.	100 m

---

LocationInfo

Structure

{
    coords: {
        latitude: number,
        longitude: number,
    }
}

The location information is the argument passed to the event listener.

---

ErrorInfo

Structure

{
    code: number,
    message: string,
}

The error code and an error message are the arguments passed to the event listener.

See more details of description at errors section.

---

Enums

• PriorityModeEnum
• ErrorCodeEnum

PriorityModeEnum

import { PriorityModeEnum } from 'react-native-android-background-geolocation';

This enum offers the priority of the start option.

VALUE	DESCRIPTION
PRIORITY_BALANCED_POWER_ACCURACY	This will mixed-use GPS or wifi and cell towers to get the location.
PRIORITY_HIGH_ACCURACY	This will use GPS to get the finest location available but use more power.
PRIORITY_LOW_POWER	This will use wifi or cell towers to get the location.
PRIORITY_NO_POWER	Your app does not trigger any location updates, but receives locations triggered by other apps.

---

ErrorCodeEnum

import { ErrorCodeEnum } from 'react-native-android-background-geolocation';

This enum offers error codes that can be used at if or switch-case to distinguish the error.

VALUE
PERMISSIONS_DENIED
PRIORITY_NOT_SUPPORTED
GOOGLE_PLAY_SERVICE_UPDATING
GOOGLE_PLAY_SERVICE_NEED_UPDATE
GOOGLE_PLAY_SERVICE_ERROR

---

Errors

CODE	ENUM VALUE	DESCRIPTION
40001	PERMISSIONS_DENIED	No permissions to access a location service.
40002	PRIORITY_NOT_SUPPORTED	Use the unsupported priority.
40003	GOOGLE_PLAY_SERVICE_UPDATING	Google Play Services is updating.
40004	GOOGLE_PLAY_SERVICE_NEED_UPDATE	Google Play Services version is too old, needs to update.
40005	GOOGLE_PLAY_SERVICE_ERROR	Google Play Services is unavailable, please check is installed or not.

License

MIT