Setup and manage devices

Identify your app user devices

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.

Java/Android
Kotlin/Android
Swift/iOS
ObjectiveC/iOS

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.

Java/Android
Kotlin/Android
Swift/iOS
ObjectiveC/iOS

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

reason	view display string	description
`location_permissions_denied`	Location permission denied	user explicitly denied location permissions
`motion_activity_permissions_denied`	Activity permission denied	user explicitly denied motion permissions
`location_services_disabled`	Location service disabled	user explicitly disables the location services
`motion_activity_services_disabled`	Activity service disabled	user explicitly disables the motion services
`sdk_killed_by_user`	App terminated by user	user kills the application running the SDK
`sdk_killed_by_permissions_activity`	App terminated by activity permission change	user changed the motion/activity permission while the SDK was tracking the device
`sdk_killed_by_permissions_location`	App terminated by location permission change	user changed the location permission while the SDK was tracking the device
`location_permission_asked_in_background`	Location permission asked in background	location 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_background`	Activity permission asked in background	motion/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_restricted`	Location permission is restricted	location permission is restricted through the phone settings, device administrator, or parental control
`motion_permission_restricted`	Activity permission restricted	motion/activity permission is restricted through the phone settings
`motion_activity_permission_not_determined`	Activity permission not detected	SDK 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_determined`	Location permission not detected	SDK asks the user for location permissions, after either a permissions reset or because the user chose the "Ask Next Time" option

System driven outage reasons

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

reason	view display string	description
`tracking_service_terminated`	Tracking service terminated	Hypertrack SDK is tracking the device, but it is killed during this process
`location_unavailable`	Location unavailable	SDK could not get fresh location data
`location_unavailable_battery_saver`	Location unavailable - Battery saver on	location updates are disabled by OS because the battery saver mode is enabled and the screen is turned off
`sdk_killed_low_memory`	App terminated - Low Memory	OS kills the host application to free up memory on the device
`sdk_killed_by_app_update`	App terminated by app update	app was killed by a force update
`sdk_killed_by_os_update`	App terminated by OS update	app was killed because the device rebooted due to an OS update
`sdk_killed_by_os_reboot`	App terminated by OS reboot	app was killed because the OS was rebooted
`sdk_killed_by_low_power`	App terminated - Low Power	battery on the device died due to low charge
`storage_unavailable`	App terminated - Low device storage	no storage space left in the device; blocks the SDK from storing data and leads to data loss
`network_limit_reached`	Network limit reached	SDK 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.

Questions?

If you have urgent needs to help you with device management and location tracking, questions or comments on any of the topics above, please do not hesitate to contact us.

Identify your app user devices#

Understand Device ID#

Get and store Device ID#

Understand device name and metadata#

Set using mobile SDK#

Set using Devices API#

Understand device status and live location#

Get using Devices API#

important

Using device status#

Inactive devices#

User driven outage reasons#

System driven outage reasons#

Understand app updates, uninstalls and reinstalls#

Manage app user turnover#

important

note

Questions?#

Identify your app user devices

Understand Device ID

Get and store Device ID

Understand device name and metadata

Set using mobile SDK

Set using Devices API

Understand device status and live location

Get using Devices API

Using device status

Inactive devices

User driven outage reasons

System driven outage reasons

Understand app updates, uninstalls and reinstalls

Manage app user turnover

Questions?