API Reference

[DEPRECATED] Views SDK

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, and BATTERY_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 methodTypeDescription
getLatitude()doubleLatitude in degrees. Negatives are for southern hemisphere.
getLongitude()doubleLongitude in degrees. Negatives are for western hemisphere.
getAltitude()DoubleAltitude in m. Could be null, if value is not available.
getSpeed()DoubleSpeed in m/s. Could be null, if device is stationary
getBearing()DoubleBearing in degrees starting at due north and continuing clockwise around the compass
getAccuracy()DoubleHorizontal accuracy in m
getRecordedAt()StringISO 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")}")
}
MemberTypeDescription
createdAtStringISO 8601 date when the device status was created
isActive()booleanReturns true if device is active (it's current location is known and updated) and false otherwise
isDisconnected()booleanReturns true if device is disconnected (it's location wasn't updated for a while) and false otherwise
isInactive()booleanReturns true if tracking data is unavailable because of lack of permissions or tracking was stopped intentionally and false otherwise
statusintProperty 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}")
}
ParameterTypeDescription
appNameStringName of the hosting app
appVersionNumberStringVersion of the hosting app
appVersionStringStringVersion of the hosting app
deviceBrandStringThe device brand
deviceModelStringThe device model
nameStringThe name of the device
osNameStringThe operating system of the device, can be one of iOS or Android
osVersionStringThe version of the operating system on the device
sdkVersionStringThe 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)
    }
ParameterTypeDescription
embedUrlStringEmbeddable view URL
shareUrlStringSharable 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=""
}
MethodTypeDescription
getTripId()StringUnique identifier of the newly created trip, case sensitive
getStatus()StringTrip status, can be either active or completed
getStartedAt()StringTimestamp for trip starting time
getMetadata()StringMetadata provided at trip start
getSummary()StringTrip summary, only provided upon completion of a trip
getDestination()Trip.DestinationDestination of the trip, or null if trip has no destination
getEstimate()Trip.EstimateTrip summary, only provided for trips with status active
getCompletedAt()StringISO 8601 date when the trips was completed or null if it haven't been completed
Trip Estimate Properties
Estimate{
    arriveAt="",
    route=Route{ ... }
}
MethodTypeDescription
getArriveAt()StringTimestamp for estimated arrival
getRoute()Trip.RoutePlanned 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{ ... }
}
MethodTypeDescription
getDistance()IntegerTimestamp for estimated arrival
getDuration()IntegerDuration in seconds
getStartAddress()StringStreet address lookup for segment start
getEndAddress()StringStreet address lookup for segment end
getPoints()List of List of DoublePlanned 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"
}
MethodTypeDescription
getLatitude()DoubleLatitude coordinate of destination center point in degrees. Negatives are for southern hemisphere
getLongitude()DoubleLongitude coordinate of destination center point in degrees. Negatives are for western hemisphere
getRadius()IntegerRadius (in meters) of a circular trip destination
getScheduledAt()StringTimestamp 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:

MethodParameterDescription
onLocationUpdateReceivedLocationLocation update
onBatteryStateUpdateReceivedBatteryStateBattery update, can be one of BATTERY_CHARGING, BATTERY_LOW, and BATTERY_NORMAL
onStatusUpdateReceivedStatusUpdateStatus update
onTripUpdateReceivedTripTrip update
onErrorException, Device ID (String)Error with exception details and device ID
onCompletedDevice ID (String)Completion with Device ID

StatusUpdate Properties

StatusUpdate{
    value="WALK",
    hint="",
    recordedAt="2019-07-29T22:35:49.963554Z"
}
ParameterTypeDescription
valueStringHealth event type, can be one of DRIVE, STOP, or WALK
hintStringHealth hint. Additional information about the health event
recordedAtStringISO 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:

MethodParameterDescription
stopAllUpdatesvoidStops all the updates, that were scheduled for this SDK instance.
hypertrackView.stopAllUpdates();
Make sure you call this method once you're done in order to free up network resource handles. Otherwise, you might end up with leaked websockets.

iOS

iOS Views SDK Reference

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: