com.hypertrack.sdk

Class HyperTrack

java.lang.Object

com.hypertrack.sdk.HyperTrack

public class HyperTrack
extends java.lang.Object

Main interface to use HyperTrack Android SDK in your app. SDK allows you to track current device in real-time in almost no effort while having ready to use dashboard and backend infrastructure already build for a bunch of existing use-cases. Usage:

     
         HyperTrack sdk = HyperTrack.getInstance(context, myPublishableKey)
                                    .setDeviceName("Elvis")
                                    .allowMockLocations()
                                    .addTrackingListener(this);

         Log.d(TAG, "HyperTrack device id is " + sdk.getDeviceID());

         sdk.start();

     

 

See our awesome Java or Kotlin quickstart for details.

Field Summary

Fields

Modifier and Type	Field and Description
CoreSDKProvider	mSdkProvider

Method Summary

Modifier and Type	Method and Description
static void	addNotificationIconsAndTitle(int smallIconId, int largeIconId, java.lang.String title, java.lang.String body) Deprecated. Use setTrackingNotificationConfig(ServiceNotificationConfig) Updates notification, that SDK will show once tracking is active.
static void	addNotificationIconsAndTitle(int smallIconId, int largeIconId, java.lang.String title, java.lang.String body, android.app.PendingIntent pendingIntent) Deprecated. Use setTrackingNotificationConfig(ServiceNotificationConfig) Updates notification, that SDK will show once tracking is active.
HyperTrack	addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener listener) Sets listener, that will be notified when tracking starts/stops or significant error occurred.
static void	addTrackingStateListener(TrackingStateObserver.OnTrackingStateChangeListener onTrackingStateChangeListener) Deprecated. use addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) instead. Registers a tracking state callback. SDK reinitialization removes all listeners.
HyperTrack	addTripMarker(java.util.Map<java.lang.String,java.lang.Object> tripMarkerData) Creates marker in trip with configurable payload.
HyperTrack	addTripMarker(java.lang.String tripMarkerData) Creates marker in trip with configurable payload.
HyperTrack	allowMockLocations() Allows you to use location mocking software (e.g.
static void	customEvent(java.util.Map<java.lang.String,java.lang.Object> eventData) Deprecated. Since 3.3.0 Use addTripMarker(Map) instead.
static void	enableDebugLogging() Enables debug log output.
static void	enableMockLocation() Deprecated. Use allowMockLocations() instead. Allows you to use mock provider to generate location data for tests etc.
static java.lang.String	getDeviceId() Deprecated. Use getDeviceID() instead.
java.lang.String	getDeviceID()
static HyperTrack	getInstance(android.content.Context context, java.lang.String publishableKey) Entry point to SDK usage.
static void	initialize(android.app.Activity activity, java.lang.String publishableKey, boolean shouldStartTracking, boolean shouldRequestPermissionIfMissing, TrackingInitDelegate trackingInitDelegate) Deprecated. Since 3.3.0 Use getInstance(Context, String)
static void	initialize(android.app.Activity activity, java.lang.String publishableKey, TrackingInitDelegate trackingInitDelegate) Deprecated. Since 3.3.0 Use getInstance(Context, String) instead.
static void	initialize(android.content.Context context, java.lang.String publishableKey) Deprecated. Use getInstance(Context, String) instead. Convenience method that calls initialize(Context, String, Config) with default config and auto start tracking. See aforementioned method description for details.
static void	initialize(android.content.Context context, java.lang.String publishableKey, boolean shouldStartTracking) Deprecated. Use getInstance(Context, String) and start() instead. E.g.: HyperTrack sdk = HyperTrack.getInstance(context, myPublishableKey) .start(); // retain sdk reference to get device id or stop tracking. Convenience method that calls initialize(Context, String, Config) with default config and selected shouldStartTracking. See aforementioned method description for details.
static void	initialize(android.content.Context context, java.lang.String publishableKey, Config sdkConfig) Deprecated. Use getInstance(Context, String) and start() E.g. HyperTrack sdk = HyperTrack.getInstance(context, myPublishableKey) .start(); // retain sdk reference to get device id or stop tracking. Most custom way to initialize HyperTrack SDK with configConfig.
boolean	isRunning()
static boolean	isTracking() Deprecated. use isRunning() instead Check tracking status.
HyperTrack	removeTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener listener) Removes listener or does nothing, if null was passed in as argument.
static void	removeTrackingStateListener(TrackingStateObserver.OnTrackingStateChangeListener onTrackingStateChangeListener) Deprecated. Use removeTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) instead. Removes a tracking state callback.
HyperTrack	requestPermissionsIfNecessary() Convenience method that will issue required permissions request dialog if necessary.
HyperTrack	setDeviceMetadata(java.util.Map<java.lang.String,java.lang.Object> metaData) Sets current device data, that can be used for easier dashboard navigation or grouping of location data in tag groups style.
HyperTrack	setDeviceMetadata(java.lang.String metaData) Sets current device data, that can be used for easier dashboard navigation or grouping of location data in tag groups style.
HyperTrack	setDeviceName(java.lang.String name) Sets current device name, that can be used for easier dashboard navigation.
static void	setNameAndMetadataForDevice(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> metaData) Deprecated. Use setDeviceName(String) and setDeviceMetadata(Map) instead. Sets current device data, that can be used for easier dashboard navigation. Use only after you've initialized the SDK. This setter is intended to be used for static data, that doesn't change during tracking sessions, as no SLA regarding this data propagation provided. In case of frequent changes, it is possible, that intermediate states could be lost, so if more real-time responsiveness is required it is recommended to use addTripMarker(Map) for passing that data.
HyperTrack	setTrackingNotificationConfig(ServiceNotificationConfig config) Allows to to customize persistent notification elements.
HyperTrack	start() Starts tracking, if all requirements are met (permissions are granted and publisahble Key is validated).
static void	startTracking() Deprecated. Use start() instead. Resumes tracking, that was previously paused by stopTracking() invocation. This should not be called, if you haven't paused tracking previously, since it default state is enabled. Please note, that if user hasn't granted location data access permission tracking service won't actually run. Use isTracking() to determine current tracking state.
static void	startTracking(boolean shouldRequestPermissionIfMissing, TrackingInitDelegate delegate) Deprecated. Since 3.3.0 Use getInstance(Context, String) ()} and start() instead.
HyperTrack	stop() Stops current tracking session.
static void	stopTracking() Deprecated. Use stop() instead. Pauses tracking. Use startTracking(boolean, TrackingInitDelegate) to start tracking service again.
HyperTrack	syncDeviceSettings() Sync device state with backend model.
static void	tripMarker(java.util.Map<java.lang.String,java.lang.Object> eventData) Deprecated. Use addTripMarker(Map) instead. Creates marker in trip with configurable payload. Please, bear in mind that this will be serialized as json so passing in recursive datastructure could lead to unpredictable results.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mSdkProvider

@NonNull
public final CoreSDKProvider mSdkProvider

Method Detail

enableDebugLogging

public static void enableDebugLogging()

Enables debug log output. This is very verbose, so you shouldn't use this for production build.

getInstance

public static HyperTrack getInstance(android.content.Context context,
                                     java.lang.String publishableKey)
                              throws java.lang.IllegalArgumentException

Entry point to SDK usage.

Parameters:

context - application context instance

publishableKey - Get it from HyperTrack dashboard.

Returns:

sdk instance that could be used to configure tracking settings and manipulate tracking state.

Throws:

java.lang.IllegalArgumentException - if null or empty publishable key or context were passed in.

addTripMarker

public HyperTrack addTripMarker(@NonNull
                                java.util.Map<java.lang.String,java.lang.Object> tripMarkerData)
                         throws java.lang.IllegalArgumentException

Creates marker in trip with configurable payload. Please, bear in mind that this will be serialized as json so passing in recursive datastructure could lead to unpredictable results.

Parameters:

tripMarkerData - key-value pairs.

Throws:

java.lang.IllegalArgumentException - if null or empty tripMarkerdata passed in.

requestPermissionsIfNecessary

public HyperTrack requestPermissionsIfNecessary()

Convenience method that will issue required permissions request dialog if necessary. Internally this will push new activity on top of current backstack popping it request is finished.

addTripMarker

public HyperTrack addTripMarker(@NonNull
                                java.lang.String tripMarkerData)
                         throws java.lang.IllegalArgumentException

Creates marker in trip with configurable payload. Please, bear in mind that this should be serialized json so passing in recursive datastructures could lead to unpredictable results.

Throws:

java.lang.IllegalArgumentException - if tripMarkerdata doesn't represent valid json object.

start

public HyperTrack start()

Starts tracking, if all requirements are met (permissions are granted and publisahble Key is validated). If tracking state listener was set before with addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) it will call TrackingStateObserver.OnTrackingStateChangeListener.onError(TrackingError) if tracking wasn't started or TrackingStateObserver.onStart() otherwise.

stop

public HyperTrack stop()

Stops current tracking session. If tracking state listener was set before with addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) it will call TrackingStateObserver.onStop() on success.

getDeviceID

public java.lang.String getDeviceID()

Returns:

identifier for current device that could be used to distinguish it in dashboard or other data sources.

isRunning

public boolean isRunning()

Returns:

true if tracking process was started successfully, or false otherwise. Please, bear in mind, that this doesn't mean that location data is actually sent, since some external changes (e.g. turning off location in system-wide settings etc) could block it.

allowMockLocations

public HyperTrack allowMockLocations()

Allows you to use location mocking software (e.g. for development). Mock locations are ignored by HyperTrack SDK by default.

setTrackingNotificationConfig

public HyperTrack setTrackingNotificationConfig(@Nullable
                                                ServiceNotificationConfig config)

Allows to to customize persistent notification elements. See more in FAQ

Parameters:

config - tracking notification parameters. See ServiceNotificationConfig for details.

setDeviceName

public HyperTrack setDeviceName(@Nullable
                                java.lang.String name)

Sets current device name, that can be used for easier dashboard navigation. This setter is intended to be used for static data, that doesn't change during tracking sessions, as no SLA regarding this data propagation provided. In case of frequent changes, it is possible, that intermediate states could be lost, so if more real-time responsiveness is required it is recommended to use addTripMarker(Map) for passing that data.

Parameters:

name - that will be visible in Dashboard.

setDeviceMetadata

public HyperTrack setDeviceMetadata(@Nullable
                                    java.util.Map<java.lang.String,java.lang.Object> metaData)

Sets current device data, that can be used for easier dashboard navigation or grouping of location data in tag groups style. This setter is intended to be used for static data, that doesn't change during tracking sessions, as no SLA regarding this data propagation provided. In case of frequent changes, it is possible, that intermediate states could be lost, so if more real-time responsiveness is required it is recommended to use addTripMarker(Map) for passing that data.

Parameters:

metaData - - key-value pairs.

See Also:

setDeviceMetadata(String)

setDeviceMetadata

public HyperTrack setDeviceMetadata(@NonNull
                                    java.lang.String metaData)

Sets current device data, that can be used for easier dashboard navigation or grouping of location data in tag groups style. This setter is intended to be used for static data, that doesn't change during tracking sessions, as no SLA regarding this data propagation provided. In case of frequent changes, it is possible, that intermediate states could be lost, so if more real-time responsiveness is required it is recommended to use addTripMarker(Map) for passing that data.

Parameters:

metaData - - valid JSON object string.

Throws:

java.lang.IllegalArgumentException - if argument does not represent valid JSON object.

See Also:

setDeviceMetadata(Map)

addTrackingListener

public HyperTrack addTrackingListener(@Nullable
                                      TrackingStateObserver.OnTrackingStateChangeListener listener)
                               throws java.lang.IllegalArgumentException

Sets listener, that will be notified when tracking starts/stops or significant error occurred. E.g. in case if SDK was initialized with incorrect publishable key, TrackingError.INVALID_PUBLISHABLE_KEY_ERROR will be delivered to litener's TrackingStateObserver.OnTrackingStateChangeListener.onError(TrackingError) callback. Does nothing when invoked with null argument.

Parameters:

listener - that will be used to deliver notifications.

Throws:

java.lang.IllegalArgumentException

See Also:

removeTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener)

removeTrackingListener

public HyperTrack removeTrackingListener(@Nullable
                                         TrackingStateObserver.OnTrackingStateChangeListener listener)
                                  throws java.lang.IllegalArgumentException

Removes listener or does nothing, if null was passed in as argument.

Parameters:

listener - to remove.

Throws:

java.lang.IllegalArgumentException

See Also:

addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener)

syncDeviceSettings

public HyperTrack syncDeviceSettings()

Sync device state with backend model. Allows you to automatically start tracking if any ongoing trips are present for this device and has no effect otherwise.

initialize

@Deprecated
public static void initialize(@NonNull
                                          android.content.Context context,
                                          @NonNull
                                          java.lang.String publishableKey)

Deprecated. Use getInstance(Context, String) instead. Convenience method that calls initialize(Context, String, Config) with default config and auto start tracking. See aforementioned method description for details.

Parameters:

context - context, that would be used to access application's Context.

publishableKey - Copy it from link

initialize

@Deprecated
public static void initialize(@NonNull
                                          android.content.Context context,
                                          @NonNull
                                          java.lang.String publishableKey,
                                          boolean shouldStartTracking)

Deprecated. Use getInstance(Context, String) and start() instead. E.g.:

 
     HyperTrack sdk = HyperTrack.getInstance(context, myPublishableKey)
                         .start();
     // retain sdk reference to get device id or stop tracking.

 

Convenience method that calls initialize(Context, String, Config) with default config and selected shouldStartTracking. See aforementioned method description for details.

Parameters:

context - context, that would be used to access application's Context.

publishableKey - Copy it from link

shouldStartTracking - if set to true, track will start automatically, when initialization finishes.

initialize

@Deprecated
public static void initialize(@NonNull
                                          android.content.Context context,
                                          @NonNull
                                          java.lang.String publishableKey,
                                          Config sdkConfig)

Deprecated. Use getInstance(Context, String) and start() E.g.

     
         HyperTrack sdk = HyperTrack.getInstance(context, myPublishableKey)
                             .start();
         // retain sdk reference to get device id or stop tracking.
     

 

Most custom way to initialize HyperTrack SDK with configConfig.

Parameters:

context - context, that would be used to access application's Context.

publishableKey - Copy it from link

sdkConfig - config of sdk Config

initialize

@Deprecated
public static void initialize(@NonNull
                                          android.app.Activity activity,
                                          @NonNull
                                          java.lang.String publishableKey,
                                          @NonNull
                                          TrackingInitDelegate trackingInitDelegate)

Deprecated. Since 3.3.0 Use getInstance(Context, String) instead.

See Also:

how to adopt delegate.

initialize

@Deprecated
public static void initialize(@NonNull
                                          android.app.Activity activity,
                                          @NonNull
                                          java.lang.String publishableKey,
                                          boolean shouldStartTracking,
                                          boolean shouldRequestPermissionIfMissing,
                                          @NonNull
                                          TrackingInitDelegate trackingInitDelegate)

Deprecated. Since 3.3.0 Use getInstance(Context, String)

Parameters:

activity - activity, that would be used to add permission request fragment (if required) and to access application's Context.

publishableKey - Copy it from link.

shouldStartTracking - if set to true, track will start automatically, when initialization finishes. Keep in mind, that location data permission decline will make tracking service unavailable to start, independently of this flag value.

shouldRequestPermissionIfMissing - if location data access permission is missing and value set to true, user will be presented with permission request dialog.

trackingInitDelegate - Handler for initialization result. Since initialization involves network activity and, optionally, user intection, invocation delay can be significant.

See Also:

how to write delegate adapter.

tripMarker

@Deprecated
public static void tripMarker(@NonNull
                                          java.util.Map<java.lang.String,java.lang.Object> eventData)
                                   throws java.lang.IllegalStateException

Deprecated. Use addTripMarker(Map) instead. Creates marker in trip with configurable payload. Please, bear in mind that this will be serialized as json so passing in recursive datastructure could lead to unpredictable results.

Parameters:

eventData - key-value pairs.

Throws:

java.lang.IllegalStateException - if SDK wasn't initialized.

customEvent

@Deprecated
public static void customEvent(@NonNull
                                           java.util.Map<java.lang.String,java.lang.Object> eventData)
                                    throws java.lang.IllegalStateException

Deprecated. Since 3.3.0 Use addTripMarker(Map) instead.

Throws:

java.lang.IllegalStateException

startTracking

@Deprecated
public static void startTracking(boolean shouldRequestPermissionIfMissing,
                                             @Nullable
                                             TrackingInitDelegate delegate)

Deprecated. Since 3.3.0 Use getInstance(Context, String) ()} and start() instead.

Parameters:

shouldRequestPermissionIfMissing - whether SDK should present permission request dialog or not.

delegate - callback receiver. See initialize(Activity, String, boolean, boolean, TrackingInitDelegate) for details.

See Also:

how to write delegate adapter.

startTracking

@Deprecated
public static void startTracking()

Deprecated. Use start() instead. Resumes tracking, that was previously paused by stopTracking() invocation. This should not be called, if you haven't paused tracking previously, since it default state is enabled. Please note, that if user hasn't granted location data access permission tracking service won't actually run. Use isTracking() to determine current tracking state.

stopTracking

@Deprecated
public static void stopTracking()

Deprecated. Use stop() instead. Pauses tracking. Use startTracking(boolean, TrackingInitDelegate) to start tracking service again.

isTracking

@Deprecated
public static boolean isTracking()

Deprecated. use isRunning() instead Check tracking status.

Returns:

true, if tracking is active and false otherwise.

addTrackingStateListener

@Deprecated
public static void addTrackingStateListener(@NonNull
                                                        TrackingStateObserver.OnTrackingStateChangeListener onTrackingStateChangeListener)

Deprecated. use addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) instead. Registers a tracking state callback. SDK reinitialization removes all listeners.

Parameters:

onTrackingStateChangeListener - TrackingStateObserver.OnTrackingStateChangeListener: Tracking state callback object to register. This value must never be null.

removeTrackingStateListener

@Deprecated
public static void removeTrackingStateListener(@Nullable
                                                           TrackingStateObserver.OnTrackingStateChangeListener onTrackingStateChangeListener)

Deprecated. Use removeTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) instead. Removes a tracking state callback.

Parameters:

onTrackingStateChangeListener - TrackingStateObserver.OnTrackingStateChangeListener: Tracking state callback object to remove. This value must never be null.

getDeviceId

@Deprecated
 @NonNull
public static java.lang.String getDeviceId()

Deprecated. Use getDeviceID() instead.

Returns:

UID for device, if SDK was initialized, or empty string otherwise.

setNameAndMetadataForDevice

@Deprecated
public static void setNameAndMetadataForDevice(@Nullable
                                                           java.lang.String name,
                                                           @Nullable
                                                           java.util.Map<java.lang.String,java.lang.Object> metaData)
                                                    throws java.lang.IllegalStateException

Deprecated. Use setDeviceName(String) and setDeviceMetadata(Map) instead. Sets current device data, that can be used for easier dashboard navigation. Use only after you've initialized the SDK. This setter is intended to be used for static data, that doesn't change during tracking sessions, as no SLA regarding this data propagation provided. In case of frequent changes, it is possible, that intermediate states could be lost, so if more real-time responsiveness is required it is recommended to use addTripMarker(Map) for passing that data.

Parameters:

name - that will be visible in Dashboard.

metaData - optional key-value pairs.

Throws:

java.lang.IllegalStateException - if SDK haven't been initialized yet.

addNotificationIconsAndTitle

@Deprecated
public static void addNotificationIconsAndTitle(@DrawableRes
                                                            int smallIconId,
                                                            @DrawableRes
                                                            int largeIconId,
                                                            @Nullable
                                                            java.lang.String title,
                                                            @Nullable
                                                            java.lang.String body)

Deprecated. Use setTrackingNotificationConfig(ServiceNotificationConfig) Updates notification, that SDK will show once tracking is active.

Parameters:

smallIconId - pass small icon id for notification.

largeIconId - pass large icon id for notification.

title - pass title for notification or null, to leave unchanged

body - pass body for notification or null, to leave unchanged

addNotificationIconsAndTitle

@Deprecated
public static void addNotificationIconsAndTitle(@DrawableRes
                                                            int smallIconId,
                                                            @DrawableRes
                                                            int largeIconId,
                                                            @Nullable
                                                            java.lang.String title,
                                                            @Nullable
                                                            java.lang.String body,
                                                            @Nullable
                                                            android.app.PendingIntent pendingIntent)

Deprecated. Use setTrackingNotificationConfig(ServiceNotificationConfig) Updates notification, that SDK will show once tracking is active.

Parameters:

smallIconId - pass small icon id for notification.

largeIconId - pass large icon id for notification.

title - pass title for notification or null, to leave unchanged

body - pass body for notification or null, to leave unchanged

pendingIntent - pass pendingIntent PendingIntent for notification or null, to leave unchanged

enableMockLocation

@Deprecated
public static void enableMockLocation()

Deprecated. Use allowMockLocations() instead. Allows you to use mock provider to generate location data for tests etc.