Skip to content
React Native Quickstart app for HyperTrack SDKs
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
Images Add images Jul 17, 2019
__tests__ Release 1.0.0 Jun 7, 2019
.gitignore Add silent push notifications Jul 17, 2019
App.js Update tracking link Jul 18, 2019
LICENSE Add License Jun 8, 2019 Add silent push notifications Jul 17, 2019 Release 1.0.0 Jun 7, 2019
app.json Release 1.0.0 Jun 7, 2019
babel.config.js Release 1.0.0 Jun 7, 2019
index.js Release 1.0.0 Jun 7, 2019
metro.config.js Release 1.0.0 Jun 7, 2019
package-lock.json Update tracking link Jul 18, 2019
package.json Add silent push notifications Jul 17, 2019

React Native Quickstart for HyperTrack SDKs


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. This repo contains an example React Native app that has everything you need to get started in minutes.

Publishable Key

We use Publishable Key to identify your devices. To get one:

  1. Go to the Signup page. Enter your email address and password.
  2. Open the verification link sent to your email.
  3. Open the Setup page, where you can copy your Publishable Key.

Signup flow

Next, you can start with the Quickstart app, or can integrate the React Native module in your app.

Quickstart app

  1. Clone this repo
  2. Install the SDKs dependencies
  3. Set your Publishable Key
  4. Run the Quickstart app

Step 1: Clone this repo

git clone
cd quickstart-react-native

Step 2: Install the SDKs Dependencies

General Dependencies

npm install

iOS Dependencies

Quickstart app uses CocoaPods dependency manager to install the latest version of the iOS SDK. Using the latest version is advised.

If you don't have CocoaPods, install it first.

cd ios
pod install

After Cocoapods is finished installing dependencies, we need to manually link the wrapper code.

  1. Open the iOS module files directory, located inside node_modules/hypertrack-sdk-react-native/ios/.
  2. Open the app's workspace file (.xcworkspace) in Xcode.
  3. Move the RNHyperTrack.h and RNHyperTrack.m files to your project. When shown a popup window, select Create groups.

Linking on iOS

Step 3: Set your Publishable Key

Open the App.js file. Locate the line with publishableKey: "YOUR_PUBLISHABLE_KEY" in the App class and set your Publishable Key inside the placeholder.

Step 4: Run the Quickstart app

To run the iOS version open the app's workspace file (/ios/Quickstart.xcworkspace) with Xcode. Select your device and hit Run.

To run the Android version execute react-native run-android.

After enabling location and activity permissions (choose "Always Allow" if you want the app to collect location data in the background), SDK starts collecting location and activity data. You can start or stop tracking with the button below.

Check out the dashboard to see the live location of your devices on the map.

Integrate the React Native module

  1. Install the module
  2. Setup native dependencies
  3. Import the module
  4. Configure the Publishable Key
  5. Enable native capabilities on iOS
  6. (optional) Enable remote notifications

Step 1: Install the module

In your project directory, install the module from npm, and then link it.

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

Step 2: Setup native dependencies


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

Edit the Podfile to include HyperTrack as a dependency for your project by adding pod 'HyperTrack' line in your target. HyperTrack iOS SDK supports iOS 10 and above, that's why platform :ios, '10.0' is included explicitly. And lastly, add the post_install script to keep dependencies with the correct Swift version.

platform :ios, '10.0'

target 'AppName' do
  pod 'HyperTrack'

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if ['GRDB.swift', 'CocoaLumberjack'].include?
      target.build_configurations.each do |config|
        config.build_settings['SWIFT_VERSION'] = '4.2'

Check the Swift version in build settings. Open your .xcodeproj project file with Xcode. Select the projects Xcode project file in the navigator, go to your app's target (Should be with the same name as a project name) > Build Settings and search for SWIFT_VERSION flag. If there isn't one, create it by clicking on the plus icon to the left of the search bar, select "Add User-Defined Setting", name it SWIFT_VERSION and set it to 4.2.

Swift version

Install the native HyperTrack SDK through CocoaPods:

pod install
Manually link the wrapper code.

After Cocoapods is finished installing dependencies, we need to manually link the wrapper code. This is a required step, in addition to the link command described previously.

  1. Open the iOS module files directory, located inside node_modules/hypertrack-sdk-react-native/ios/.
  2. Open the app's workspace file (.xcworkspace) in Xcode.
  3. Move the RNHyperTrack.h and RNHyperTrack.m files to your project. When shown a popup window, select Create groups.

Linking on iOS


Update compileSdkVersion, buildToolsVersion, support library version

Edit the build.gradle file in your android/app directory:

android {
    compileSdkVersion 28
dependencies {
    compile project(':hypertrack-sdk-react-native')
    compile fileTree(dir: "libs", include: ["*.jar"])
    compile ""
    compile "com.facebook.react:react-native:+"  // From node_modules
Add maven for Google Play Service Libraries

Edit the build.gradle file in your android directory:

// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
    repositories {
        maven {
            url ''
            name 'Google'
    dependencies {
        classpath ''
        classpath ''

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files

allprojects {
    repositories {
        maven {
            name 'hypertrack'
            url ''
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url "$rootDir/../node_modules/react-native/android"
        maven {
            url ''
            name 'Google'

Step 3: Import the module

import { NativeModules } from 'react-native';
var RNHyperTrack = NativeModules.RNHyperTrack;

Step 4: Configure the Publishable Key

To configure the SDK, set the publishable key. This can be done in the constructor of your component class.

export default class App extends Component {
  constructor() {

Step 5: Enable native capabilities on iOS

Enable background location updates

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

Capabilities tab in Xcode

Add purpose strings

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

Always authorization location

Include Privacy - Location Always Usage Description key only when you need iOS 10 compatibility.

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.

In use authorization location

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

Step 6. Enable remote 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. For this purpose, the iOS SDK uses APNs silent remote notifications and Android SDK uses FCM silent notifications.


This guide assumes you have configured APNs in your application. If you haven't, read the iOS documentation on APNs.

Configure APNs on the dashboard

Log into the HyperTrack dashboard, and open the setup page. Upload your Auth Key (file in the format AuthKey_KEYID.p8) and fill in your Team ID.

This key will only be used to send remote push notifications to your apps.

Enable remote notifications in the app

In the app capabilities, ensure that remote notifications inside background modes is enabled.

Remote Notifications in Xcode

In the same tab, ensure that push notifications is enabled.

Push Notifications in Xcode

Registering and receiving notifications

The following changes inside AppDelegate will register the SDK for push notifications and route HyperTrack notifications to the SDK.

Register for notifications

Inside didFinishLaunchingWithOptions, use the SDK method to register for notifications.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [HTSDK registerForRemoteNotifications];
    return YES;
Register device token

Inside and didRegisterForRemoteNotificationsWithDeviceToken and didFailToRegisterForRemoteNotificationsWithError methods, add the relevant lines so that HyperTrack can register the device token.

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [HTSDK didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    [HTSDK didFailToRegisterForRemoteNotificationsWithError:error];
Receive notifications

Inside the didReceiveRemoteNotification method, add the HyperTrack receiver. This method parses only the notifications that sent from HyperTrack.

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [HTSDK didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];

If you want to make sure to only pass HyperTrack notifications to the SDK, you can use the "hypertrack" key:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    if (userInfo[@"hypertrack"] != nil) {
        // This is HyperTrack's notification
        [HTSDK didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
    } else {
        // Handle your server's notification here


This guide assumes you have configured FCM in your application. If you haven't, read the Firebase guide.

Configure FCM key on the Dashboard

Log into the HyperTrack dashboard, and open the setup page. Enter your FCM Key.

This key will only be used to send remote push notifications to your apps.

Enable server to device communication

Server to device communication uses firebase push notifications as transport for commands so for remote tracking state management Firebase integration is required. So you need to setup Firebase Cloud Messaging, if you have no push notifications enabled so far. Next step is to specify HyperTrackMessagingService as push messages receiver by adding following snippet to your apps Android manifest:

  <service android:name="com.hypertrack.sdk.HyperTrackMessagingService" android:exported="false">
          <action android:name="" />

If you already use firebase push notifications you can extend HyperTrackMessagingService instead of Firebase, or declare two receivers side by side, if you wish. Check out Quickstart app with notifications integrated if you prefer to get a look at example.

You are all set

You can now run the app and start using HyperTrack. You can see your devices on the dashboard.


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


Supported versions on iOS

Currently we do support all of the iOS versions starting from iOS 10.

Error: Access to Activity services has not been authorized

You are running the Quickstart app on the iOS simulator, which currently does not support CoreMotion services. You can test the quickstart app on real iOS devices only.


Supported versions on Android

Currently we do support all of the Android versions starting from API 19 (Android 4.4 Kit Kat)


I've added SDK and my app started failing with message like Fatal Exception: java.lang.NoClassDefFoundError. The reason of it, is that on Android API level 19 and below you cannot have more than 65536 methods in your app (including libraries methods). Please, check this Stackoverflow answer for solutions.


SDK dependencies graph looks like below:

+--- org.greenrobot:eventbus:3.1.1
+--- com.parse.bolts:bolts-tasks:1.4.0
+--- net.grandcentrix.tray:tray:0.12.0
|    \--- -> 28.0.0
|    +---
|    |    +---
|    |    |    \---
|    |    |         +---
|    |    |         |    +--- -> 28.0.0
|    |    |         |    \--- android.arch.lifecycle:runtime:1.0.0
|    |    |         |         +--- android.arch.lifecycle:common:1.0.0
|    |    |         |         \--- android.arch.core:common:1.0.0
|    |    |         +---
|    |    |         |    +--- -> 28.0.0
|    |    |         |    \--- (*)
|    |    |         +---
|    |    |         |    +--- -> 28.0.0
|    |    |         |    \--- (*)
|    |    |         +---
|    |    |         |    +--- -> 28.0.0
|    |    |         |    \--- (*)
|    |    |         \---
|    |    |              +--- (*)
|    |    |              +--- (*)
|    |    |              \--- (*)
|    |    \---
|    |         \--- (*)
|    +--- (*)
|    +---
|    |    \--- (*)
|    \--- (*)

Common problem here is depending on different versions of library components. You can explicitly specify required version by adding it as a dependency in your app's build.gradle, e.g.:

  implementation ``

That will take precedence over SDK version and you'll have one version of support library on your classpath.

Persistent notification

HyperTrack SDK, by default, runs as a foreground service. This is to ensure that the location tracking works reliably even when your app is minimized. A foreground service is a service that the user is actively aware of and isn't a candidate for the system to kill when low on memory. Android mandates that a foreground service provides a persistent notification in the status bar. This means that the notification cannot be dismissed by the user.


Handling custom ROMs

Smartphones are getting more and more powerful, but the battery capacity is lagging behind. Device manufactures are always trying to squeeze some battery saving features into the firmware with each new Android release. Manufactures like Xiaomi, Huawei and OnePlus have their own battery savers that kills the services running in the background. To avoid OS killing the service, users of your app need to override the automatic battery management and set it manual. To inform your users and direct them to the right setting page, you may add the following code in your app. This would intent out your user to the right settings page on the device.

try {
    Intent intent = new Intent();
    String manufacturer = android.os.Build.MANUFACTURER;
    if ("xiaomi".equalsIgnoreCase(manufacturer)) {
        intent.setComponent(new ComponentName("com.miui.securitycenter", "com.miui.permcenter.autostart.AutoStartManagementActivity"));
    else if ("oppo".equalsIgnoreCase(manufacturer)) {
        intent.setComponent(new ComponentName("com.coloros.safecenter", "com.coloros.safecenter.permission.startup.StartupAppListActivity"));
    else if ("vivo".equalsIgnoreCase(manufacturer)) {
        intent.setComponent(new ComponentName("", ""));

    List<ResolveInfo> list = context.getPackageManager().queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY);
    if  (list.size() > 0) {
    catch (Exception e) {

You may also try out open source libraries like

Some manufacturers don't allow to whitelist apps programmatically. In that case the only way to achieve service reliability is manual setup. E.g. for Oxygen OS (OnePlus) you need to select Lock menu item from app options button in Recent Apps view:


HyperTrack notification shows even after my app is terminated

The HyperTrack service runs as a separate component and it is still running when the app that started it is terminated. That is why you can observe that notification. When you stop tracking (stopTracking()), the notification goes away.


Join our Slack community for instant responses. You can also email us at

You can’t perform that action at this time.