[DEPRECATED] Views SDK · HyperTrack Docs

The Views SDK is deprecated. For real-time updates, use Webhook Payloads instead.

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.

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. 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 (its current location is known and updated) and `false` otherwise
isDisconnected()	`boolean`	Returns `true` if device is disconnected (its 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`	Provides a more extended description of current state, e.g. whether it is driving, if active, etc.

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

DeviceViewUrls Properties

This object encapsulates resources that could be used to open a 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(uri)
    }

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 trip was 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`	Distance in meters
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

// 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 the below method:

Method	Parameter	Description
stopAllUpdates	`void`	Stops 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