npm package: @shehang/react-native-simple-native-geofencing
Description: **Attention: This repo is not yet fully tested !**
Author: Michael Raring
Latest version: 1.0.3

# react-native-simple-native-geofencing

A native geofencing implementation for Android and iOS that allows to natively post notification when entering/exiting specified geofences and to fire a react-native/javascript asynchronous function when leaving a specific monitoring geofence (see at the bottom of this README). This can be useful to trigger calculations of new Geofences when leaving one area.

# Restrictions

**iOS**

Needs iOS 10 or higher

**Android**

Needs a minSdkVersion of 19.

### Getting started
`$ npm install @shehang/react-native-simple-native-geofencing --save`

### Mostly automatic installation
`$ react-native link @shehang/react-native-simple-native-geofencing`

**iOS only:**

**Attention**

For the module to work at least one `.Swift` file and a `Bridging-Header.h` must be added in the xcode project. Simply create an empty Swift File and Xcode will ask you if you wish to add a `Bridging-Header.h` to your project. Both Files can be empty.

For background updates you have to activate this in your Xcode Project under: `Project` ➜ `Capabilities` ➜ `Background Modes` with at least `Location updates` !

### Manual installation

**Not recommended**

**iOS**

1. In XCode, in the project navigator, right click `Libraries` ➜ `Add Files to [your project's name]`
2. Go to `node_modules` ➜ `@shehang/react-native-simple-native-geofencing` and add `RNSimpleNativeGeofencing.xcodeproj`
3. In XCode, in the project navigator, select your project. Add `libRNSimpleNativeGeofencing.a` to your project's `Build Phases` ➜ `Link Binary With Libraries`
4. Run your project (`Cmd+R`)<

**Android**

1. Open up `android/app/src/main/java/[...]/MainActivity.java`
  * Add `import com.simplegeofencing.reactnative.RNSimpleNativeGeofencingPackage;` to the imports at the top of the file
  * Add `new RNSimpleNativeGeofencingPackage()` to the list returned by the `getPackages()` method
2. Append the following lines to `android/settings.gradle`:

```
  include ':react-native-simple-native-geofencing'
  project(':react-native-simple-native-geofencing').projectDir = new File(rootProject.projectDir,'../node_modules/@shehang/react-native-simple-native-geofencing/android')
```

3. Insert the following lines inside the dependencies block in android/app/build.gradle:
  `compile project(':react-native-simple-native-geofencing')`

**Permissions**

**iOS**

The framework itself asks for permissions for the notifications and the location. However, best practice would be to ask for permission from the user in React Native part.

The following changes must be in the `Info.plist` :

```
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>bla bla</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>bla bla 2</string>
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>
...
```

**Android**

Edit `AndroidManifest.xml` and add the following permission and ServiceIntent:

```
<manifest ...>
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <application
        ...
        android:allowBackup="true">
        <receiver android:name="com.simplegeofencing.reactnative.GeofenceTransitionsBroadcastReceiver" />
        <service android:name="com.simplegeofencing.reactnative.ShowTimeoutNotification" />
    <application/>
</manifest>
```

If you want to use a ***Monitoring Geofence***, that fires a react-native async function when leaving this geofence, you need to add the following as well:

```
<manifest ...>
    ...
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <application ...>
        ...
        <service android:name="com.simplegeofencing.reactnative.MonitorUpdateService"/>
    <application/>
</manifest>
```

The App also needs to ask for permission in react-native since ***Android 6.0 (API level 23)***. You can fire a function like this in the App's componentWillMount hook:

```
import {PermissionsAndroid} from 'react-native';
async function requestLocationPermission() {
  try {
    const granted = await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
        {
          'title': 'Location permission',
          'message': 'Needed obviously'
        }
    )
    if (granted === PermissionsAndroid.RESULTS.GRANTED) {
      console.log("Granted Permission")
    } else {
      console.log("Denied Permission")
    }
  } catch (err) {
    console.warn(err)
  }
}
```

### Usage

```
import RNSimpleNativeGeofencing from '@shehang/react-native-simple-native-geofencing';

export default class App extends Component {
    componentWillMount() {
        //see above
        if(Platform.OS === 'android'){
            requestLocationPermission();       
        }
    }
    componentDidMount(){
        //set up Notifications
         RNSimpleNativeGeofencing.initNotification(
            {
              channel: {
                title: "Message Channel Title",
                description: "Message Channel Description"
              },
              start: {
                notify: true,
                title: "Start Tracking",
                description: "You are now tracked"
              },
              stop: {
                notify: true,
                title: "Stopped Tracking",
                description: "You are not tracked any longer"
              },
              enter: {
                notify: true,
                title: "Attention",
                //[value] will be replaced ob geofences' value attribute
                description: "You entered a [value] Zone"
              },
              exit: {
                notify: true,
                title: "Left Zone",
                description: "You left a [value] Zone"
              }
            }
         );
    }
    fail(){
        console.log("Fail to start geofencing")
    }
    startMonitoring(){
        let geofences = [
          {
            key: "geoNum1",
            latitude: 38.9204,
            longitude: -77.0175,
            radius: 200,
            value: "yellow"
            url: "https://www.image.com" // replace this with the url of the image you want to display
          },
          {
            key: "geoNum2",
            latitude: 38.9248,
            longitude: -77.0258,
            radius: 100,
            value: "green"
          },
          {
            key: "geoNum3",
            latitude: 47.423,
            longitude: -122.084,
            radius: 150,
            value: "red"
          }
        ];
        RNSimpleNativeGeofencing.addGeofences(geofences, 3000000, this.fail);
    }
    
    stopMonitoring(){
        RNSimpleNativeGeofencing.removeAllGeofences();
    }
}
```


### Methods
method | arguments | notes
------ | --------- | -----
`initNotification` | `settings`: SettingObject | Initializes the notification strings and when they should appear **(required)**
`addGeofence` | `geofence`: GeofenceObject, `duration`: number | Adds one geofence to the native geofence list (optional)
`addGeofences` | `geofencesArray`: Array, `duration`: number, `failCallback`: function | Adds a list of geofences, a Geofence for monitoring and starts monitoring **(required)**
`removeAllGeofences` |  | Removes all geofences and stops monitoring (optional)
`updateGeofences` | `geofencesArray`: Array, `duration`: number | Deletes Geofences and adds the new ones without notifications (optional)
`removeGeofence` | `geofenceKey`: String | Removes a specific geofence (optional)
`startMonitoring` | `failCallback`: function | Start monitoring (optional)
`stopMonitoring` | | Stop monitoring (optional)

The function `monitoringCallback()` gets fired with the parameter of the remaining duration. `duration` is in millisec.

### Types

```
type GeofenceObject {
  key: string,
  latitude: Number,
  longitude: Number,
  radius: Number,
  value: String
  url: string
}
```

MonitoringGeofenceObject is item of `geofencesArray` with `key: "monitor"`:


```
type MonitoringGeofenceObject {
  key: "monitor",
  latitude: Number,
  longitude: Number,
  radius: Number
  url: string // The attachment url you want to show in the notification.Please this wont work for local device storage paths
}
type SettingObject {
  start: {
    notify: boolean,    // If Notification should be fired on start tracking
    title: string,      // Title of Notification
    description: string // Content of Notification
  },
  stop: {
    notify: boolean,
    title: string,
    description: string
  },
  timeout: {            // automatic stop by end of duration 
    notify: boolean,
    title: string,
    description: string
  },
  enter: {
    notify: boolean,
    title: string,
    description: string
  },
  exit: {
    notify: boolean,
    title: string,
    description: string
  },
  channel: {            // Only Android specific
    title: string,
    description: string
  }
}

```

The string `[value]` is automatically replaced by the GeofenceObject's value string in enter & exit's notification's title & description/content

### Monitoring Geofences

With this module you can also define a Monitoring Geofence that allows you to fire a react-native / javascript function when leaving. Therefore include this geofence in your List with the key `"monitor"` (see `MonitoringGeofenceObject` above) . The implementation of the function depends on Android or iOS.

**iOS**

If the app is in the background and a geofence trigger, the app's React Part will also start in the background. With a `NativeEventEmitter` a corresponding event can be intercepted.

```
import {... , NativeEventEmitter} from 'react-native';
...
componentWillMount(){ 
    const myModuleEvt = new NativeEventEmitter(RNSimpleNativeGeofencing);
        let subscription = myModuleEvt.addListener(
        'leftMonitoringBorderWithDuration',
        (result) => {
        
            //result is a Object with the remaining 
            //duration of the activ geofences & a boolean
            //for leaving or entering the monitoring boarder
        
            console.log("Event :");
            console.log(JSON.stringify(result, null, 2));
        }
    );
}
```

**Android**

In Android this implementation uses Headless JS, which allows you to run javascript code in the background (see [Headless JS Docs](https://reactnative.dev/docs/headless-js-android)).

Therefore, you have to define a task as an asynchronous function with the name `leftMonitoringBorderWithDuration`

```
import React from 'react';
import RNSimpleNativeGeofencing from "react-native-simple-native-geofencing";
module.exports = async (taskData) => {
    //taskData.remainingTime tells you the remaining time of the geofencing
    // so you can reuse it to update yours
    console.log(taskData);
    // do stuff
    RNSimpleNativeGeofencing.updateGeofences(
        newGeofencesArray,
        taskData.remainingTime
    );
};
```

This tasks needs to be registered in your `index.js` of your App:

```
import {AppRegistry} from 'react-native';
import App from './App';
import {name as appName} from './app.json';

// Your App
AppRegistry.registerComponent(appName, () => App);
// Your defined task (see above)
AppRegistry.registerHeadlessTask('leftMonitoringBorderWithDuration', () => require('./leftMonitoringBorderWithDuration'));
```