Android
Requirements
- The minimum Android version supported by HyperTrack SDK is
Android 5.0 Lollipop
(API level 21). - The minimum supported
targetSdk
is the same as current minimal value for Google Play submission. - The supported Android CPU architectures (Android ABIs) are:
arm64-v8a
,armeabi-v7a
,x86_64
,x86
. Emulators are also supported. - You need to have Google Play Services installed on the device for tracking to work. Huawei HMS Location Kit is not supported yet.
- HyperTrack SDK uses Firebase Cloud Messaging Android SDK as dependency, and minimal version is 23.1.1
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:
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:
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:
- android.permission.ACCESS_FINE_LOCATION
- android.permission.ACCESS_BACKGROUND_LOCATION - only for devices with Android 11 and above (API 30+)
- android.permission.POST_NOTIFICATIONS - only for for devices with Android 13 and above (API 33+)
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 1 month ago