Skip to content
Quickstart app for HyperTrack Android SDK
Branch: master
Clone or download

HyperTrack Quickstart for Android SDK


HyperTrack lets you add live location tracking to your mobile app. This repo contains an example client app that has everything you need to get started in minutes. This repo written in Java, checkout Kotlin quickstart if your feel more comfortable with it.

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 inbox.
  3. Open the Keys page, where you can copy your Publishable Key.

Keys page in dashboard

Next, you can start with the Quickstart app, or can integrate the SDK in your app.

Quickstart app

Step 1. Open this project in Android Studio


Step 2. Set your Publishable key

  1. Add the publishable key to MyActivity file.

  2. Run project on your device use simulator instance.

  3. Go through one-time permission flow (applicable for Android M and later).


Step 3. Check your location on the HyperTrack dashboard

Integrate the SDK

Step 1. Add Hypertrack SDK

Add following lines to your applications build.gradle:

// Import the SDK within your repositories block
repositories {
    maven {
        name 'hypertrack'
        url ''

//Add HyperTrack as a dependency
dependencies {
    implementation 'com.hypertrack:hypertrack:3.3.1'

Step 2. Start tracking.

Add SDK init call when you wan't to start tracking:

    HyperTrack.initialize(MyActivity.this, "your-publishable-key-here");

SDK will prompt for permission, if necessary, adding fragment on top of activity, that was passed in as a first argument. That's it. You have implemented tracking.

Step 3. (optional) Utility Methods

Turn tracking on and off

Depending on your needs, you can always stop and start tracking, invoking HyperTrack.stopTracking() and HyperTrack.startTracking() SDK methods. Also, checkout overloaded variants of initialize methods for fine-grained control on initialization, permission request and tracking start. You can determine current tracking state using HyperTrack.isTracking() call.

Add SDK state listener to catch events.

You can subscribe to SDK status changes HyperTrack.addTrackingStateListener(TrackingStateObserver.OnTrackingStateChangeListener) and handle them in the appropriate methods onError(TrackingError) onTrackingStart() onTrackingStop()

Customize foreground service notification

HyperTrack tracking runs as a separate foreground service, so when tracking is ON, your users will see a persistent notification. By default, it displays your app icon with text {app name} is running but you can customize it anytime after initialization by calling:

Identify devices

All devices tracked on HyperTrack are uniquely identified using UUID. You can get this identifier programmatically in your app by calling HyperTrack.getDeviceId() after initialization. Another approach is to tag device with a name that will make it easy to distinguish them on HyperTrack Dashboard.

HyperTrack.setNameAndMetadataForDevice(name, metaData);
Create trip marker

Use this optional method if you want to associate data with specific place in your trip. E.g. user marking a task as done, user tapping a button to share location, user accepting an assigned job, device entering a geofence, etc.

Map<String, Object> order = new HashMap<>();
order.put("item", "Martin D-18");
order.put("previousOwners", Collections.emptyList());
order.put("price", 7.75);


Look into documentation for more details.

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. Last step is to add your Firebase API key to HyperTrack dashboard under Server to Device communication section. FCM-key

You are all set

You can now run the app and start using HyperTrack. You can see your devices on the dashboard. Also you can find more about SDK integration here.


Once your app is running, go to the Dashboard page where you can see a list of all your devices and their location on the map.


Frequently Asked Questions

Supported versions

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.