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 require 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

Why do I have dependencies conflicts?

Dependency conflicts may arise when the HyperTrack SDK is used together with different libraries. In most cases Gradle automatically resolves all the issues. In some situations, a configuration modification has to be applied to your project.

Detailed information

More information with detailed explanations and instructions can be found here: Gradle documentation

Cheat sheet

In case of unresolvable dependency conflicts, please use ./gradlew :your_project_name:dependencies command to see the dependency graph.
Usually there are bumped versions in dependency graph (marked like com.some.dependency:2.0.0 -> com.some.dependency:2.5.0) - Gradle automatically selects the newest version of the transitive dependencies required by other dependencies.
If conflicts are visible and cause compilation errors, you can manually exclude the transitive dependencies or downgrade them using: this documentation
Common problem here may be depending on different versions of com.android.support library components. You need to migrate to Android X to resolve the issue.

How do I handle system 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 also can be a result of some kind of battery saving settings. Check How do I handle system battery saver killing my app?

You may benefit from checking this also.

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 'AndroidRuntime: java.lang.IncompatibleClassChangeError: Found interface com.google.android.gms.location.FusedLocationProviderClient, but class was expected'?

If the target application / module (or any of the sub-dependencies) uses older Google Play Services Location dependency, a conflict in class definitions between them and HyperTrack SDK Google Play Services dependency can cause build or runtime failures.

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 newer version 21.0.0 or newer, you may encounter this issue.

💻
One of the Exceptions that happens with incompatible versions of Google Location Services is:
AndroidRuntime: java.lang.IncompatibleClassChangeError: Found interface com.google.android.gms.location.FusedLocationProviderClient, but class was expected

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 dependency to the newer version and check the grapg 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>')
    ...
}