[New Features] Promise API, Two new events, new Initialization method #ready

[christocracy]

This is a rather large refactor of the iOS / Android configuration API, in addition to some other native API, making them less "json-centric" with more traditional Obj-c / Android APIs.

This version will be called 2.12.0, available now in master (not yet tagged).

Android Installation Change

The Android plugin makes a slight change to the installation procedure. Gone is flatDirs, replaced with a local maven url:

📂 android/build.gradle

allprojects {
    repositories {
        mavenLocal()
        jcenter()
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url "$rootDir/../node_modules/react-native/android"
        }
        // Google now hosts their latest API dependencies on their own maven  server.  
        // React Native will eventually add this to their app template.
+       maven {
+           url 'https://maven.google.com'
+       }
+       maven {
+           url "$rootDir/../node_modules/react-native-background-geolocation/android/libs"
+       }
+       maven {
+           url "$rootDir/../node_modules/react-native-background-fetch/android/libs"
+       }
    }
}

Also note the installation procedure now includes directions for setting up react-native-background-fetch, which now supports Android.

See the Installation docs for more information:

• Android react-native link setup

• Android Manual setup

Android Application-wide Configuration Parameters

In order to assist with solving gradle dependency version-conflicts (eg: play-services, firebase), the plugin is now aware of several key gradle configuration parameters and will use them when detected. In your root build.gradle file, if you provide the following parameters, the plugin will align itself to them:

📂 android/build.gradle

In your application's "root" gradle file, define global properties to be used by your app and all the modules you include into it:

buildscript {...}

allprojects {...}

/**
 * Project-wide configuration properties
 */
+ext {
+    compileSdkVersion   = 26
+    targetSdkVersion    = 26
+    buildToolsVersion   = "26.0.2"
+    supportLibVersion   = "26.1.0"
+    googlePlayServicesVersion = "11.8.0"    
+}

See Wiki Solving Android Gradle Conflicts for more information.

New Initialization method: #ready

This PR deprecates the #configure method in favour of a new initialization method named #ready. Since the plugin has always persisted the supplied configuration, it's always bugged me having to re-apply the {config} object every time the app launches. With #ready, the plugin will detect the first launch of your application and only apply the supplied {config} object then — each launch thereafter, the plugin will automatically apply the last known configuration from persistent storage.

Observe the following example. Imagine you've deleted the app from the device and re-installed it:

BackgroundGeolocation.ready({distanceFilter: 10}, (state) => {
  console.log('- Plugin is ready.  distanceFilter: ', state.distanceFilter);  
});

In the console, you'll see

> - Plugin is ready.  distanceFilter: 10

Somewhere else in your code, you change the distanceFilter:

BackgroundGeolocation.setConfig({distanceFilter: 250});

Now terminate the app and reboot. In the console, you'll see:

> - Plugin is ready.  distanceFilter: 250

The #ready method will apply the supplied {config} ONLY at first launch of your application. Thereafter, it will load the last known configuration from persistent storage.

New method: #reset

The plugin now includes a method #reset to reset the plugin to documented defaults. For more information, see the docs for #reset.

// Reset to documented default-values
BackgroundGeolocation.reset();
// Reset to documented default-values with overrides
BackgroundGeolocation.reset({distanceFilter:  10});

reset: true

Optionally, you can specify reset: true to #ready. This will esentially force the supplied {config} to be applied with each launch of your application, making it behave like the traditional #configure method.

BackgroundGeolocation.ready({
  reset: true,  // <-- set true to ALWAYS apply supplied config; not just at first launch.
  distanceFilter: 50
}, (state) => {
  conosle.log('Ready with reset: true: ', state.distanceFilter);
});

Javascript API Now uses Promises

BackgroundGeolocation Javascript API supports Promises for nearly every method (the exceptions are #watchPosition and adding event-listeners via #on method.

// Traditional API still works:
BackgroundGeolocation.getCurrentPosition((location) => {
  console.log('- current position: ', location);
}, (error) => {
  console.log('- location error: ', error);
}, {samples: 1, persist: false});

// Promise API
BackgroundGeolocation.getCurrentPosition({samples:1, persist: false}).then(location => {
  console.log('- current position: ', location);
}).catch(error => {
  console.log('- location error: ', error);
});

Using await

By marking one of your application methods as async you can use the await mechanism instead of callbacks:

async onClickGetPosition() {
  let location = await BackgroundGeolocation.getCurrentPosition({samples:1, persist: false});
  conosle.log('- current position: ', location);

  let count = await BackgroundGeolocation.getCount();
  console.log('- There are ', count, ' records in the database');
}

Two New Events: connectivitychange, enabledchange

connectivitychange

Fired when the state of the device's network-connectivity changes (enabled -> disabled and vice-versa). By default, the plugin will automatically fire a connectivitychange event with the current state network-connectivity whenever the #start method is executed.

BackgroundGeolocation.on('connectivitychange', function(event) {
  console.log("- connectivitychange, network is connected? ", event.connected);
});

enabledchange

Fired when the plugin's enabled state changes. For example, executing #start and #stop will cause the enabledchange event to fire. This event is primarily desigend for use with the configuration option [stopAfterElapsedMinutes], which automatically executes the plugin's #stop method.

BackgroundGeolocation.on('enabledchange', function(event) {
  console.log("- enabledchange, plugin is enabled? ", event.enabled);
});

• [Added] Added new initialization method #ready, desigend to replace #configure (which is now deprectated). The new #ready method operates in the same manner as #configure with a crucial difference -- the plugin will only apply the supplied configuration {} at the first launch of your app — thereafter, it will automatically load the last-known config from persistent storage.
• [Added] Add new method #reset for resetting the plugin configuration to documented defaults.
• [Added] Refactor Javascript API to use Promises. Only #watchPosition and adding event-listeners with #on will not use promises.
• [Fixed] iOS issue not turning of "keepAlive" system when #stop method is executed while stop-detection system is engaged.
• [Added] Android will fire providerchange event after the result of user location-authorization (accept/deny). The result will be available in the status key of the event-object.
• [Changed] Refactor native configuration system for both iOS and Android with more traditional Obj-c / Java API.
• [Changed] Create improved Obj-c / Java APIs for location-requests (#getCurrentPosition, #watchPosition) and geofencing.
• [Added] Added new event connectivitychange for detecting network connectivity state-changes.
• [Added] Added new event enabledchange, fired with the plugin enabled state changes. Executing #start / #stop will cause this event to fire. This is primarily designed for use with stopAfterElapsedMinutes.