react-native-activity-recognition-wrapper

A wrapper for the Activity Recognition (Android) and CMMotionActivity (iOS) libraries.

***NOTE: This library is currently still in experimental phase and is constantly being worked on. For suggestions/questions, please email me on [email protected] and I will get back to you ASAP.

Installation

npm install react-native-activity-recognition-wrapper
or 
yarn add react-native-activity-recognition-wrapper

How it currently works and pre-requisites for your app

The updates of the user's motion are triggered by location changes, as this was a technical limitation imposed by iOS and in order to maintain consistency across the platforms, we have implemented the same in Android.

The package requests location updates from the operating system, at a distance interval(android) or distance filter(ios) that you specify (see below in usage). Whenever the package receives a location update, it then listens to the motion activity of the device for a specified amount of time (also see below in usage) and these updates are broadcasted to any listeners that are listening on the 'ACTIVITY_UPDATE' topic.

The prerequisites are the following:

Android:

These permissions need to be requested before the package is invoked, if they are not granted, do not call the package.

1. ACTIVITY_RECOGNITION
2. ACCESS_FINE_LOCATION
3. ACCESS_COARSE_LOCATION These need to be added to your android manifest file, along with the following other items:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.reactnativeactivityrecognitionwrapper">
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.INTERNET" />
    <application android:name=".MainApplication" android:label="@string/app_name" android:icon="@mipmap/ic_launcher" android:roundIcon="@mipmap/ic_launcher_round" android:allowBackup="false" android:theme="@style/AppTheme">
        <!-- ... activity ... -->
        <service android:name=".service.ActivityDetectionIntentService" android:exported="false"></service>
        <service android:name=".service.BackgroundDetectedActivitiesService"></service>
    </application>
</manifest>

iOS:

You need to enable the Location Updates Background mode in your application (found under the main target of your application - Signing and Capabilities - Background Modes), then you need to add the following permission items to your info.plist file:

<dict>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Display Message for Location When In Use Usage Description</string>
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>Display Message Location Always and When In Use Usage Description</string>
</dict>

Usage

import { 
  enableActivityRecognitionTracking,
  stop,
  startSignificantLocationUpdates,
  startFrequentLocationUpdates
}  from 'react-native-activity-recognition-wrapper';

Initialising configuration for the package

We now need to initialise the parameters with which we want the service to run, namely the distance filter for location updates, and the time interval that we want to receive motion updates for.The function enableActivityRecognitionTracking must be called with 2 parameters, the first being the location update interval (distance filter - which will tell the OS after what displacement the app must be sent location updates (IN METERS)) and the second being the activity update interval (update duration - how long the activity updates must be sent to your app for, after the location displacement has been exceeded and the location updates have now been triggered (IN MILLISECONDS)) NOTE: this does not actually start the updates, it purely sets configuration parameters. Here's an example:

enableActivityRecognitionTracking(10, 10000)    

The example will tell the OS to let our app know once the user has moved by 10 meters, and thereafter start sending activity updates for 10 seconds. After the 10 seconds have passed, the activity updates will stop. When the distance filter (10 meters) is exceeded again, then the activity updates will start again etc.

The package then broadcasts the events via the native event emitter module to your app.

Start listening to location and activity updates

Now that we have configured the package, we have to tell the package to START listening to the location updates, and when a location update comes through, it will automatically start monitoring the user activity for the specified time interval. This is done with the following 2 methods:

startSignificantLocationUpdates()

Which is a low power location updating method, it listens for location updates in the background on both android and iOS (ie it will launch the app and deliver the location updates even if the app was force-killed by the user). The distance filter here is ignored, and location updates are only delivered in +- 500m intervals.

OR we can use the following:

startFrequentLocationUpdates()

Which now tells the OS to deliver location updates to the application more frequently (at your specified distance interval). This consumes more battery of course, and will NOT run in the background on iOS. On android it will run in the background however. I suggest using this for short intervals within your application and only when the app is in the foreground. For background tasks, it is recommended to use the significant updates function for more reliable location updates.

You can call either one of these depending on your use case.

As mentioned, the activity updates are started automatically when a location update comes through, there are no explicit functions (yet) to trigger activity updates manually - the purpose being that this package was developed to allow these updates to occur in the background mostly.

You can listen for the events of location updates and activity updates by subscribing to the following events:

1. LOCATION_UPDATE: if you would like to receive the location objects when they come through from the OS
2. ACTIVITY_UPDATE: to receive the activity updates when they are triggered by the location filter being exceeded.

Here's an example of the code implementation to listen to these events:

const emitter = new NativeEventEmitter(
    NativeModules.ActivityRecognitionWrapper
  );

  emitter.addListener('ACTIVITY_UPDATE', (response: any) => {
   //...your handling code here for when a new activity log is sent through
  });
  emitter.addListener('LOCATION_UPDATE', (response: any) => {
      //...your handling code here for when a new location log is sent through

  });

Stopping the service

You can simply stop the service by calling the stop() method that you have imported and this will kill the location and activity listeners.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library