Install SDK on React Native

HyperTrack lets you add live location tracking to your mobile app. Live location is made available along with ongoing activity, tracking controls and tracking outage with reasons.

React Native HyperTrack SDK is a wrapper around native iOS and Android SDKs that allows to integrate them into React Native apps.

SDK provides access to functionality that collects location, activity and device health data. The module exposes methods to start and stop tracking, and interact with the HyperTrack APIs.

Functionality is provided through one single npm package so you can use it for both platforms without downloading any extra packages.

Integrate the React Native SDK

First, go to Setup page, where you can copy your publishable key.

In case you are not using React Native, you can refer to the iOS or Android versions. If you want to quickly try the module in a test app, you can use the React Native Quickstart app.

You will need either npm or Yarn in order to install the SDK and configure the Android and iOS projects.

1. Create React Native project
2. Install JavaScript packages
3. Configure projects
4. Enable remote notifications
5. Usage

Step 1: Create React Native project

First create a React Native project:

react-native init YourApp

Step 2: Install JavaScript packages

Run yarn (or npm install, if using npm) inside your new YourApp directory:

cd YourApp
yarn

Then, install the hypertrack-sdk-react-native package:

yarn add hypertrack-sdk-react-native

Or, if using npm:

npm install hypertrack-sdk-react-native --save

note

We constantly work on making our SDKs better, so make sure you have the latest version of it. You might take a look of its changelog here.

Step 3: Configure projects

Android

Assuming you have latest Android Studio installed, open the project with Android Studio.

Go to build.gradle and change minimum sdk version:

minSdkVersion = 23

Add in repositories section:

maven {
    name 'hypertrack'
    url 'https://s3-us-west-2.amazonaws.com/m2.hypertrack.com/'
}

iOS

Add HyperTrack iOS SDK to your Podfile

The native iOS SDK is distributed using CocoaPods dependency manager.

If you don't have CocoaPods, install it first. Using the latest version is advised.

In your project's ios directory, create a Podfile (if you don't have one).

cd ios
pod init

HyperTrack iOS SDK supports iOS 11 and above, that's why platform :ios, '11.0' is included explicitly. And lastly, add the post_install script to keep dependencies with the correct Swift version.

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, '11.0'

target 'Quickstart' do
  config = use_native_modules!

  use_react_native!(:path => config["reactNativePath"])

  # Enables Flipper.
  #
  # Note that if you have use_frameworks! enabled, Flipper will not work and
  # you should disable these next few lines.
  use_flipper!
  post_install do |installer|
    flipper_post_install(installer)
  end
end

Install the native HyperTrack SDK through CocoaPods:

pod install

info

If your using Xcode 12 and newer, open your workspace in Xcode, right-click on Your App Name in the Project Navigator on the left, and click New File. Create a single empty Swift file to the project (make sure that Your App Name target is selected when adding) when Xcode asks, press Create Bridging Header and do not remove Swift file then.

Enable background location updates

Enable Background Modes in your project target's Capabilities tab. Choose "Location updates".

Add purpose strings

Set the following purpose strings in the Info.plist file:

You can ask for "When In Use" permission only, but be advised that the device will see a blue bar at the top while your app is running.

Be advised, purpose strings are mandatory, and the app crashes without them.

Step 4: Set up silent push notifications

The SDK has a bi-directional communication model with the server. This enables the SDK to run on a variable frequency model, which balances the fine trade-off between low latency tracking and battery efficiency, and improves robustness. This also enables HyperTrack Trips to start and stop tracking automatically when trip starts and ends. For this purpose, the iOS SDK uses APNs silent remote notifications and Android SDK uses FCM silent notifications.

• Set up push notifications (Android)
• Set up push notifications (iOS)

Step 5: Usage

// Import HyperTrack SDK API
// You can also use CriticalErrors to react to different kind of errors preventing tracking (ex: permissions deined)
import {CriticalErrors, HyperTrack} from 'hypertrack-sdk-react-native';

const PUBLISHABLE_KEY = "Paste_your_publishable_key_here";

export default class App extends Component {

    state = {
        deviceId: "",
        trackingState: "Stopped",
        isTracking: false
    };

    _initializeHyperTrack = async () => {
        // (Optional) This turns on logging for underlying native SDKs. Placed on top so SDKs start logging immediately
        HyperTrack.enableDebugLogging(true);

        // Initialize HyperTrack with a publishable key
        this.hyperTrack = await HyperTrack.createInstance(PUBLISHABLE_KEY, true);

        // Obtain the unique HyperTrack's DeviceID identifier to use it with HyperTrack's APIs
        const deviceId = await this.hyperTrack.getDeviceID();
        this.setState({deviceId: deviceId});

        // (Optional) Set the device name to display in dashboard (for ex. user name)
        this.hyperTrack.setDeviceName("RN Quickstart");

        // (Optional) Attach any JSON metadata to this device to see in HyperTrack's API responses
        this.hyperTrack.setMetadata({driver_id: "83B3X5", state: "IN_PROGRESS"});

        // (Optional) Register tracking listeners to update your UI when SDK starts/stops or react to errors
        this.hyperTrack.registerTrackingListeners(this,
            // Display or log errors
            (error) => {
                if (error.code === CriticalErrors.INVALID_PUBLISHABLE_KEY
                    || error.code === CriticalErrors.AUTHORIZATION_FAILED) {
                    console.log("Initialization failed")
                } else {
                    console.log("Tracking failed")
                }
                this.setState({
                    trackingState: "Stopped with error: " + error.code + " - " + error.message,
                    isTracking: false
                })
            },
            // Update UI when tracking starts
            () => this.setState({trackingState: "Started", isTracking: true}),
            // Update UI when tracking stops
            () => this.setState({trackingState: "Stopped", isTracking: false}));
    };

    // Call the initialization in componentWillMount
    UNSAFE_componentWillMount() {
        this._initializeHyperTrack();
    }

    // (Optional) Unregister tracking listeners if they were registered in previous step
    UNSAFE_componentWillUnmount() {
        this.hyperTrack.unregisterTrackingListeners(this);
    }

Step 6: Tag locations with geotags

Some places are more important then the others, so you can mark them on map, creating geotag when specific action in your app happens (e.g. delivery is marked done or driver confirmend pickup)

  // Tag the geolocation of app action
  this.hyperTrac.addGeotag({"action": "Login"});

If you already know the address, where action is supposed to happen, you can specify it to analyze the deviations

  // Tag the geolocation of app action
  const expectedLocation = {latitude: 35.0476912, longitude: -90.0260493};
  this.hyperTrac.addGeotag({"action": "Login"}, expectedLocation);

Step 7: Prepare for App Store and Play Market submission

Read the Prepare for App Store submission section of iOS SDK guide and Get approved for the background location access section of Android SDK guide.

You are all set

Once your app is running, go to the dashboard where you can see a list of all your devices and their live location with ongoing activity on the map.

Frequently Asked Questions

• Frequently Asked Questions (Android)
• Frequently Asked Questions (iOS)

Support

Join our Slack community for instant responses. You can also email us at help@hypertrack.com.