Troubleshoot Android SDK

Basic 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.

External Dependencies

The HyperTrack SDK includes following dependencies:

Name Version Description
Google Play Services libraries 15.0.0 This includes play-services-gcm, play-services-location, play-services-maps and play-services-places libraries
Firebase Messaging library 15.0.0 For FCM support
Android v7 support 27.1.1 For PlaceSelector widget: this includesrecyclerview-v7 and cardview-v7 libraries.
Android Volley library 1.0.0 For HTTP networking
Gson library 2.8.1 For data serialization and deserialization
SmartScheduler 0.0.13 For job scheduling
HyperLog 0.0.10 For storing logs into database and push them to remote server for debugging.
Sentry 1.6.4 Crash Reporting Tool

The latest version of these libraries will be automatically included as transitive dependencies. To exclude transitive dependencies to resolve version conflicts, you can exclude them by specifying transitive = false and including all the above mentioned dependencies separately. Once you have, clear your Gradle cache and sync your project.

Use Different Versions of Dependencies

By default the HyperTrack SDK includes the above mentioned libraries with their versions as specified. In case a different version of one of these library is a dependency to your app or to another library you have integrated, you can follow the following step to resolve this conflict. You will have to remove the required dependency from the HyperTrack SDK by using exclude command and manually add these dependencies separately. Once you have, clear your Gradle cache and sync your project.

repositories {
    maven {
      url ""

dependencies {

     * Add and dependencies of the
     * version that you have included or want to include.
    compile ''
    compile ''
    compile ''
    compile ''
    compile ''


     * Exclude and dependencies
     * from HyperTrack SDK dependency for versions other than what is being
     * used by the HyperTrack SDK.
    compile("com.hypertrack:android:0.7.36:release@aar") {
        transitive = true;
        exclude group: '', module: 'firebase-messaging'
        exclude group: '', module: 'play-services'


Persistent SDK notification

Default notification

Foreground service

  • By default, HyperTrack runs as a service in the background to collect data. However, background services may be killed and restarted by the OS. The OS may do this when it needs to allocate memory to other tasks (for example, to display a large page in the browser) or to conserve battery. The OS will then restart the HyperTrack service automatically when resources are available again.

  • This killing and restarting by the OS often results in patches with missing data. To get higher fidelity tracking with HyperTrack, it is recommended that you use HyperTrack as a foreground service. This is the DEFAULT option.

  • Android O is coming up with restrictions on background updates which will also need for HyperTrack SDKs to run as a foreground service for location limits.

  • You can customize this notification by following our customize guide.

Customizing notification (basic)

Use these basic UI customizations to edit the icon and/or text.

[info] Android docs

For more information on how Notifications work, refer to the Android documentation.

Notification icon

By default, the notification's small icon is selected according to the icon specified in the android:icon tag in your AndroidManifest.xml file. You can customise the icons by adding drawable resources in your application with the same name as follows:

  • For the small icon, add an icon with the name ic_ht_service_notification_small
  • For the large icon, add an icon with the name ic_ht_service_notification_large

Notification text

By default, the notification text is "Touch here to open the app". You can customise the text by adding string resources in your application with the same name as ht_service_notification_text

<?xml version="1.0" encoding="utf-8"?>
    <string name="ht_service_notification_title">Driver App is running</string>
    <string name="ht_service_notification_text">Touch here to open the app</string>
    <string name="ht_service_notification_group_key">hypertrack</string>
    <string name="ht_service_notification_channel_id">com.hypertrack</string>
    <string name="ht_service_notification_channel_name">HyperTrack</string>

Notification click

By default, tapping the notification opens the LAUNCHER Activity specified in your AndroidManifest.xml file. To customise it call HyperTrack.setServiceNotificationParams() API with an instance of ServiceNotificationParams as depicted in the next section.

Customizing notification (advanced)

In case you need to dynamically change the notification, or you want to use the Android Rich Notifications, follow these steps. These settings once set will persist till the App Data persists.

Advanced notification

Building notification params

To customize the Notification, we need to create a ServiceNotificationParams object. Following params can be customized using ServiceNotificationParamsBuilder object.

Parameters Description
smallIconResId required ResourceId for Small Icon for the Notification Layout and StatusBar Icon
smallIconBGColor Color Value for the Small Icon Background on the Notification layout
groupKey To merge the notifications
channelName Channel Name for Android 8.0 and above
channelId Channel Id for Android 8.0 and above
largeIconResId ResourceId for Large Icon for the Notification Layout
contentTitle Content Title for the Notification
contentText Content Text for the Notification
contentIntentActivityClassName Class Name for the Activity to be launched on Notification Click
setContentIntentExtras List of Extras to be passed along with Notification's intent
RemoteViews Inflated view for the custom layout to be set as Notification Layout
List List of Notification.Action to be added in Notification Layout
// Get ServiceNotificationParamsBuilder Object
ServiceNotificationParamsBuilder builder = new ServiceNotificationParamsBuilder();

// List of Extras to be passed along with Notification.Action's Intent
ArrayList<String> extras = new ArrayList<>();

// Create ServiceNotificationParams using ServiceNotificationParamsBuilder
final ServiceNotificationParams notificationParams = builder
    .setSmallIconBGColor(ContextCompat.getColor(getApplication(), R.color.colorAccent))
    .setContentTitle("Driver Demo is running")
    .setContextText("Touch here to open the Driver Demo app.")

Set notification params

The Notification Params build can be set using the HyperTrack.setServiceNotificationParams() API


Clear notification params

Notification Params set using setServiceNotificationParams() API are stored in persistent storage. In case the notification settings needs to be reset, call HyperTrack.clearServiceNotificationParams API to reset to default settings.


Adding notification actions to the notification

The service notification provides support for Notification.Action that can be added as part of this notification. It must include an icon, a label, a Class name & an Intent type for the PendingIntent to be fired when the action is selected by the user.

  1. To add an Notification.Action to the notification, create an instance of ServiceNotificationAction as shown in the code snippet.
  2. Set a List of such ServiceNotificationAction objects to the notification using setActionsList method of ServiceNotificationParamsBuilder.
  3. Additionally, you can also provide a list of Strings as Extras which needs to be passed along with an Notification.Action's intent. Intent extras will contain this list as a key with the name HyperTrackConstants.HT_SERVICE_NOTIFICATION_INTENT_EXTRAS_LIST.
// List of Extras to be passed along with Notification.Action's Intent
ArrayList<String> extras = new ArrayList<>();

// Create an instance of ServiceNotificationAction
ServiceNotificationAction likeAction = new ServiceNotificationAction(R.drawable.ic_notification_like, "Like",

[warning] Intent Activity's launchMode settings

In order for ServiceNotificationActionIntentType.ACTION_INTENT_TYPE_ACTIVITY Intents to work as expected, the Activity's launchMode has to be set to either singleTop or singleTask. Also, in case of already running Activities, the Intent has to be handled in Activity's onNewIntent method.

Identifying intent clicks

To identify the source of the intent click, the Intent of the click will contain an Extra by the name HyperTrackConstants.HT_SERVICE_NOTIFICATION_INTENT_TYPE.

Click source Extra value

With action clicks, the actionText param specified in the ServiceNotificationAction object is also sent as an Extra by the name HyperTrackConstants.HT_SERVICE_NOTIFICATION_INTENT_ACTION_TEXT.

Disabling persistent notification

If your app is a consumer app and you want the location tracking to happen silently, then you may want to disable the notification. It can be done by calling HyperTrack.disablePersistentNotification(true). You need to call this only once on a device. This setting is purged only if the app is deleted. By default, persistent notification is enabled when the sdk is integrated. Note that location tracking will be still useful though less reliable if the notification is disabled.

Merging persistent notification

If your service already has a persistent notification, you can merge HyperTrack's persistent notification with the existing one.

HyperTrack uses groupKey in the notification builder. Use 101010 as notification Id while creating notification in your code. Note that this is supported in SDK version v0.6.20 and above.


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.**

results matching ""

    No results matching ""