Track devices with the API

The quickest and most popular way to use HyperTrack is to track devices with the API. This guide will show you how to:

Start and stop tracking

HyperTrack Devices APIs give you the power to control tracking on all devices using apps with HyperTrack SDKs pointing to your account. As you perform Device API calls from your servers, you are can remotely start and stop tracking devices with apps running HyperTrack SDK integration.

In order to perform API calls from your server, you need to first obtain AccountId and Secret Key.

Start tracking

For example, if you would like to start tracking when your app at the start of working hours, or work assignment, or app login, you may want to call Devices API call to start tracking for your device. In order to start tracking on your device, you should be able to obtain, store, and reference your users' HyperTrack device_id when calling this API from your server.

To start tracking your device, you may make a Devices API call as shown below.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to start tracking
hypertrack.devices
.startTracking(deviceId)
.then(() => {
// Tracking started
})
.catch(error => {
// Error handling
});

Stop tracking

In order to protect the privacy of workers using your app, you are strongly encouraged to stop tracking when the user either logs out, ends working hours, completes all assigned work, etc. To do so, you may make a Devices API stop tracking call. Once you issue this call from the server, HyperTrack Device API will remotely stop tracking for your device with device_id.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to stop tracking
hypertrack.devices
.stopTracking(deviceId)
.then(() => {
// Tracking started
})
.catch(error => {
// Error handling
});
note

Team HyperTrack is working on a way to specify private hours when tracking is stopped, and automatically resumes thereafter.

Set custom markers (OPTIONAL)

Use this when you want to add an action performed by the app user in the location timeline of the user.

SDK: Create custom trip marker

// create new marker payload
Map<String,Object> payload = new HashMap<>();
// add event details
payload.put("custom keys", "custom values");
HyperTrack.tripMarker(payload);

To attach contextual data to devices, HyperTrack provides the ability to set custom markers.

To set a custom marker, you need to use the HyperTrack mobile SDK (iOS, Android). There is currently no option to use HyperTrack APIs to set trip markers.

Submitted markers are part of the views and are available in the device summary.

Get the device ID(s) of the user(s) you want to track

The SDK should have added a device name and metadata upon initialization in the user's app: (iOS, Android).

If you have already sent and stored this information to your servers, get the user's device ID from your application database. Else, get the list of registered devices from the Devices API and use the device name or metadata to identify the user(s) you want to track.

HyperTrack views and developer integrations rely on the device names and metadata for filtering, selection, and more. Customizing these device properties makes navigation and identification of users easier. Developers often add unique identifiers, grouping information, or annotations that are frequently accessed for devices.

Device name and custom metadata

{
"name": "Alex’s Phone",
"metadata": {
"customer_id": "ABC123"
}
}

By default, the property name is set to the name of the device as configured in the device settings. With the SDK, you can set and customize this name. Additionally, the Devices API provides you an ability to update device name and metadata via an HTTP PATCH.

note

The Devices API is authoritative when it comes to setting the device name and/or metadata. Once you have updated the device name by invoking the Devices API above, the HyperTrack mobile SDK will not be able to make subsequent changes to the device name. Similarly, if you update the device metadata via the Devices API call, the HyperTrack mobile SDK will not be able to make changes as well.

Stream events via webhooks

Use webhooks to ingest live location, activity, outage and other movement context of your devices from HyperTrack to your server end point. Works best when building live location experiences and applications on your server.

Webhooks setup

The HyperTrack dashboard allows you add your webhook URL on the Setup page.

setup screen

Just enter your webhook URL and click on "Add Webhook". The screen will ask you to verify your webhook URL to start receiving events. The verification is a one-time activation and described below.

verification pending

One-Time Activation

verification process

Webhook subscription request payload (text/plain)

{
"Type": "SubscriptionConfirmation",
"MessageId": "c0216cf3-8f2e-4aae-b678-ccf18a5cb63c",
"Token": "2336412f37fb687f5d51e6e241dbca52e99b",
"TopicArn": "arn:aws:sns:us-west-2:012432584802:location_b29fe",
"Message": "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:012432584802:location_b29fe.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
"SubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:012432584802:location_b29fe",
"Timestamp": "2019-06-11T13:36:08.195Z",
"SignatureVersion": "1",
"Signature": "kWr8Z1vgKrN+uS3sOUYTRHTSP3Jhd5cLLWbW9lkBQHgt7JWtAt",
"SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-69.pem"
}

As soon as your webhook status is set to ‘Pending verification’, you should notice a confirmation message (HTTPS POST) on your server. The message is coming from the AWS SNS Service HyperTrack is using to handle webhook subscription. The message is in JSON and looks like this:

You should implement your server to handle the subscription confirmation request. You can identify the message type by looking at the HTTPS POST request headers. The relevant header is x-amz-sns-message-type. For the confirmation message above it is set to SubscriptionConfirmation.

important

Please ensure to parse the POST body with the content type text/plain. All webhooks after the verification will have the x-amz-sns-message-type header set to Notification.

To complete the verification, you should read the value for SubscribeURL and visit the URL indicated. You can make an HTTP GET request to the URL either programmatically, by using a command-line tool (cURL), or using a web browser. The request will return an XML document.

Webhook subscription confirmation payload

<ConfirmSubscriptionResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
<ConfirmSubscriptionResult>
<SubscriptionArn>arn:aws:sns:us-west-2:012432584802:location_b29fe6c9-27ef-4551-b3ee-8bb3ec000a3b:658eb789-eb17-4694-9575-83b1591df841</SubscriptionArn>
</ConfirmSubscriptionResult>
<ResponseMetadata>
<RequestId>68f77c42-6e72-5e0e-a60a-293905d68d9a</RequestId>
</ResponseMetadata>
</ConfirmSubscriptionResponse>

The document returns the subscription ARN for the endpoint within the ConfirmSubscriptionResult element. Ensure to store the SubscriptionARN as a string for webhook signature verification (next chapter).

Your one-time verification is now complete and you should start receiving webhooks from HyperTrack. Your dashboard will confirm the completion of this process.

complete setup screen

Troubleshooting webhook integration

Please review common issues below for suggestions on how to resolve them.

Webhooks status is still "Pending verification"

In this case, HyperTrack was not able to send you a subscription confirmation request. In this case, there may be the following reasons for it to occur:

  • Your host server might not be reachable on the network. Please verify connectivity to your server. Once you confirmed that your server is operating normally, please resend verification by clicking on three dots on the webhook setup screen and and then clicking on Resend verification option.
  • Your host server may have been down while subscription confirmation requests were sent to you. We try to send these requests three times before giving up. As in above, you confirmed that your server is operating normally, please resend verification by clicking on three dots on the webhook setup screen and and then clicking on Resend verification option.
  • If you have tried all of the above, then please check if you have a full SSL certificate chain provided by your host server including all intermediate SSL certificates. Once you checked and confirmed that your host's SSL certificate is correctly installed, you may try to resend verification request again.
  • If you manually retrieve the subscription url from your server logs, please make sure to capture a full SubscribeURL string to perform a subscription request from your browser.

Webhooks not sending data to your server

  • To confirm if your webhook server is working as expected, you may send a test event by clicking on three dots on the webhook setup screen and and then clicking on Send test event option. You will receive a webhook test payload that will be like this:
[
{
"recorded_at": "2019-02-27T22:50:24.538000Z",
"data": {
"altitude": 495.2,
"bearing": 90,
"location": {
"coordinates": [
-6.2755,
57.6398983
],
"type": "Point"
},
"location_accuracy": 14.087,
"speed": 0
},
"device_id": "TEST_DEVICE_ID",
"type": "location",
"account_id": "0"
}
]
  • If you have not received the request, then you may want to verify if your server is reachable by making a POST request with a tool of your choice to your webhook server URL. Otherwise, your server will be receiving webhooks from HyperTrack once devices under your account generate location data.
note

You will likely not receive webhooks right away. We offer the capability to send test events (upon click on the three dots on the screen above). This will allow you to test your implementation.

Webhook payload content

The following Webhooks are posted.

Locations

Location time series data where each location in the stream includes coordinates and the optional fields speed, altitude, bearing, and accuracy when available.

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "location",
"data": {
"geometry": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"speed": 0.0,
"bearing": 313.94
},
"version": "2.0.0"
}

Location events are sent with a high frequency (~ 100x more than activity events).

  • Data: Current location of the device in GeoJSON format. Altitude, the optional third parameter in the coordinates array, is the current device elevation in meters, relative to the sea level on iOS and relative to the WGS 84 reference ellipsoid on Android.
  • Location Accuracy (Optional): The estimated horizontal accuracy of the location, radial, in meters. When the location identifies the center of a confidence circle, the accuracy defines the radius of the circle (in meters). For Android, there is a 68% probability that the true location is inside the circle.
  • Bearing (Optional): The horizontal direction of travel, measured in degrees and relative to true North. Degrees start at true North and continue clockwise around the compass (north is 0, east is 90, south is 180, west is 270 degrees).
  • Speed (Optional): Speed of travel in meters per second.

Device status

Device status changes. This includes a device becoming active, inactive/disconnected and activity transistions such as start of walk, drive, or stop

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "device_status",
"data": {
"value": "active",
"activity": "walk"
},
"location": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"version": "2.0.0"
}

Device status provides update about the device. The value can be active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status.

Mobile devices send health data through the Mobile SDKs. The data is showing tracking outages and resumptions. Health data is available for outage events when an outage affects location data. This data is sent with a low frequency (based on device activity).

When the device is active, we include the activity when available. Mobile phones use a variety of sensors combined with location data to intelligently identify phone users’ activity. Activity transitions are sent with a medium frequency (similar to summary events).

HyperTrack supports 3 types of activity transitions: walk, drive, and stop.

For your convenience, we provide you a set of free-to-use SVG icons to display activities in your application.

Battery

Battery status changes. Values include low, normal and charging

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "battery",
"data": {
"value": "low"
},
"location": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983 124]
},
"version": "2.0.0"
}

HyperTrack sends battery updates to indicate the battery health. These events include details on charge, discharge and low battery.

info

Battery updates can be combined with outages as a leading indicator for tracking outages.

Get live location from the API

Use the Devices API to get the live location and device status of one or more devices. Works best when building dispatch, assignment and routing applications, and require live location information on demand.

HTTP 200 - Single device payload

{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
},
"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
},
"views": {
"share_url":"https://trck.at/abcdef",
"embed_url":"https://embed.hypertrack.com/devices/00112233-4455-6677-8899-AABBCCDDEEFF?publishable_key=abc"
},
"battery": "normal",
"device_info": {
"timezone": "America/Los_Angeles",
"os_name": "iOS",
"device_brand": "Apple",
"sdk_version": "3.3.2",
"device_model": "iPhone X",
"network_operator": "T-Mobile",
"name": "Alex’s Phone",
"os_version": "12.4"
},
"registered_at": "2019-07-10T01:38:45.610000Z",
"metadata": { ... }
}

All tracked devices are available through the Devices API. Each device entity contains the following data:

  • Last known location
  • Device status, and activity or outage reason
  • Share and embed view URLs for the device
  • Battery level (one of normal, low, or charging)
  • Device info, including name, brand, model, OS, operator, timezone, and SDK version
  • Custom metadata sent by the SDK

The device_status object has properties that are conditional to device_status.value.

It can be one of the following: active, inactive or disconnected. See here for a detailed description.

Active

Active device status includes an activity

"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
}

The device is actively sending updates. In that case, the device_status.data object is provided with an activity property. It can be one of stop, walk, or drive.

note

Run and cycle activities are purposefully removed because fewer businesses cared about it, and inaccurate classification obfuscated walks and drives. We are working on adding public transit detection, including trains, ferries and buses.

Inactive

Inactive device status includes a reason

"device_status": {
"data": {
"recorded_at": "2019-09-03T16:39:35.326000Z",
"reason": "stopped_programmatically"
},
"value": "inactive"
}

The device is not sending location updates and in that case, the device_status.data object is contains reason property`. These reasons can be one of the following below:

  • location_permissions_denied
  • location_services_disabled
  • motion_activity_permissions_denied
  • motion_activity_services_disabled
  • motion_activity_services_unavailable
  • stopped_programmatically
  • tracking_service_terminated
  • unexpected

Disconnected

Disconnected device status does not have any data

"device_status": {
"data": {},
"value": "disconnected"
}

Connection with the device was lost unexpectedly (no data received for over an hour). In that case, the device_status.data object is empty.

tip

If you would like to receive device status updates as they come in, it is recommended to use device status webhooks. This enables reacting to tracking outages and resumptions as they happen.

Battery status property

"battery": "normal"

Device objects contain a battery property to indicate the state of the device battery. The property can take one of the following values: low, normal, or charging

tip

If you would like to receive battery state updates as they come in, it is recommended to use battery updates webhooks. This enables reacting to low battery risks as they happen.

Device location payload

"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
}

Use the location object to display the location of a device on a map. It is important to understand the GeoJSON format to handle the data correctly:

  • Type can only be "Point" in this scenario
  • Coordinates is an array of 2-3 values (the last being optional) with the following format: [longitude, latitude, altitude]

The accuracy value is often used to draw a "halo effect" around the location dot with the accuracy (in meters) value being the radius of the surrounding ring. In addition, bearing (in degrees starting at due north) is used to draw a directional indicator at the location dot.

location

View devices on the map

Go to Views on your HyperTrack dashboard to map all devices that you intend to track.

  • Clustered live location of all devices right now
  • Day-wise list of all devices you intend to track, classified as active, inactive or disconnected
  • Location polyline and movement timeline of each device for the selected day
  • Aggregate durations, steps and distances of stops, walks and drives
  • Hierarchical views organized and filtered by metadata

Map view of all devices

Map View
  • The default view shows a map with a list of all devices you intended to track today
  • User may select the day and timezone to view devices for
  • Devices are grouped by device status
  • User may search devices by name or metadata
  • Each device shows associated metadata and a status bar with split of stop, walk, drive, inactive and disconnected durations
  • Every device that tracked location(s) that day is classified as active for that day
  • Devices that were inactive all day have an associated reason and the last updated location timestamp
  • Devices that were disconneced all day show the last updated location timestamp
  • Clicking on a device will show the day's movement timeline on the map
  • User may popout the device history in a new browser window if you prefer

Day and timezone select

calendar select

Users can select the day and timezone for which they want to view the list of devices on a map, and drill down into individual devices and their histories.

Device status and metadata device status

Devices in the list show a status bar and metadata for each device. For selected day, the status bar indicates the duration of stop, walk, drive, inactive and disconnected for the device. Metadata shows the values set in the device metadata JSON, and shows the corresponding keys on hover.

Live location of a device

live location view

The view for today shows live location of devices on the map with last known locations. Live locations automatically update in the view as the device moves. Hovering on live location opens a card with the following information:

  • Device status: active, inactive or disconnected. Read more here.
  • Activity: stop, walk or drive
  • Recorded: Timestamp of the location as recorded by the OS
  • Altitude: Altitide of the device at that location
  • Bearing: Bearing of the device at that location
  • Speed: Speed of device at that location
  • Location: Latitude, Longitude
  • Accuracy: Accuracy of the location

There are additional visual elements to make the live location of other devices come alive in a way that is consistent with on-device views of location in popular mapping apps.

  • Live location pulsates if recorded under a minute ago
  • Live location shows bearing when the device is moving
  • The halo around the live location dot indicates accuracy

Device timeline

device timeline

Clicking a device in the list or clicking the dot on the map shows the device timeline.

  • Location polyline with replay to drill down where the device was at what point in time
  • Movement timeline card organized by activity and outages
  • Addresses for stops, distances for drives, and steps for walks
  • Option to view or hide the device info and metadata
  • If selected day is today and the device is active, ongoing activity, last updated and speed become visible

Device info

device info card

Selecting a device gives you the option to look at device info, including:

  • Brand: Name of the device producer
  • Model: Product name of the device
  • Network: Network provider in use
  • Timezone: Timezone set on the device
  • OS: Operating system and version on the device
  • App package name: Package name of the application that HyperTrack is integrated into
  • App version: Version of the app that is using the HyperTrack SDK
  • SDK version: Version of the HyperTrack SDK used in the app
  • Created at: Date and time when the device was added to HyperTrack systems
  • Play services: Version of Play Services running on the Android device. Not visible for iOS devices.
note

You can see all HyperTrack SDK versions here: Android, iOS, and React Native.

Hierarchical views

HyperTrack automatically organizes devices in a hierarchy using device metadata set through the SDK or API. Each level in the hierarchy has a unique view with its own URL that may be embedded in your operations dashboard with restricted access.

Setting device metadata

[
{ "device_id": "1",
"metadata": {
"person_name": "Alex",
"vehicle_type": "bike",
"group_id": 3
}
},
{ "device_id": "2",
"metadata": {
"person_name": "Kishan",
"vehicle_type": "scooter",
"group_id": 1
}
},
{ "device_id": "3",
"metadata": {
"person_name": "Kaitlin",
"vehicle_type": "scooter",
"group_id": 3
}
},
...
]

Device metadata can be used to create restricted views for subsets of your tracked devices.

Device metadata can be set via two options:

  • By invoking methods in SDK. To learn more about how to set metadata via our SDKs, please read this guide for iOS or Android.
  • By using Devices API. Please see Device PATCH API that also allows to set or change name as well as metadata.

With device metadata in mind, you may be able to quickly create and deliver customized embeddable dashboards for operations managers and their teams restricted by metadata attributes that are relevant only to their teams and their devices under your HyperTrack account.

Hierarchical organization of metadata

If you have metadata attached to your devices, you will see the hierarchical device management icon in the dashboard, on the right, below the calendar and timezone selector.

Device Management

Initial view

Dashboard View Selection

By default, the view shows all of devices that are intended to be tracked today. If you set name and metadata for your devices, you will see name and metadata highlighted in green background color for each device entry in the left column. The map on the right will load the entire area for all devices under your account with a known last recorded location for the day. You may select date and timezone for which you wish to see devices that you intended to track.

Selecting view from hierarchy

Upon selecting hierarchical view icon, you will see that the hierarchical view is laid out automatically based on the metadata you create and assign to your devices. The map view on the right remains unchanged while the hierarchical device management icon turns blue.

View after selecting metadata and resetting the view

Once a selection is picked as shown in the image below, the view for the map on the right will be restricted only to devices that are grouped under this metadata key.

In order to go back to the previous unfiltered hierarchical view, clicking on x next to a chosen metadata value above will allow to go back to the original hierarchical dashboard view.

Selection toggle

If you select a metadata key and want to go back to the standard device list column view while preserving the metadata selection, you can click on the hierarchical device management icon. The icon will turn back to black and you will see the following as shown in the screenshot below:

In order to go back to the previous unfiltered device list column view, clicking on x next to a previously selected metadata value will allow to reset back to the original view.

## Coding view instructions
const baseUrl = "https://embed.hypertrack.com/devices"
const publishableKey = "xyz"
const metadataObject = {
vehicle_type: "scooter"
}
const metadataFilter = JSON.stringify(metadataObject)
## Embeddable widget for Get Devices Status by metadata
<iframe width="400px" height="400px" src=`{baseUrl}?metadata_filter={metadataFilter}&publishable_key={publishableKey}` />

Metadata filter URL encoding

As you navigate hierarchical views, you will notice that the URL contains metadata_selection parameter that contains your current selection. For example:

https://embed.hypertrack.com/devices?publishable_key=<your_publishable_key>&metadata_selection=Area__West+Delhi

Only valid JSON strings can be passed to the URL, and your objects must have a max nesting depth of 1. While testing, you can use this linter to validate JSON.

Your browser will most likely encode { } and : special characters, but when distributing embed URLs with a metadata_selection, be sure to encode your link. To read more about URL encoding, please read this guide.

Embed views in your dashboard

Embed views require the HyperTrack publishable key. Get your publishable key from the Setup page on your HyperTrack dashboard.

Aggregate views

Aggregate View

The browser URL for aggregate views in the dashboard are in the form:

https://dashboard.hypertrack.com/devices?{var1}={foo}&{var2}={bar}

The corresponding embed URL would be:

https://embed.hypertrack.com/devices?publishable_key={publishable_key}&{var1}={foo}&{var2}={bar}

Single device view

Single Device View

The browser URL for single device views in the dashboard are in the form:

https://dashboard.hypertrack.com/devices/{deviceID}?
{var1}={foo}&{var2}={bar}

The corresponding embed URL would be:

https://embed.hypertrack.com/devices/{deviceID}?publishable_key={publishable_key}&{var1}={foo}&{var2}={bar}

If you prefer, the Devices API returns embed_url for single device views that you may directly use.

Inline Frames

Embeddable views are implemented with HTML inline frames and require JavaScript to be executed successfully.

Iframes have important properties to be considered during implementation. Please read the following instructions carefully to ensure a seamless integration:

  • Iframe size: By default, Iframes are sized with 200 pixels height and 300 pixels width. It is recommended to implement responsiveness using CSS. Here is a sample implementation
  • Responsive views: All embeddable views are responsive and the mobile views will be displayed when the Iframe size is below 500 pixels
  • Security: When you activate the sandbox property for this Iframe, please include allow-scripts allow-same-origin to ensure successful execution of the JavaScript present in the Views
  • Compatibility: Please review browser compatibility of IFrame properties you want to use
  • Loading times: In order to improve speed, it's recommended to set the iframe's src attribute with JavaScript after the main content is done with loading

Delete devices

Use delete to delete devices and stop tracking them permanently. This is typically needed when the user has abandoned the app or left the business. Deleting a device will retain the tracking history of the device, and will be available through APIs and views. The device will stop tracking further and you will be unable to start tracking the same device ID again.