Plug in the Android SDK

In this guide, we will setup the HyperTrack SDK in your Android app. At the end of this guide, you would be able to track a user in real time. You would see trips that the user made along with polylines, time & distance travelled, and places that the user stopped at along with time they spent at that place.

In case you are not using Android, you can refer to the iOS version.

[warning] Requirements

The SDK is compatible with Android 4.1 (API level 16) and above. Also, the SDK can only be used in devices that support GPS. Devices utilizing only A-GPS are not supported.

Step 1: Install the SDK

In your app's build.gradle file, define the repositories and dependencies as shown. Once configured, run a gradle sync to import the SDK and its dependencies to your project.

[info] build.gradle files

Your project will have two gradle files: one for the app module, and one for the project. Edit the app module file to install the SDK.

repositories {
    maven { url "" }

dependencies {
    compile("com.hypertrack:android:0.1.17:release@aar") {
        transitive = true;

[warning] Proguard rules

If you are using Proguard in your project add the following lines to your proguard configuration file (

  • -keep class com.hypertrack.lib.** { *; }
  • -dontwarn com.hypertrack.lib.**

Step 2: Configure the SDK

Now that the SDK has been installed, you can use the SDK methods inside Android Studio. Configure your publishable key and initialise the SDK in the onCreate method of your Application class.

HyperTrack.initialize(this.getApplicationContext(), “YOUR_PUBLISHABLE_KEY”);

Step 3: Configure GCM/FCM key

Configure your GCM or FCM key in the HyperTrack dashboard. GCM/FCM allows the SDK to be controlled by the server for better battery optimization and also adds robustness in recovering from crashes.

You can refer to Enable GCM/FCM guide for detailed steps or Test your GCM/FCM Integration section for testing your integration.

FCM Integration

To enable FCM integration, you need to change the base class for your implementation of FirebaseMessagingService to HyperTrackFirebaseMessagingService.

[info] Fresh FCM Integration

Add a new Service which extends HyperTrackFirebaseMessagingService to your application's manifest file with the tag as highlighted in the code snippet.

// Add a new class which extends `HyperTrackFirebaseMessagingService`
public class AppFCMListenerService extends HyperTrackFirebaseMessagingService {
    // Extend HyperTrackFirebaseMessagingService instead of FirebaseMessagingService
<!-- For fresh FCM integration, register the new file in your app's `AndroidManifest.xml` file -->
<service android:name=".AppFCMListenerService">
        <action android:name="" />

GCM Integration

To enable GCM integration, you need to change the base class for your implementation of GcmListenerService to HyperTrackGcmListenerService.

[info] Fresh GCM Integration

Add a new Service which extends HyperTrackGcmListenerService to your application's manifest file with the tag as highlighted in the code snippet.

// Add a new class which extends `HyperTrackGcmListenerService`
public class AppGCMListenerService extends HyperTrackGcmListenerService {
    // Extend HyperTrackGcmListenerService instead of GcmListenerService
<!-- For fresh GCM integration, register the new file in your app's `AndroidManifest.xml` file -->
<service android:name=".AppGCMListenerService">
        <action android:name="" />

Step 4: Configure Location Permissions & Settings

  • The SDK requires the ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions. These are already included in the SDK manifest so need not be explicitly added.

  • In case your app is for Marshmallow and above (API level 23+), Call requestPermissions() API to request for run-time location permissions.

  • For high quality location collection, the SDK needs location services enabled at high accuracy. Call requestLocationServices() API to request for user to enable Location Services in high-accuracy, if not enabled already.

Refer here for a sample implementation for requesting Location Permissions & Services.

// To request Location Permissions

// To enable Location Services
HyperTrack.requestLocationServices(this, null);

Step 5: Create SDK user

To be able to identify the device, the SDK needs a user id. You can create a new user user on the SDK, and specify a string identifier. This is a network call that requires the device to be online.

[info] User already created?

You can set an existing user id, in case you have created an user id via the backend API using the HyperTrack.setUserId("YOUR_USER_ID") method in the SDK.

HyperTrack.createUser(userName, new HyperTrackCallback() {
   public void onSuccess(@NonNull SuccessResponse response) {
       if (response.getResponseObject() != null) {
            User user = (User) response.getResponseObject();
            String userId = user.getId();
            // Handle user_id, if needed

   public void onError(@NonNull ErrorResponse error) {
       // Handle createUser error here
       Toast.makeText(this, error.getErrorMessage(), Toast.LENGTH_SHORT).show();

Step 6: Start the SDK

To start tracking the user, use the startTracking method. You can keep the SDK on throughout the day, or turn it off if you want to stop tracking the user at any point of time using the HyperTrack.stopTracking() method.


Step 7: View dashboard

Install your app with the HyperTrack SDK on a device and begin tracking on the Dashboard. You would see the user’s current state on the HyperTrack dashboard. If you click on the user, you should be able to view the user's trips and stops.

results matching ""

    No results matching ""