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(myPublishableKey)
                                    .setDeviceName("Elvis")
                                    .allowMockLocations()
                                    .addTrackingListener(this);

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

         sdk.start();

     

 

See our awesome quickstart for details.

Field Summary

Fields

Modifier and Type	Field and Description
CoreSDKProvider	mSdkProvider

Method Summary

Modifier and Type	Method and Description
GeotagResult	addGeotag(java.util.Map<java.lang.String,?> payload) Convenience alias to addGeotag(Map, Location) with null expected location.
GeotagResult	addGeotag(java.util.Map<java.lang.String,?> payload, android.location.Location expected) Creates geotag with configurable payload.
HyperTrack	addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener listener) Sets listener, that will be notified when tracking starts/stops or significant error occurred.
HyperTrack	allowMockLocations() Allows you to use location mocking software (e.g.
HyperTrack	backgroundTrackingRequirement(boolean isRequired) Sets whether to request background location permission on Android 11 and later.
static void	enableDebugLogging() Enables debug log output.
static java.util.Set<Blocker>	getBlockers()
void	getCurrentLocation(AsyncResultReceiver<android.location.Location,OutageReason> receiver) Asynchronous access to the current device location.
java.lang.String	getDeviceID()
static HyperTrack	getInstance(java.lang.String publishableKey) Entry point to SDK usage.
Result<android.location.Location,OutageReason>	getLatestLocation() Latest device location, that is known to HyperTrack SDK.
boolean	isRunning()
HyperTrack	removeTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener listener) Removes listener or does nothing, if null was passed in as argument.
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	setDeviceName(java.lang.String name) Sets current device name, that can be used for easier dashboard navigation.
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).
HyperTrack	stop() Stops current tracking session.
HyperTrack	syncDeviceSettings() This method checks with HyperTrack cloud whether to start or stop tracking.

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(@NonNull
                                     java.lang.String publishableKey)
                              throws java.lang.IllegalArgumentException

Entry point to SDK usage.

Parameters:

publishableKey - Get it from HyperTrack dashboard. It is only used in first invocation, so providing different keys during one application session will have no effect.

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 was passed in.

addGeotag

@NonNull
public GeotagResult addGeotag(@NonNull
                                       java.util.Map<java.lang.String,?> payload)

Convenience alias to addGeotag(Map, Location) with null expected location.

addGeotag

@NonNull
public GeotagResult addGeotag(@NonNull
                                       java.util.Map<java.lang.String,?> payload,
                                       @Nullable
                                       android.location.Location expected)

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

Parameters:

payload - key-value pairs.

expected - location where the geotagging action is supposed to happen.

Returns:

Object holding deviation distance or the reason why it can't be computed.

See Also:

for more.

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.

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.OnTrackingStateChangeListener.onTrackingStart() otherwise.

stop

public HyperTrack stop()

Stops current tracking session. If tracking state listener was set before with addTrackingListener(TrackingStateObserver.OnTrackingStateChangeListener) it will call TrackingStateObserver.OnTrackingStateChangeListener.onTrackingStop() 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.

backgroundTrackingRequirement

public HyperTrack backgroundTrackingRequirement(boolean isRequired)

Sets whether to request background location permission on Android 11 and later. Default is true.

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 addGeotag(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 addGeotag(Map) for passing that data.

Parameters:

metaData - - key-value pairs.

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()

This method checks with HyperTrack cloud whether to start or stop tracking. Tracking starts when Devices or Trips API is used to either to start device tracking or when a trip is created for this device.

getLatestLocation

@NonNull
public Result<android.location.Location,OutageReason> getLatestLocation()

Latest device location, that is known to HyperTrack SDK.

Device location is constantly refreshed while the sdk is tracking, so the returned location represents current device location. Since the sdk uses accelerometer, gyroscope and other sensor data to optimize power consumption, this could be location computed seconds or minutes ago. If the location can't be retrieved for whatever reason (SDK isn't tracking, missing permissions, location services were disabled etc) null is returned.

Returns:

latest device location, that is known to HyperTrack SDK or null, if it's unknown.

See Also:

()

getCurrentLocation

public void getCurrentLocation(@NonNull
                               AsyncResultReceiver<android.location.Location,OutageReason> receiver)

Asynchronous access to the current device location.

getBlockers

@NonNull
public static java.util.Set<Blocker> getBlockers()

Returns:

Set of blockers, that need to be resolved to start the tracking.

See Also:

Blocker