Android

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.

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

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.

To understand how tracking status is defined and used in HyperTrack API, please refer to the following:

Review device status guide
GET Devices API reference