Track app users

HyperTrack aims to bring in adequate level of transparency to businesses, that operate in a field. This generally varies in detail but even in the most basic case operations manager should be able instantly get access to his field ops location, both current and any point in history. This guide focuses on achieving that goal.

Introduction

We use mobile devices (phones and tablets) as a source of location data. Since privacy nowadays is an important aspect of any business, it's important to emphasize that tracking should only happen during the working hours. Breaking this rule won't only expose your business to various compliance risks but can cause in silent user resistance to the whole project, driven by negative attitude to surveillance technologies focused to your solution.

Any integration roughly consist from three components: 1. Phones that generate the data. We use mobile devices (both Android and iOS) as a source of data. We provide a ready to use Visits App as well as SDK that can be integrated into an existing app. 2. Data aggregation and transformation. All that is done by HyperTrack. 3. Data delivery to ops manager (consumption). We provide various ways of consuming data from real-time raw data stream via webhooks to ready-to-use dashboards with periodic reports. Although tracking hardware is located on mobile phones, HyperTrack provides you with infrastructure that allows you start and stop tracking using REST API. In fact, this is the recommended way of launching and terminating tracking, as it gives you maximum level of control. Although you can use mobile SDK to achieve the same, the mobile application's logic is less controlled, than your backend environment, and relies on expectation of the user performing (or not performing) some action. So putting start/stop logic inside app code could lead to unintended tracking after hours due to that code path not being executed, that expose business to unintended risks.

With platform APIs as a primary source of device state management you should also pay attention to s.c. tracking rate which is the ratio of number of devices being actually tracked to the number of devices you were intended to track. As it was already mentioned above, tracking hardware is located on users phone, so customers still have a possibility to resist tracking via mechanisms of permissions management, disabling geopositioning hardware or software and alike. For each of the devices that was intended to be tracked, but we don't have location data we provide the reason, why it wasn't tracked.

Setup the SDK

Configure push notifications

We use silent push notifications as transport for the server to device communication. They're called content updated messages on iOS and data messages on Android, but works exactly the same: commands from the backend are passed to the mobile application via push notifications service. If you haven't had them enabled yet, please use the guide for the appropriate platform iOS or Android. Once the application part of the integration is done, you also need to add push notifications service credentials to your dashboard's setup page under Server to Device communication section. On iOS, you also need to perform additional steps, in order to wire up HyperTrack SDK with the push notifications framework.

iOS additional steps to enable remote notifications
Enable remote notifications in the app

In the app capabilities, ensure that remote notifications inside background modes is enabled.

Remote Notifications in Xcode

In the same tab, ensure that push notifications is enabled.

Push Notifications in Xcode

important

Silent push notifications will work even if users deny notification permissions in the app. The only way to disable them is to disable "Background App Refresh" in Settings or to turn on "Low Battery Mode".

Registering and receiving notifications

The following changes inside AppDelegate will register the SDK for push notifications and route HyperTrack notifications to the SDK.

Register for notifications

Inside didFinishLaunchingWithOptions, use the SDK method to register for notifications.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
HyperTrack.registerForRemoteNotifications()
return true
}
Register device token

Inside and didRegisterForRemoteNotificationsWithDeviceToken and didFailToRegisterForRemoteNotificationsWithError methods, add the relevant lines so that HyperTrack can register the device token.

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
HyperTrack.didRegisterForRemoteNotificationsWithDeviceToken(deviceToken)
}
func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
HyperTrack.didFailToRegisterForRemoteNotificationsWithError(error)
}
Receive notifications

Inside the didReceiveRemoteNotification method, add the HyperTrack receiver. This method parses only the notifications sent from HyperTrack.

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
HyperTrack.didReceiveRemoteNotification(userInfo, fetchCompletionHandler: completionHandler)
}

If you want to make sure to only pass HyperTrack notifications to the SDK, you can use the "hypertrack" key:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
if userInfo["hypertrack"] != nil {
// This is HyperTrack's notification
HyperTrack.didReceiveRemoteNotification(userInfo, fetchCompletionHandler: completionHandler)
} else {
// Handle your server's notification here
}
}

Setup and manage app users

Tracking business assets on the move requires identification of your app users and their physical devices. To achieve this goal, HyperTrack uses a unique, randomly generated device id in order to track the physical device your app is used on.

Location data generated by your app user is sent to HyperTrack platform and stored together with the unique device id which identifies your app user.

With this unique device id, HyperTrack gives you the power of its APIs to manage tracking of your business assets.

Once you integrated HyperTrack SDK into your app, from your app backend, you can use HyperTrack APIs with device id to start and stop tracking of your app user's device from your server, create and complete trips for your app users, create geofences and track their entries and exits for each physical device in realtime.

Understand Device ID

HyperTrack SDKs use random generated universally unique ids (UUIDs) that are stored in the device for future use once your SDK instance is initialized.

This device id is different for each physical device and is typically not persistent across uninstalls or re-installs of your app to ensure user's privacy.

Get and store Device ID

Once you integrate HyperTrack SDK in your app, you may get device id from your SDK instance.

In your app integration code, retrieve an SDK instance, when you wish to use SDK, by passing your publishable key from the setup page. Once you get an SDK instance, you may get device id as shown in code samples below for iOS and Android HyperTrack SDK integration examples.

val publishableKey = "your-publishable-key-here"
val sdkInstance = HyperTrack.getInstance(this, publishableKey)
// Your HyperTrack device id
val deviceId = sdkInstance.deviceID

Once you obtained a device id as shown in the examples above, you should store this device identifer together with your app user identity in your own data store for future usage with HyperTrack API. You will need to map your own app user identity to HyperTrack device id to manage tracking of your app user's devices.

When you dispatch someone for a gig job, tracking a mobile worker via your app, create an order for an on-demand delivery, or tracking a driver via a logistics app, you need to use HyperTrack device id to track location of physical devices used by your app users.

Understand device name and metadata

While HyperTrack uses a device id to track your app with HyperTrack SDK integration, convenience methods are provided to help set device name and metadata as an option to help display, sort, manage, and organize large fleets of devices in your account.

While HyperTrack device id is a unique identifier for all of your app user's devices in your HyperTrack account, HyperTrack APIs do not enforce uniqueness constraints on name and metadata.

See an example of device name and metadata that are set for three devices with device_id such as 7BEEABA4-4890-4AFA-916A-AA80FE659C5A and D5FCE235-4650-476F-9871-59AC7F9BE48B.

{ "device_id": "D5FCE235-4650-476F-9871-59AC7F9BE48B",
"name": "Kishan E",
"metadata": {
"vehicle_type": "scooter",
"group_id": 1
}
},
{ "device_id": "7BEEABA4-4890-4AFA-916A-AA80FE659C5A",
"name": "Alex K",
"metadata": {
"vehicle_type": "bike",
"group_id": 2
}
}

Devices name is used to conveniently show your app user's device, filter, and search for it in HypeTrack dashboard.

Your device metadata can be any valid JSON string and be used for filtering purposes to help identify a group of devices that share common or distinct properties of your choosing. For example, please review how device metadata can be used to create hierarchical embedded views.

Once you set a name for your physical device, it will be used to display your app user's device in your account HyperTrack dashboard.

If you do not set a name for your app user's device, alternatively, its device id will be shown. As mentioned earlier, there is no requirement for device names to be unique. For example, if your app has a name for an app user in your user management system, you may as well use it to set the device name as well for the HyperTrack device id to create a consistent user experience for your customers.

As a developer, you have an option of being able to set and change device name and metadata via the SDK in your mobile app as well as via Devices API from your app server backend.

To get a hands-on experience of setting and changing device name and metadata without writing a single line of code, please visit HyperTrack Playground. Once you select your app user's device in the list inside Playground, you will be presented with device name and metadata entry forms. As you change them, please observe how your changes get reflected in HyperTrack Dashboard.

Set using mobile SDK

When you develop your app with HyperTrack location tracking, you may already have a requirement or preference to set your app user's device name and/or metadata once the app user started and logged into your app.

In this case, inside your mobile app, you may be able to set device name and metadata as shown below.

// Set device name as in the example above
sdkInstance.setDeviceName("Kishan E")
// create new metadata map
Map<String,Object> myMetadata = new HashMap<>();
// add metadata as in the example above
myMetadata.put("vehicle_type", "scooter");
myMetadata.put("group_id", 1);
sdkInstance.setDeviceMetadata(myMetadata);

Set using Devices API

In addition to SDK methods above, HyperTrack provides you Devices API where you may be able to set device name and/or metadata.

You may need this when you have a business workflow that requires updating your app user's device name, or a change for your app user which may have to be reflected in your metadata.

For example, you want to restrict viewing of an operations team to their manager which, in turn, can be done by specifying an attribute to which your app users belong to, such as group_id from the example above.

Once you have used Devices API to set device name or device metadata, you can no longer use SDK methods to change them.
// Use Node.js helper library to set device metadata
const accountId = "your_account_id"
const secretKey = "your_secret_key"
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey)
const deviceName = "Kishan E"
// Set name for the device
hypertrack.devices.changeName(deviceId, deviceName).then(() => {
// Name changed
}).catch(error => {
// Error handling
})
const metadata = {"vehicle_type": "scooter", group_id":1}
hypertrack.devices.patchMetadata(deviceId, metadata).then(() => {
// Metadata set
}).catch(error => {
// Error handling
})

Understand device status and live location

Get using Devices API

In your business workflow, you may need to be able to retrieve device data and tracking status for a device id registered under your HyperTrack account. Conveniently, HyperTrack Devices API provides you an option to do so.

With this Devices API GET call,

GET /devices/{device_id}

with an example response as shown:

{
"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": { ... }
}

This response delivers your app user's device most recently known recorded location, its current device status, provides you a publicly shareable share_url for the device location as well as embeddable embed_url that you can use to create a single device view dashboard. Lastly, you can see device's name, metadata, as well as device_info field as shown above along with it's registration UTC timestamp in registered_at.

Additionally, HyperTrack Devices API provides you ability to query all registered devices in your account.

The devices API above requires a device_id But for example, you want to retrieve device data and status by their grouping. For example, you want to find devices that show vehicle_type as scooter per example above.

HyperTrack Devices API provides you an option to use a metadata_filter query parameter to help you conveniently retrieve this data:

GET /devices?metadata_filter=<url_encoded_json>

with an example JSON as shown:

{
"vehicle_type": "scooter"
}

Once you perform URL encoding for the string above, you Devices GET API call will be executed as follows:

GET /devices?metadata_filter=%7B%27vehicle_type%27%3A+%27scooter%27%7D
important

Thus, this API call will only return entries that match this metadata. Note that the metadata filter will look for any matching subsets of JSON data that match correspoding keys and values you send in this API call.

Using device status

HyperTrack devices can be in one of the following state:

  • active: Device is tracking. activity value shows the current activity (drive, walk or stop)
  • inactive: Device is not tracking with known reasons
  • disconnected: HyperTrack lost connectivity with this device
Inactive devices

When a device cannot be tracked, it's in inactive state and HyperTrack gives you the reason why it can't be tracked.

User driven outage reasons

User drive outages are a result of specific user action. To mitigate these issues, reaching out to the app user is required.

reasonview display stringdescription
location_permissions_deniedLocation permission denieduser explicitly denied location permissions
motion_activity_permissions_deniedActivity permission denieduser explicitly denied motion permissions
location_services_disabledLocation service disableduser explicitly disables the location services
motion_activity_services_disabledActivity service disableduser explicitly disables the motion services
sdk_killed_by_userApp terminated by useruser kills the application running the SDK
sdk_killed_by_permissions_activityApp terminated by activity permission changeuser changed the motion/activity permission while the SDK was tracking the device
sdk_killed_by_permissions_locationApp terminated by location permission changeuser changed the location permission while the SDK was tracking the device
location_permission_asked_in_backgroundLocation permission asked in backgroundlocation permissions have not been granted because app was in the background; request will be made when the application is brought to the foreground
motion_activity_permission_asked_in_backgroundActivity permission asked in backgroundmotion/activity permissions have not been granted because app was in the background; request will be made when the application is brought to the foreground
location_permission_restrictedLocation permission is restrictedlocation permission is restricted through the phone settings, device administrator, or parental control
motion_permission_restrictedActivity permission restrictedmotion/activity permission is restricted through the phone settings
motion_activity_permission_not_determinedActivity permission not detectedSDK asks the user for motion/activity permissions, after either a permissions reset or because the user chose the "Ask Next Time" option
location_permission_not_determinedLocation permission not detectedSDK asks the user for location permissions, after either a permissions reset or because the user chose the "Ask Next Time" option
location_permission_impreciseLocation permission impreciseStarting with iOS 14, app user can choose to reduce location accuracy information
System driven outage reasons

These outages are due to operating system or device related issues.

reasonview display stringdescription
tracking_service_terminatedTracking service terminatedHypertrack SDK is tracking the device, but it is killed during this process
location_unavailableLocation unavailableSDK could not get fresh location data
location_unavailable_battery_saverLocation unavailable - Battery saver onlocation updates are disabled by OS because the battery saver mode is enabled and the screen is turned off
sdk_killed_low_memoryApp terminated - Low MemoryOS kills the host application to free up memory on the device
sdk_killed_by_app_updateApp terminated by app updateapp was killed by a force update
sdk_killed_by_os_updateApp terminated by OS updateapp was killed because the device rebooted due to an OS update
sdk_killed_by_os_rebootApp terminated by OS rebootapp was killed because the OS was rebooted
sdk_killed_by_low_powerApp terminated - Low Powerbattery on the device died due to low charge
storage_unavailableApp terminated - Low device storageno storage space left in the device; blocks the SDK from storing data and leads to data loss
network_limit_reachedNetwork limit reachedSDK stops collecting events because network outage was longer than 12 hours

Understand app updates, uninstalls and reinstalls

As your user performs an app update with your next release, HyperTrack device_id does not change. HyperTrack keeps track of your app user's device id in this case, as well as updating relevant fields inside device info returned to you by Devices API GET call.

Once your app user uninstalls your app, mobile OS requires that all data associated with your app are removed to protect user's privacy. If your app user's device was actively tracking at the time, HyperTrack will detect and mark it's tracking status as disconnected.

In case if your app user uninstalls and subsequently installs your app again, the new installation will result in creation of a new device id even though it's the same physical device that belongs to your app user. Depending on your app workflow, if you expect a single physical device for each user, you may take advantage of either device name and/or metadata to determine a new installation and update your data store accordingly to keep track of new device id in your system.

Manage app user turnover

Sometimes you may have a case where an app user leaves your organization or you want to permanently stop this app user being tracked.

In order to remove the physical device associated with this app user, you may use delete API method to delete this device and stop tracking it permanently. At the same time, after deleting this device id, HyperTrack will retain and provide tracking history of the device in dashboard views as well via API.

The device will stop tracking further and you will be unable to start tracking the same device ID again.

important

Once a new monthly billing cycle begins, you will not be charged for this device moving forward. Devices are billable only if they were active for any duration during the month.

Please see code snippets explaining device deletion below.

// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.delete(deviceId).then(() => {
// Device deleted
}).catch(error => {
// Error handling
})
note

To get a deleted device back into your account and start tracking, please check Devices Undelete API documentation.

Manage permissions

iOS and modern Android require applications, that access sensitive data, request user's permission in an interactive way.

Permissions management in the app

SDK requires that user should grant location and activity (motion) data access in an intractive way. Since tracking can only be started if permissions are granted, your app needs to receive them in advance. OS guidelines also recommend to show quick rational explaining why the location data access is required followed by permissions request screen. You can use SDK helper methods to request the permissions:

sdkInstance.requestPermissionsIfNeeded()

Mostly that will pop-up the permission dialogs series that customer should accept. However, there's specific issue that appears on Android 11+. Background location access permission, that is required to start tracking with device's screen being turned off, cannot be asked directly, but user needs to manually flip that switch in Settings widget. There's also bunch of other permissions, that aren't requested interactively, but you don't need to do anything as SDK takes care of them.

Custom ROMs

Aside from regular Android permissions some manufacturers tweak Android with the additional once, aiming to alter recommended power management behavior with stricter and savvy one. The result is that they suspend all the background apps and processes without special whitelisting flag so you'd better ask user to add your app to the list of power optimization exceptions with code like:

try {
val intent = Intent().also {
when (Build.MANUFACTURER.toLowerCase(Locale.ROOT)) {
"xiaomi" -> it.component = ComponentName("com.miui.securitycenter", "com.miui.permcenter.autostart.AutoStartManagementActivity")
"oppo" -> it.component = ComponentName("com.coloros.safecenter", "com.coloros.safecenter.permission.startup.StartupAppListActivity")
"vivo" -> it.component = ComponentName("com.vivo.permissionmanager", "com.vivo.permissionmanager.activity.BgStartUpManagerActivity")
}
}
if (context.packageManager.queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY).isNotEmpty()) {
context.startActivity(intent)
}
} catch (e: Exception) {
Crashlytics.logException(e)
}

Another approach is to use a third-party library like Autostarter or similar.

App user messaging about lack of permissions

Modern OS allow user to change permission status at any time, so aside from the intitial flow, described earlier, you should implement some variant of missing permission resolution strategy. Possible approach is to show visual notifications with resolution hints. This require deep understanding of os permission model. Good iOS permissions guide can be found here and we also have a story to get the intuition behind Android permissions model.

Control app user tracking with API

Modern applications have most of their business logic transactions running on the backend, so it's convenient to control tracking state from the backend too, disregards whether the trigger comes from the client application or determined by other factors (shifts schedule and alike). Although it adds some complexity to the integration process, as you need to setup the push notifications, the hidden win here is that you can avoid transactions distributed between backend and client and keep the code simpler and bug-free.

Tracking with Device API

In order to start tracking you need to execute POST request to device's REST API endpoint which looks like https://v3.api.hypertrack.com/devices/{device_id}/start where device_id is the UUID string that you got from the sdk earlier.

curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}/start

Our REST API uses Basic authentication scheme with credentials that are displayed in Dahsboard's Setup section under API header (we use AccountId term for the user-id and SecretKey for the password).

The expected response is 200 status code with {"message": "Device tracking started"} body.

Once you've done with tracking you can use stop endpoint to terminate the tracking session.

curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}/stop

Tracking with Trips API

Although start and stop endpoints do their job okay, some businesses might prefer to track using trips API. If a word like order or task appears frequently in your business logic, that's a sign that you'll have additional complexity trying to map those orders to shifts and vise versa, while a trip could easily represent order's location data. Creating a trip for the device automatically starts tracking and trips completion stops it if no other active trips are present. Additional benefits include shareable tracking link, destination arrival estimate and real-time delay notifications. To create a trip execute request like in the example below:

payload='{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
}
}
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/ \
-H 'Content-Type: application/json' \
-d $payload

00112233-4455-6677-8899-AABBCCDDEEFF here is device id, -122.398096, 37.793038 are the trip destination's longitude and lattitude respectively, AccountId and SecretKey are auth parameters (look for them in Dashboard's Setup page under APIs section). Successfull response has 201 status code and json, that contains trip serialized in JSON.

{
"completed_at": null,
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944
]
},
"radius": 30,
"scheduled_at": null,
"arrived_at": null,
"exited_at": null
},
"estimate": {
"arrive_at": "2019-05-03T06:25:51.238000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "Mannat Manzil #48,2nd cross, 3rd Main,Amrita Nagar, 3rd Phase, Choodasandra, Bengaluru, Karnataka 560035, India",
"end_place": "4, Muniswamy Garden, A - Block, Bengaluru, Karnataka 560025, India",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}

estimate field is only present if you set the destination (its optional) and we know device's location. Otherwise the estimate is computed once device will start tracking.

Tracking with SDK

Although it's recommended to use our REST APIs to control the tracking, you can achieve the same result using mobile SDK interface.

val publishableKey = "your-publishable-key-here"
val sdkInstance = HyperTrack.getInstance(this, publishableKey)
sdkInstance.start()

The invocation above will start the tracking and either provides device's location or a reason, why the device can't be tracked (e.g. if required permissions are missing etc.). In order to stop tracking, use the below command:

sdkInstance.stop()

Track app users with API, webhooks, and embeddable custom tracking views

Device API

To get the status of any device you can use the following query:

curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/00112233-4455-6677-8899-AABBCCDDEEFF

The response is 200 status code with body like follows:

{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
// Last known location for the device
"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" // could also be `inactive` or `disconnected`
},
"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", // the name you've assigned from the mobile SDK or via API
"os_version": "12.4"
},
"registered_at": "2019-07-10T01:38:45.610000Z",
"metadata": { ... } // key-value datastructure that you can assign for device for grouping or tagging
}

Receive webhooks notifications about user device status

Although you can get current status and location for all devices using our REST API that way of getting the data mostly feat into report-like flow. In case of building the real-time system, to keep your data up to date it's better use reactive style when you receive a stream of data updates. We deliver those updates via webhooks. The setup is pretty straightforward, you should go to Dashboards Setup page and add your endpoint URL under Webhooks section. Once finished, the endpoint will start receiving HTTP POST requests each time the status of any device in your account changes. You can find different payload examples in API Reference, but all of those events has structure like below:

[{
"created_at": "2019-02-27T22:50:29.000000Z", // the time, when the appropriate event was created in HyperTrack platform
"data": { ... },
"location": { ... },
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-02-27T22:50:24.000000Z", // the time when the original event on device was recorded
"type": "",
"version": "2.0.0"
}]

By default, we do not deliver location events, as raw location data is mostly unuseful, but creates high load on infrastructure. You can get all the location history upon receiving the trip completion or tracking stop event in one response instead of processing hundreds of requests. Check out the webhooks guide for more.

Embeddable custom tracking views

Device status and trip responses payload contains field embed_url. This is ready to use webview, that you can link or use in iframe to visualize location data in your own dashboard. devices-embeddable-view Its appearance could be modified via URL parameters e.g., adding &icon=car will make that green dot turn into a vehicle image. Also we provide a url for the list of devices view: devices-list-view You can tweak it as well by providing url parameters. Common scenario is to display only devices, that belong to the specific division, that is specified in device's metadata. Check out this guide for details.

Understand and Improve tracking rates for your fleet

As was already mentioned, tracking rate is the ratio of the number of devices that were tracked to the number of those, that were intended to track. Because of users, that declined permissions, disabled geolocation services on their phones, or just run out of battery, that percentage rarely has 100% value. To facilitate the basic pattern of observe-identify-improve we provide you with Scoreboard and Insights views and status updates webhooks.

Get tracking rates from Scoreboard and Insights

Scoreboard

Scoreboard provides an overall view of how operations are progressing with the ability to review historic data for comparison. Visualizations provide a clear indication of trends based on key metrics while focusing on a current day’s status. scoreboard Use it to evaluate the impact of integration changes as well as observe trends among your workforce. Check out the guide for the details.

Insights

Another way of observing the data is to use Insights. Use vast amount of sorting and filtering patterns to observe the workforce performance and easily export the data for further analysis.


Insights


Check out Scoreboard and Insights guide for details.

Improve

Once you've identified the most promising path to improve the tracking rate, you can use the appropriate webhook to address the issue. E.g., if tracking doesn't happen due to disabled geolocation you can display user in-app visual notification, that he needs to enable it to proceed and block particular flows until done.