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.
- Create React Native project
- Configure projects
- Enable remote notifications
Step 1: Create React Native project
First create a React Native project:
npm install, if using npm) inside your new
Then, install the
Or, if using npm:
Finally, link the SDK to configure the iOS and Android projects:
Step 3: Configure projects
Assuming you have latest Android Studio installed, open the project with Android Studio.
app/src/main/java/com/<project name>/ to complete setup.
Register SDK package in method
Add in your
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).
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 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.
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 a new Swift file without creating a bridging header, and Xcode will create this setting for you. Set it to
5. You can then delete the file.
Install the native HyperTrack SDK through CocoaPods:
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.
- Open the iOS module files directory, located inside
- Open the app's workspace file (
.xcworkspace) in Xcode.
- Move the
HyperTrack.mfiles to your project. When shown a popup window, select
Create folder referencesand make sure
Copy items if neededis deselected. This will allow these files to update every time the JS module updates.
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
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: 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. 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.
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
If you already use firebase push notifications you can extend
HyperTrackMessagingService instead of Firebase, or declare two receivers side by side, if you wish.
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.
In the same tab, ensure that push notifications is enabled.
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
didFinishLaunchingWithOptions, use the SDK method to register for notifications.
Register device token
didFailToRegisterForRemoteNotificationsWithError methods, add the relevant lines so that HyperTrack can register the device token.
didReceiveRemoteNotification method, add the HyperTrack receiver. This method parses only the notifications that sent from HyperTrack.
If you want to make sure to only pass HyperTrack notifications to the SDK, you can use the "hypertrack" key:
Step 5: Usage
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 11.
Error: Access to Activity services has not been authorized
You are running your app on the iOS simulator, which currently does not support CoreMotion services. You can test the quickstart app on real iOS devices only.
- What API levels (Android versions) are supported?
- Why do I have NoClassDefFoundError?
- Why do I have dependencies conflicts?
- Why do I have persistent notification on my app?
- How do I handle custom ROMs?
- Why does HyperTrack notification show even after my app is terminated?
- How does tracking work in Doze mode?
- What is AAPT: error: attribute android:foregroundServiceType not found?
- Why doesn't setting device metadata and name work in SDK?
- What is device Id that I get from SDK?
What API levels (Android versions) are supported?
Currently we do support all of the Android versions starting from API 19 (Android 4.4 Kit Kat).
Why do I have NoClassDefFoundError?
I've added SDK and my app started failing with message like:
This takes place because on Android API level 19 and below you cannot have more than 65536 methods in your app (including methods in libraries).
Please check this StackOverflow answer for solutions.
Why do I have dependencies conflicts?
SDK dependencies graph looks like below:
Common problem here is depending on different versions of
com.android.support library components. You can explicitly specify required version by adding it as a dependency in your app's
and explicitly force SDK pick app's dependencies
That will take precedence over SDK version and you'll have one version of support library on your classpath.
Why do I have persistent notification on my app?
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 it is 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.
How do I handle 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 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.
You may also try out open source libraries like AutoStarter.
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:
Why does HyperTrack notification show 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 tracking is stopped, the notification goes away.
How does tracking work in Doze mode?
Doze mode requires device to be stationary, so before OS starts imposing power management restrictions, exact device location is obtained. When device starts moving, Android leaves Doze mode and works regularly, so no special handling of Doze mode required with respect to location tracking.
What is AAPT: error: attribute android:foregroundServiceType not found?
If build fails with error like
AAPT: error: attribute android:foregroundServiceType not found that means that you're targeting your app for Android P or earlier.
Starting from Android 10 Google imposes additional restrictions on services, that access location data while phone screen is turned off. Possible workaround here is to remove declared service property by adding following element to your app's manifest
Although you'll be able to avoid targeting API 29, but tracking service won't work properly on Android Q devices with screen been turned off or locked.
Why doesn't setting device metadata and name work in SDK?
Devices API or in PlayGround take precedence over SDK methods in setting device name and metadata. If you used either Devices API or PlayGround, these SDK methods
setDeviceName will not modify device metadata and name.
What is device Id that I get from SDK?
Device ID uniquely identifies SDK installation. Make sure that you stored it on your backend as a part of user profile to be able to identify location data. On Android 8 and later it is always the same for the app + publishable Key pair and persists across the installation. On devices, powered by earlier versions, it could change after reinstall, although there are some cases in which we are able to keep it the same. Anyway, users change devices and can use one login for multiple phones, so you need to handle that logic of updating device ids in backend.
Join our Slack community for instant responses. You can also email us at firstname.lastname@example.org.