Guides

Android

Android SDK

Requirements

Basic integration

Updating the SDK? Check out our CHANGELOG and Migration Guide to see what's changed.

Add HyperTrack SDK to your project

Add HyperTrack's Maven repository

Depending on the Gradle version used in the Project use one of the following snippets:

With centralized repositories declaration

This way of managing dependencies was added in Gradle 6.8 and is required by default in Gradle 8.

dependencyResolutionManagement {
    ...
    repositories {
        google()
        mavenCentral()
        jcenter()

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


dependencyResolutionManagement {
    ...
    repositories {
        google()
        mavenCentral()
        jcenter()

        maven {
            name = 'hypertrack'
            url = 'https://s3-us-west-2.amazonaws.com/m2.hypertrack.com/'
        }
    }
}
Without centralized repositories declaration

Add the repository to your module-level Gradle config (usually app/build.gradle) and project-level one (<project folder>/build.gradle).

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

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

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            name 'hypertrack'
            url  'https://s3-us-west-2.amazonaws.com/m2.hypertrack.com/'
        }
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            name = 'hypertrack'
            url = 'https://s3-us-west-2.amazonaws.com/m2.hypertrack.com/'
        }
    }
}

Add HyperTrack SDK dependencies

Add HyperTrack SDK dependencies to the app or module

dependencies {
    ...
    implementation 'com.hypertrack:sdk-android:<version>'
    implementation 'com.hypertrack:location-services-google:<version>'
    implementation 'com.hypertrack:activity-service-google:<version>'
    implementation 'com.hypertrack:push-service-firebase:<version>'
    ...
}

dependencies {
    ...
    implementation('com.hypertrack:sdk-android:<version>')
    implementation('com.hypertrack:location-services-google:<version>')
    implementation('com.hypertrack:push-service-firebase:<version>')
    ...
}

The latest version: SDK-Android

You can learn more about SDK plugins here.

⚠️

Because of a known issue in Google Play Services Location library, if you use version 19.0.1 or older you need to use the special version of the HyperTrack SDK Location Services plugin. Check this FAQ item for more details.

💻

After adding dependencies make sure you run Sync Project with Gradle Files!

Configure Proguard

Make sure you are using the latest SDK version.

If you use Proguard (have minifyEnabled true in your app build.gradle) add these lines to your proguard-rules.pro:

# config for kotlin-coroutines
-keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
-keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
-keepclassmembernames class kotlinx.** {
    volatile <fields>;
}
-keep class kotlinx.coroutines.android.AndroidDispatcherFactory {*;}

Set up silent push notifications

HyperTrack SDK requires Firebase Cloud Messaging to:

  • Manage on-device tracking
  • Enable HyperTrack cloud APIs usage to control the tracking from your server
  • Waking up the app if it was killed by the device OS

If you do not yet have push notifications enabled, please proceed to Setup Firebase Cloud Messaging.

To provide HyperTrack the access to sending push messages you need to get a JSON key for a Google Cloud Service account with Firebase access that is connected to your app. You need to upload the key to HyperTrack Dashboard Setup Page under Server to Device communication section.

If you don't know how to get the key, check the guide: Getting Google Service account key for Firebase

Set the publishable key

Get your Publishable Key from the Setup page.

Add PublishableKey to AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application android:name=".AnApplication">
        <meta-data
            android:name="HyperTrackPublishableKey"
            android:value="put-your-key-here" />
    </application>
</manifest>

Set Worker Handle

To link a Worker with the device you should set the worker handle:

HyperTrack.workerHandle = "user_id" // unique user identifier

See Worker device linking guide for more information.

Grant the permissions to the app

The application has to ask for runtime permissions before the SDK will be able to track.

The permissions that are necessary are:

Start Tracking

Now the app is ready to be tracked from the cloud.

You will need the device id to start tracking, check the Identify devices section for instructions on how to get it.

Follow the Track Work tutorial to learn how to control device tracking from your backend.

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.

Recommended additional steps

Identify devices

All devices tracked on HyperTrack are uniquely identified using UUID. You can get this identifier programmatically in your app by calling getDeviceId().

⚠️

The device ID is changed on each app re-install or clearing the app data

   val deviceId = HyperTrack.deviceID

   String deviceId = HyperTrack.getDeviceID();

Another approach to identification is to tag devices with names that will make it easy to distinguish them on HyperTrack Dashboard.

   HyperTrack.name = "Device name"

   HyperTrack.setName("Device name");

You can additionaly tag devices with custom metadata (and filter them in the Dashboard using metadata fields).

Metadata should be representable with a map of JSON data types.

You need to build a special Json.Object data type to send the data to the SDK. This type ensures that the format is JSON-compatible. There are 2 helper methods to build this object from Map or JSON string, but you can build it manually too using the constructor methods.

Kotlin

import com.hypertrack.sdk.android.Json

val metadataJson: Json? = Json.fromString("{ \"key\":\"value\" }")

if(metadataJson != null) {
    HyperTrack.metadata = metadataJson
} else {
    // You will get the null value if provided String is not a valid JSON
}

import com.hypertrack.sdk.android.Json

val metadataJson: Json? = Json.fromMap(mapOf("key" to "value"))

if(metadataJson != null) {
    HyperTrack.metadata = metadataJson
} else {
    // You will get the null value if provided Map is not a valid JSON Map
}

Java

import com.hypertrack.sdk.android.Json

Json.Object metadataJson = Json.Companion.fromString("{ \"key\":\"value\" }")

if(metadataJson != null) {
    HyperTrack.setMetadata(metadataJson)
} else {
    // You will get the null value if provided String is not a valid JSON
}

import com.hypertrack.sdk.android.Json

Map myMetadata = new HashMap<String, Object>()
myMetadata.put("key", "value")

Json.Object metadataJson = Json.Companion.fromMap(myMetadata)

if(metadataJson != null) {
    HyperTrack.setMetadata(metadataJson)
} else {
    // You will get the null value if provided Map is not a valid JSON Map
}

Handle errors

Use the errors query or subscribeToErrors subscription to make sure that when the driver navigates to the screen where tracking is supposed to happen, there are no blockers that can interrupt it.

You can use subscription API to be able to react immediately when errors come up:

// You can use this value to cancel the subscription.
val errorsCancellable: HyperTrack.Cancellable? = null

errorsCancellable = HyperTrack.subscribeToErrors { errors ->
  errors.forEach {
    when(it) {
      is Permissions.Location.Denied -> ...
      is Location.ServicesDisabled -> ...
      ...
    }
  }
}

Or by querying the API only when needed:

HyperTrack.errors.forEach {
  when(it) {
    is Permissions.Location.Denied -> ...
    is Location.ServicesDisabled -> ...
    ...
  }
}

See Error API reference for a full list of errors.

Reference

For a full SDK API reference see HyperTrack Android SDK

SDK integration examples

To learn more about SDK integration examples, you may visit these resources:

Support

Join our Slack community for instant responses.

Updated about 2 months ago

What’s Next