Android
For the following chapter, please select Java to see relevant sample code on the right side.
Android Views are implemented using GraphQL subscriptions and enable server-to-client communication without the need to integrate Webhooks on the backend.
The module handles websockets and provides easy-to-consume methods to retrieve device status and subscribe to programmatic notifications about key moments in the movement tracking of devices and trips, as they happen.
This reference shows methods available in the Android Views module. You can also review the generated JavaDoc files.Get device status
// Get SDK instance with Context reference
// replace <PUBLISHABLE_KEY> with your own key
HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, <PUBLISHABLE_KEY>);
// replace <DEVICE_ID> with your device ID
hypertrackView.getDeviceMovementStatus(<DEVICE_ID>,
new Consumer<MovementStatus>() {
@Override
public void accept(MovementStatus movementStatus) {
Log.d(TAG, "Got movement status data " + movementStatus);
}
});
val hyperTrackView = HyperTrackViews.getInstance(this, PUBLISHABLE_KEY)
hyperTrackView.getDeviceMovementStatus(DEVICE_ID)
{Log.d(TAG, "Got movement status $it")}
Get device information by device ID. The callback receives a MovementStatus
object describing the device.
Movement Status
The device movement status object encapsulates all data associated with a device, similar to the Device API. It provides the latest snapshot of the device state, including ...
- Device location, including coordinates, speed, altitude, bearing, accuracy, and timestamp of record
- Device status, including activity and timestamp of record
- Battery information, can be one of
BATTERY_CHARGING
,BATTERY_LOW
, andBATTERY_NORMAL
- General device information
- Share and embed view URLs associated with the device
- Trips associated with the device
Location Object
Location location = movementStatus.location;
if (location != null) {
Log.d(TAG, "Got device location " + location +
" with latitude " + location.getLatitude() +
" and longitude " + location.getLongitude());
}
val location = movementStatus?.location
location?.let {
Log.d(TAG, "Got device location $location " +
"with latitude ${location.latitude}" +
"and longitude ${location.longitude}")
Accessor method | Type | Description |
---|---|---|
getLatitude() | double | Latitude in degrees. Negatives are for southern hemisphere. |
getLongitude() | double | Longitude in degrees. Negatives are for western hemisphere. |
getAltitude() | Double | Altitude in m. Could be null , if value is not available. |
getSpeed() | Double | Speed in m/s. Could be null , if device is stationary |
getBearing() | Double | Bearing in degrees starting at due north and continuing clockwise around the compass |
getAccuracy() | Double | Horizontal accuracy in m |
getRecordedAt() | String | ISO 8601 date when the location was recorded |
Device Status Object
DeviceStatus status = movementStatus.deviceStatus;
if (status != null) {
Log.d(TAG, "Device is " + (status.isDisconnected() ? "disconnected" : "connected"));
}
val status = movementStatus?.deviceStatus
status?.let {
Log.d(TAG, "Device is ${(if (status.isDisconnected) "disconnected" else "connected")}")
}
Member | Type | Description |
---|---|---|
createdAt | String | ISO 8601 date when the device status was created |
isActive() | boolean | Returns true if device is active (it's current location is known and updated) and false otherwise |
isDisconnected() | boolean | Returns true if device is disconnected (it's location wasn't updated for a while) and false otherwise |
isInactive() | boolean | Returns true if tracking data is unavailable because of lack of permissions or tracking was stopped intentionally and false otherwise |
status | int | Property provides more extended description of current state, e.g. whether it it is driving, if active, etc. See JavaDoc for the list of possible values and their meaning. |
Device Info Properties
DeviceInfo deviceInfo = movementStatus.deviceInfo;
if (deviceInfo != null) {
Log.d(TAG, "Got status for device " + deviceInfo.name);
}
val deviceInfo = movementStatus?.deviceInfo
deviceInfo?.let {
Log.d(TAG, "Status from device ${deviceInfo.name}")
}
Parameter | Type | Description |
---|---|---|
appName | String | Name of the hosting app |
appVersionNumber | String | Version of the hosting app |
appVersionString | String | Version of the hosting app |
deviceBrand | String | The device brand |
deviceModel | String | The device model |
name | String | The name of the device |
osName | String | The operating system of the device, can be one of iOS or Android |
osVersion | String | The version of the operating system on the device |
sdkVersion | String | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
DeviceViewUrls Properties
This object incapsulates resources that could be used to open WebView Widget (embedded view) or for sharing location via link.
String shareUrl = movementStatus.deviceViewUrls.embedUrl;
Uri uri = Uri.parse(shareUrl + PUBLISHABLE_KEY);
Intent intent = new Intent(Intent.ACTION_VIEW, uri);
if (intent.resolveActivity(getPackageManager()) != null) {
startActivity(intent);
}
val shareUrl = movementStatus.deviceViewUrls.embedUrl
val uri = Uri.parse(shareUrl!! + PUBLISHABLE_KEY)
val intent = Intent(Intent.ACTION_VIEW, uri)
if (intent.resolveActivity(packageManager) != null) {
startActivity(intent)
}
Parameter | Type | Description |
---|---|---|
embedUrl | String | Embeddable view URL |
shareUrl | String | Sharable view URL |
Trip Properties
Trip{
tripId="3737e382-b251-11e9-a7f6-f6b591671d93",
startedAt="2019-07-29T22:35:49.963554Z",
completedAt="",
status="active",
destination=Destination{
geometry=Geometry{
coordinates=[-122.437941, 37.800563]
},
radius=30,
scheduledAt=""
},
estimate=Estimate{ ... },
metadata="",
summary=""
}
Method | Type | Description |
---|---|---|
getTripId() | String | Unique identifier of the newly created trip, case sensitive |
getStatus() | String | Trip status, can be either active or completed |
getStartedAt() | String | Timestamp for trip starting time |
getMetadata() | String | Metadata provided at trip start |
getSummary() | String | Trip summary, only provided upon completion of a trip |
getDestination() | Trip.Destination | Destination of the trip, or null if trip has no destination |
getEstimate() | Trip.Estimate | Trip summary, only provided for trips with status active |
getCompletedAt() | String | ISO 8601 date when the trips was completed or null if it haven't been completed |
Trip Estimate Properties
Estimate{
arriveAt="",
route=Route{ ... }
}
Method | Type | Description |
---|---|---|
getArriveAt() | String | Timestamp for estimated arrival |
getRoute() | Trip.Route | Planned route segments to destination |
Trip Route Properties
Route{
distance=210,
duration=1720,
startAddress="1 Embarcadero Center, San Francisco, CA, 94122",
endAddress="353 Sacramento St, San Francisco, CA, 94122",
polyline=Polyline{ ... }
}
Method | Type | Description |
---|---|---|
getDistance() | Integer | Timestamp for estimated arrival |
getDuration() | Integer | Duration in seconds |
getStartAddress() | String | Street address lookup for segment start |
getEndAddress() | String | Street address lookup for segment end |
getPoints() | List of List of Double | Planned route segments to destination, as array of longitude, latitude and altitude (optional) tuples |
Trip Destination Properties
Destination{
geometry=Geometry{ ... },
radius=30,
scheduledAt="2019-07-29T22:35:49.963554Z"
}
Method | Type | Description |
---|---|---|
getLatitude() | Double | Latitude coordinate of destination center point in degrees. Negatives are for southern hemisphere |
getLongitude() | Double | Longitude coordinate of destination center point in degrees. Negatives are for western hemisphere |
getRadius() | Integer | Radius (in meters) of a circular trip destination |
getScheduledAt() | String | Timestamp for scheduled arrival |
Subscribe to updates
// Get SDK instance with Context reference
// replace <PUBLISHABLE_KEY> with your own key
HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, <PUBLISHABLE_KEY>);
// replace <DEVICE_ID> with your device ID
hypertrackView.subscribeToDeviceUpdates(<DEVICE_ID>,
new DeviceUpdatesHandler() {
@Override
public void onLocationUpdateReceived(@NonNull Location location) {
Log.d(TAG, "onLocationUpdateReceived: " + location);
}
@Override
public void onBatteryStateUpdateReceived(@BatteryState int i) {
Log.d(TAG, "onBatteryStateUpdateReceived: " + i);
}
@Override
public void onStatusUpdateReceived(@NonNull StatusUpdate statusUpdate) {
Log.d(TAG, "onStatusUpdateReceived: " + statusUpdate);
}
@Override
public void onTripUpdateReceived(@NonNull Trip trip) {
Log.d(TAG, "onTripUpdateReceived: " + trip);
}
@Override
public void onError(Exception e, String deviceId) {
Log.w(TAG, "onError: ", e);
}
@Override
public void onCompleted(String deviceId) {
Log.d(TAG, "onCompleted: " + deviceId);
}
}
);
You can subscribe to receive device state changes as they come in. The DeviceUpdatesHandler
should implement and override the following interface methods:
Method | Parameter | Description |
---|---|---|
onLocationUpdateReceived | Location | Location update |
onBatteryStateUpdateReceived | BatteryState | Battery update, can be one of BATTERY_CHARGING , BATTERY_LOW , and BATTERY_NORMAL |
onStatusUpdateReceived | StatusUpdate | Status update |
onTripUpdateReceived | Trip | Trip update |
onError | Exception, Device ID (String ) | Error with exception details and device ID |
onCompleted | Device ID (String ) | Completion with Device ID |
StatusUpdate Properties
StatusUpdate{
value="WALK",
hint="",
recordedAt="2019-07-29T22:35:49.963554Z"
}
Parameter | Type | Description |
---|---|---|
value | String | Health event type, can be one of DRIVE , STOP , or WALK |
hint | String | Health hint. Additional information about the health event |
recordedAt | String | ISO 8601 date when the device status was recorded |
Unsubscribe from updates
You can unsubscribe from all the updates that you are subscribed to using below method:
Method | Parameter | Description |
---|---|---|
stopAllUpdates | void | Stops all the updates, that were scheduled for this SDK instance. |
hypertrackView.stopAllUpdates();
iOS
Refer to the integration guide for additional details.
Device Status
A device is either active or inactive at any given time.
Active
Location and activity data is tracking as expected.
Inactive
Location or activity data are not tracking. Error codes for reasons are documented in this section.
See this example how Device API provides insight into device outage status. Also, see this example how you can use a webhook payload device status update to help you receive outage codes and act on them.
Disconnected
HyperTrack platform is unable to sync with the device.
HyperTrack is a cloud platform to track ground truth of the device. There are times when the platform goes out of sync with the device. If and when the connection between device and platform is restored, the platform syncs up offline data and updates it for consumption in the cloud.
In the event that the device never returns to sync with the platform (can happen when device is lost or app is uninstalled), the device status will remain disconnected.
Impact: Business intends to track this device and the device has lost connection with the HyperTrack platform. Reviewing and deleting devices that are disconnected for an extended period is recommended.To understand how tracking status is defined and used in HyperTrack API, please refer to the following: