react-native-proximity-sdk v0.1.1-beta.0

react-native-proximity-sdk

Proximity Delivery solutions tracking sdk for react-native

Installation

npm install react-native-proximity-sdk
npm install react-native-background-fetch

Android

Navigate to /android/build.gradle and add the below URLs inside allProjects -> repositories block:

  maven {
      url("${project(':react-native-proximity-sdk').projectDir}/libs")
    }
  maven {
      url("${project(':react-native-background-fetch').projectDir}/libs")
    }

Add the Proximity SDK license key:

Add the below entry in your android/app/src/main/res/values/strings.xml file (Create the file if it does not exists):

<resources>
    <-- <other string entries go here> -->
  <string name="proximity_sdk_license_key">YOUR_LICENSE_KEY</string>
</resources>

iOS

Navigate to /iOS from terminal and run the below command:

pod install

Make sure you have added capabilities for Audio, Location updates, Background Fetch and Background Processing.

Add the below entries in your Info.plist file:

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>[CHANGME] Location Always and When  in Use</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
  <dict>
    <key>DemoPurpose</key>
    <string>CHANGEME:  Allow the sample app to track location with high accuracy</string>
  </dict>
<key>NSLocationWhenInUseUsageDescription</key>
  <string>[CHANGME] Location when in use</string>
<key>NSMotionUsageDescription</key>
  <string>[CHANGME] Motion description</string>

Usage

Import Proximity plugin as below:

import Proximity from 'react-native-proximity-sdk';
// ...

Start tracking

To start tracking, just call the below method from the plugin:

let launchObject = {
  orgToken: '<YOUR-ORG-TOKEN>', //associated with a unique organization
  username: '<USER-ID>', //Identifier for the user
  orderId: '1234', //Optional, order associated with the tracking, if any
  storeSdkId: '', //Optional, The destination will be taken from this if passed
  storeRef: '', //Optional, The destination will be taken from this if passed
  env: 'sandbox', //prod by default, if not passed
  destination: {
    //Optional, If destination is passed, the tracking stops when user reaches these coordinates
    Latitude: 30.2720039,
    Longitude: 78.0892899,
  },
  userInfo: {}, //Pass vehicle info, userInfo here.
};

Proximity.startTracking(
  launchObject,
  (isTracking) => {
    console.log('Success : ' + isTracking); //if isTracking is true, the tracking has started else the tracking has stopped
  },
  (error) => {
    console.log('Error : ' + error);
  }
);

Order in which the SDK looks for destinations if all the values are passed:

1. If destination object is passed, this will be taken
2. If destination is not passed, SDK lookes for storeSdkId, this will be taken.
3. If destination and storeSdkId are not passed, storeRef will be considered.
4. If none is passed, the tracking will start, but will not stop, untill stopped manually using stopTracking function

Stop tracking

By default the plugin stops tracking automatically when the user reaches the destination. However, there might be cases when the user would want to stop the tracking manually. Call the below function to stop tracking:

Proximity.stopTracking(
  (isTracking) => {
    console.log('Success : ' + isTracking); // false means tracking has stopped
  },
  (err) => {
    console.log('Error : ' + err);
  }
);

On the other hand, if the tracking is in progress, the call to startTracking function also stops tracking. It works like a tracking toggle function.

Get tracking state

In some cases you would want to check the state of tracking ie wether the tracking is already going on or not. You can call the below method to get the tracking state:

Proximity.getTrackingState((isTracking) => {
  console.log('tracking state: ' + isTracking); //true indicates the tracking is in progress
});

Generate debug APK

react-native bundle --platform android --dev false --entry-file index.tsx --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res

cd android/
./gradlew assembleDebug

Flow of the SDK:

The entry point of the SDK is index.js file located inside src directory. There is also a wrapper of this file under src/declaration/ directory: DeliverySolution.d.ts. The wrapper just contains the exposed method signatures from the src/index.js directory.

The start tracking method works as below:

startTracking -> checks the tracking state -> If tracking is true, stops the tracking by call to stopTracking method. -> If tracking is false, follows the below: -> authorizes the user (returns error if fails) -> ready the SDK using tha passed parameters (returns error if fails) -> addDestination: -> checks if destination is passed -> If passed, uses this destination -> If not passed, checks for storeRefId and storeSDKId -> If found, makes API call gets the destination -> If not found, returns true, meaning start indefinite tracking untill stopTracking is called -> When destination is found, add geofence using this destination -> When geofence is added, register for onGeofenece event -> When enter event is received, stop tracking

Building the plugin:

WHen any change is done inside src/ directory, the changes will not reflect automatically. The plugin needs to be built before using locally or publishing to npmjs.

Run the below command to build the plugin:

npm run prepare

Run the below command to publish the plugin to npms(Assuming you are already logged into npmjs from terminal):

npm publish

Don't forget to bump the plugin version in package.js file before publishing to npmjs.

Note: Don't get confused about running commands in plugin and sample app. To run any plugin related command, use the root directory in terminal. To run any sample app related command, use the example directory. To run any iOS related command like pod install or generating IPA use the example/ios directory. To run any Android related command like generating APK, use the example/android directory.

Sample app

The sample app is located under example directory. This implements the above SDK locally. This might have issues building due to the react-native-vector-icons library being used in it. The issue is not related to the SDK. React-Native has a very unstable build system unlike flutter, capacitor/cordova etc and there might be errors building for iOS or Android. Use the below guide.

To install the plugin from local, use the below command:

npm install ../

Note that we are using ../ since the plugin is located just a step above the example directory. In other words, the example directory is inside the plugin directory. If you want to install the plugin locally to some other app in some other directory, you need to provide the absolute path of the plugin in place of '../'.

To uninstall the plugin, use the below command:

npm uninstall react-native-proximity-sdk

Assuming you have already setup Android and iOS build tools in your system, you can use the below commands to run the app from terminal. React-Native uses the metro server for real time updates accross the app from your system. It is hosted on local host. Make sure you are not using port 8081 since this will be used. By running the below command the server will automatically start.

For Android:

react-native run-android

For iOS:

react-native run-android

But this will only work if you already have all the required dependencies installed on the system. Which is not the case for beginners. Since react native generates android and iOS modules, you can open them in respective IDEs to fix your build issues just like the native apps.

Follow the below steps:

1. If your Metro server is not running, you can start it using the below command from the example directory:

npm start

2. For Android, open the example/android directory in Android Studio. Let it build. If you face issues related to libraries not being found or update gradle version, do the suggesstions mentioned by android studio. You might have to replace the urls for artifacts due to recent shutdown of jcenter. To do so, navigate to your root build.gradle file and replace jcenter() with mavenCentral().

3. For iOS, open the example/ios/.xcworkspace file in xcode. You might be able to build it. If you get an error on the device "FontAwesome not found", you need to link the vector icons library. Navigate to the example directory and run the below command:

react-native link react-native-vector-icons

You might face a build issue after this related to "Multiple commands produce". This is again because the icons are added twice by xcode. Use the fix from this link: https://github.com/oblador/react-native-vector-icons/issues/1074#issuecomment-533960934

All the best.