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 your app users
- Stream the tracked data via webhooks to your server
- Get live location and device status of your devices with the API
- View devices on the map in aggregate or individually, live or historically
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.
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.
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
Team HyperTrack is working on a way to specify private hours when tracking is stopped, and automatically resumes thereafter.
Get the device ID(s) of the user(s) you want to track
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.
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.
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.
The HyperTrack dashboard allows you add your webhook URL on the Setup page.
Just enter your webhook URL and click on
Add Webhook. Once entered, it will immediately change to
Receiving Events as shown below:
Troubleshooting webhook integration
Please review common issues below for suggestions on how to resolve them.
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:
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.
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.
Location time series data where each location in the stream includes coordinates and the optional fields speed, altitude, bearing, and accuracy when available.
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 changes. This includes a device becoming active, inactive/disconnected and activity transistions such as start of walk, drive, or stop
Device status provides update about the device. The value can be
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 status changes. Values include
HyperTrack sends battery updates to indicate the battery health. These events include details on charge, discharge and low battery.
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.
Getting a single device status and location
All tracked devices are available through the Devices API. Each device entity contains the following data:
- Last known location in
- Device status, and activity or outage reason in
- Share and embed view URLs for the device in
- Battery level (one of normal, low, or charging) in
- Device info, including name, brand, model, OS, operator, timezone, and SDK version in
- Custom metadata sent by the SDK or set by Devices API in
Understanding device status
device_status object has properties that are conditional to
It can be one of the following:
disconnected. See here for a detailed description.
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
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.
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:
Connection with the device was lost unexpectedly (no data received for over an hour). In that case, the
device_status.data object is empty.
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.
Device objects contain a
battery property to indicate the state of the device battery. The property can take one of the following values:
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.
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.
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
- 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
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
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
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
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
If you would like to get help with location tracking needs for your app users' devices, questions or comments on any of the topics above, please do not hesitate to contact us.