Android SDK FAQ

Why starting tracking from the server fails?

HyperTrack relies on Firebase Cloud Messaging to deliver the tracking intent to the app, and to wake up the app if it is killed at that moment. This mechanism is generally reliable, but sometimes may fail or delay due to various reasons.

We recommend to check the following frequent issues:

• Check if you added FCM key properly as described in Set up silent push notifications.
• Check if you have matching app package and project ID for the key above and for the app.
• Check if you mistakenly use wrong environment (production vs development) for the app.
• Check if you have your app signature properly added to the Firebase project (may fail on debug builds).
• If you want to simulate waking the app up, make sure you don't use Force stop to kill the app (this feature disables push notifications for that app until the next launch). Kill the app with phone reboot, with simulated crash, or by manually stopping the activities and the services instead. Killing the app from Android Studio or adb also counts as Force stopping and blocks the push notifications.
• Check the push notification delivery with Firebase debug menu: call *#*#426#*#* in the device dialpad and press Events button. Reopen the debug app to update the logs.

Why do I have persistent notification in my app?

HyperTrack SDK by default runs as a foreground service. This is needed to ensure that the location tracking works reliably even when your app is in background.

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 requires foreground service to have a persistent notification in the status bar.

Can I customize the foreground service notification?

Yes, check the HyperTrackForegroundNotificationTitle and HyperTrackForegroundNotificationText parameters in SDK configuration doc.

You can also check the code example in Quickstart Android

How do I handle battery saver killing my app?

Check the Whitelisting doc to learn how to handle the battery saver killing your app.

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.

Why doesn't setting device metadata and name work in SDK?

Devices API take precedence over SDK methods in setting device name and metadata. If you used it, the SDK methods will not modify device metadata and name.

What runtime permissions are required for the SDK to work?

Chech the Grant permissions section

Why in the dashboard I can see SDK killed by ... outage reason?

SDK killed can be a result of some kind of battery saving settings. Check How do I handle system battery saver killing my app?

Can I test the tracking without actual movement?

Yes, please check the Test the workflow with mock locations doc.

How to fix Google Api Error: Invalid request - You must let us know whether your app uses any Foreground Service permissions. when uploading the app to Google Play with API?

This error can appear if you have targetSDK 34+. HyperTrack SDK have to use Foreground service, and starting Android 14 it requires declaring the Foreground service permission. If your app has this permission, you can't upload the update with API and need to do a manual release to fill in the Foreground service permissions form. Check our Guide if you have any issues with submitting the form.

How to fix device not getting any location events and not showing any outages?

This can ocassionally happen if the OS doesn't provide location updates despite the SDK requesting it. That can be caused by various reasons, like the device being in the area with bad GPS satellite visibility.

Another case is if you have the same issue on multiple devices, and none of them can get any location. This usually indicates that the SDK had the undelying exception when requesting location update with the message like this:

AndroidRuntime: java.lang.IncompatibleClassChangeError: Found interface com.google.android.gms.location.FusedLocationProviderClient, but class was expected

This error is caused by the dependency conflict: your app has older Google Play Services Location dependency, and HyperTrack SDK depends on the newer version.

The breaking change was added in version 21.0.0, and if your app depend on version 19.0.1 or older, and some other dependency (e.g. HyperTrack SDK) depend on 21.0.0 or newer, this exception is thrown.

You can check which dependency version you are using with Gradle dependency graph command:

./gradlew app:dependencies | grep 'com.google.android.gms:play-services-location'

gradlew app:dependencies

Check for lines containing com.google.android.gms:play-services-location. If any of them have version 19.0.1 or older, you should update the parent dependency to the newer version and check the graph again.

If updating the dependency is not possible there is a special Location services plugin in HyperTrack SDK to overcome this issue. Use it instead of implementation 'com.hypertrack:location-services-google:<version>:

dependencies {
    ...
    implementation 'com.hypertrack:location-services-google-19-0-1:<version>'
    ...
}

dependencies {
    ...
    implementation('com.hypertrack:location-services-google-19-0-1:<version>')
    ...
}

If you are using framework like Flutter or React Native, check the Plugins doc for according plugin dependencies.