Build custom tracking views

Introduction

Businesses with teams tracking their assets on the move with HyperTrack need feature-rich map-enabled dashboards. Customers need to see live location of their service technicians or deliveries. Organizations building ops dashboards and customer centric delivery apps need to customize live tracking UIs to deliver experiences aligned with their use cases, workflow, and branding. Larger enterprises with multiple field teams want to create live tracking views restricted for each team. Moreover, developers want greater control of how to create compelling live tracking use cases for mobile and web without worrying about infrastructure and platform scale.

HyperTrack provides answers to all of the above.

Embed and customize web views for ops


As fleets of devices get tracked throughout the day, their operations managers need a tool to review their teams in their dashboards in both real-time and as well as with detailed historical reports. As the count of assets on the move grow larger, operation managers need scalable dashboards that provide a quick assessment of whereabouts of their teams, hierarchically grouped based on organizational criteria, such as, for example, team names, their categorization, or geographic regions. They need an ability to see where these devices are at any present moment, review their location history, activity, and tracking status now or in the past. Additionally, for reporting and auditing purposes, they need to export detailed device history data as well as aggregated reports organized per their preferences.

To achieve the ease of use in reviewing large counts of devices on the move, HyperTrack provides hierarchical view functionality which automatically organizes devices in 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.

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

Map View

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.

Calendar

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.

Device status and metadata

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

Live Location View

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

Viewing inactive device status

In the dashboard, you may observe inactive device status for your app user's devices in your account as shown in the image below.

Tracking Experience

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 Timeline

Enabling hierarchical views

To enable hierarchical view functionality, device metadata can be used to create restricted views for subsets of your tracked devices. HyperTrack uses this metadata to automatically arrange your devices. Additionally, metadata values can be utilized in creating restricted access dashboards.

Setting device metadata

Device metadata can be set via these three options:

  • By using PlayGround in the Dashboard. Please go here to explore setting device metadata without coding required.
  • 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.

See an example of device metadata for three devices with device_id such as 7BEEABA4-4890-4AFA-916A-AA80FE659C5A, D5FCE235-4650-476F-9871-59AC7F9BE48B, and 9F9DB479-E07B-4120-A27E-10964BC93FAB.

[
{ "device_id": "7BEEABA4-4890-4AFA-916A-AA80FE659C5A",
"metadata": {
"person_name": "Alex",
"vehicle_type": "bike",
"group_id": 3
}
},
{ "device_id": "D5FCE235-4650-476F-9871-59AC7F9BE48B",
"metadata": {
"person_name": "Kishan",
"vehicle_type": "scooter",
"group_id": 1
}
},
{ "device_id": "9F9DB479-E07B-4120-A27E-10964BC93FAB",
"metadata": {
"person_name": "Kaitlin",
"vehicle_type": "scooter",
"group_id": 3
}
}
]

With this example metadata structure above, you should be able to easily organize device views by person_name, vehicle_type, or group_id as explained in the next section below.

Hierarchical organization of metadata

If you have metadata attached to your devices, you will see the hierarchical device management icon, which is displayed as Device Management in the dashboard, on the top left, below the calendar and timezone selector as shown in the animated image below.

Dashboard View Selection

Initial view

By default, the view shows all of devices that are intended to be tracked today.

Dashboard View

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. Note that date and timezone selection is preserved as you navigate this dashboard.

Selecting view from hierarchy

Upon selecting hierarchical view icon Device Management, you will see that the embedded dashboard 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 Device Management turns blue.

By default, the view shows all of devices that are intended to be tracked today.

Dashboard View

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.

Dashboard View

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 Device Management . The icon will turn back to black and you will see that the hierarchical arrangement of devices in the left panel will get you to this view as shown below.

Dashboard View

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.

Inline Frames

In order to embed a dashboard into your web application, you need to create 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
## Coding view instructions
const baseUrl = "https://embed.hypertrack.com/devices"
## This is an example Publishable Key. Please replace it with the key you obtain from the Setup page.
const publishableKey = "rYd51pSVlZkhisUkcQCncp-c5CVxQeRi6s6bAWXM6T76bWwUlaUMlQ"
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}` />

Live trip view for operations dashboards using embed URL

As you have seen form the above, embed_url offers you an ability to create live trip tracking dashboard inside your application and is suited for operations manager usage.

It provides full trip history timeline since the starting point of the trip, an option for exporting a trip summary, with real-time tracking for active trips as well as completed trips full summary data.

trip embed view

The Trip payload includes the views object. Every trip gets assigned unique URLs to share and embed views of the trip. The URLs will remain active after trip completion. In that case, the views will show a summary of the trip, along with destination marker, start and complete locations, distance, duration, arrival time, device info, trip metadata, and the actual route taken to the destination.

While shareable views are accessible to everyone with the URL, embed views include the HyperTrack publishable key. The embed_URL includes the publishable key and is available to use as-is. That said, your publishable key is available in the Setup page of your HyperTrack dashboard.

The embed URL format is https://embed.hypertrack.com/trips/{trip_id}?publishable_key={publishable_key}

important

To identify a HyperTrack Trip with your application order, and destination with your order location, please use the metadata object for trip and destination respectively.

Single device view

In certain cases, you may decide to create a single device view experience in your dashboard as shown in the image below. The corresponding embed URL would be:

https://embed.hypertrack.com/devices/{deviceID}?publishable_key={publishable_key}
Single Device View

If you prefer, the Devices API returns embed_url for single device views that you may directly use. This approach allows you to create single device views in your operations dashboard dynamically as you get new devices registered under your HyperTrack account.

Inline frames

Please see how to use inline frames to create embeddable operations dashboards.

Embed restricted views for role based access

You may want to be able to restrict these dashboards only to devices that are relevant to operation managers responsible for their teams. In order to do this, you may leverage metadata filter URL encoding to embed these dashboards into your web application.

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

For example, with this code below:

https://embed.hypertrack.com/devices?publishable_key=...&metadata_selection=Zone__East

The restricted view will look like this image below with devices filtered for key Zone with value East in their metadata:

Restricted dashboard View

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.

## Coding view instructions
const baseUrl = "https://embed.hypertrack.com/devices"
## This is an example Publishable Key. Please replace it with the key you obtain from the Setup page.
const publishableKey = "rYd51pSVlZkhisUkcQCncp-c5CVxQeRi6s6bAWXM6T76bWwUlaUMlQ"
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}` />

Embed and customize web views for customer

Trips API generates a publicly visible share URL for customers. These URLs are unique for each trip.

Once the trip is created, you will get a response payload that contains views field that contains share_url and embed_url as shown in an example below.

HTTP 201 - New trip with destination
"views":{
"embed_url":"https://embed.hypertrack.com/trips/2a819f6a-5bee-4192-9077-24fc61503ae9?publishable_key=<your_publishable_key>",
"share_url":"https://trck.at/abcdef"
},
note

The URLs will remain active after trip completion.

Live trip view for customers using share URL

As mentioned above, HyperTrack API gives you an ability for you, as a developer, to create live, real-time, high fidelity, location sharing with your customer via share_url link.

Please see an image below for a mobile location sharing viewing experience in the web browser. Once your customer receives the link, the web browser will continually display and update the location of your app user's device as it moves towards the destination while ETA is updated live.

Tracking Experience

Share URL has the following structure: https://trck.at/{7_digit_tracking_id}.

This makes it a total of 23 characters, and therefore a friendly URL to share via text or other messengers. Share URLs stay accessible permanently and show trip summary after trip completion.

Customize tracking view

HyperTrack offers you options that allow you to create customizations for share URLs with ETA for your customers.

Customize with url query parameters

The share URL experience can be modified with the following query parameters appended to it:

  • layer
  • mini
  • icon
Layer query parameter

This parameter offers you options to customize map layer used to render the share URL experience. The layer parameter can have the following values:

  • base - default choice for the share URL
  • street - additional street detail is shown in the map
  • satellite - satellite view is used as shown in an example below

For example:

https://trck.at/abcdexyz?layer=street

To illustrate, please review corresponding images below for each of the layer option value usage.

Location Map   Location Map   Location Map

Icon query parameter

This parameter offers you options to customize how your tracked device appears on the map. The icon parameter can have the following values:

  • car
  • bus
https://trck.at/abcdexyz?icon=car

Location Map   Location Map

Mini query parameter
  • mini - this parameter allows to hide trip details used to show in the map as shown below.
https://trck.at/abcdexyz?mini=true

Location Map   Location Map

Customize with reserved trip metadata keys

In order to perform such customizations, you may use these reserved trip metadata keys to help define public share URL experience. Use Trips API with these reserved trip metadata keys when creating a trip.

  • ht_view_text_ongoing - defines a title of an ongoing delivery, for example, "Your order for xyz is on the way!"
  • ht_view_text_completed - defines a title for a delivery that was completed, for example, "Your order for xyz is delivered!”
  • ht_view_href_completed - provides an option to the customer to go back to the link which exposes order details in your delivery app
  • ht_view_href_text_completed - once this option is used, your completed trip will have a title defined by the value of this key
  • ht_view_hide_summary_completed - this option allows you to remove completed trip summary from the view which is included by default

For example the payload to create a trip with some of this metadata can be like this:

{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793013]
},
"metadata": {
"store_id": "STORE_A",
"delivery_id": "pkg_1AC",
"route_id": "rt_B12",
"transport_type": "scooter",
"ht_view_text_ongoing": "Your order for Philarmonic coffe cup is on the way!",
"ht_view_text_completed": "Your Philarmonic coffee cup order is delivered. Enjoy!",
"ht_view_href_completed": "yourphilarmoniccoffee.com/rate_order",
"ht_view_href_text_completed": "Enjoyed your Coffee!. Rate your order!",
"ht_view_hide_summary_completed": true
}
}
}'

Hide trip completion button

This parameter offers you option to hide trip completion button. Trip completion button is shown by default. The icon parameter can have the following value:

  • false
https://embed.hypertrack.com/trips/{trip_id}?publishable_key={publishable_key}&trip_complete=false

Stream data as callbacks to native apps

One of the more frequent use cases supported by HyperTrack is live location status streaming to your app user's mobile device.

For example, if you are developing a carpool app, you want to provide a native real-time view of a driver on the way to a pickup destination, with up-to-date location and status with ETA.

To help you build apps where native in-app real-time tracking experience is required, HyperTrack provides you Views SDKs for Android and iOS as building blocks. You can use these building blocks to create real-time location tracking experience in the map layer of your own choosing, with full control of UI/UX while HyperTrack provides you real-time location data updates and infrastructure. This way, you focus on creating compelling app experience without worrying about building location tracking infrastructure.

Views SDKs connect directly to HyperTrack cloud and provide you callbacks you can use in your app to stream real-time data for devices involved in your business workflow. Views SDKs stream devices' locations, status changes, as well as trip updates to your mobile app directly from HyperTrack platform.

important

HyperTrack Views SDK on both Android and iOS enable you to deliver real-time location tracking experience without you needing to set up your own servers.

HyperTrack does this directly for you by pushing live subscriptions to your app via Views SDK in real-time at scale.

Live location streaming on Android

The Android Views SDK is used for getting live location and movement data for devices and trips directly to your native Android app. Please follow steps below to learn how to integrate the SDK and get started with its API.

note

Currently we do support all of the Android versions starting from API 19 (Android 4.4 Kit Kat)

Add Views SDK

Add following lines to your app build.gradle file:

// Import the SDK within your repositories block
repositories {
maven {
name 'hypertrack'
url 'http://m2.hypertrack.com'
}
...
}
//Add HyperTrack Views SDK as a dependency
dependencies {
implementation 'com.hypertrack:hypertrack-views:0.8.5'
...
}

Instantiate Views SDK

Pass Context reference to get SDK instance.

HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, PUBLISHABLE_KEY);

Identify which device to track

For example, your app user a passenger waiting for a pickup. Your passenger app user needs to be able to see driver's device in real-time inside your app. You have a database of drivers, and dispatched an available driver to pick up your passenger. The driver is identified by the device id.

Please see this guide on how to get and store device ids required for your application workflow.

Views SDK

Your driver app user runs a dedicated driver app which integrates HyperTrack SDK on either Android or iOS. The driver's app is on the move and generates location data sent by HyperTrack SDK.

Get current location of tracked device

With the SDK, you can get current status of another's app user device status. For example, once a passenger launches the app, you may call to get location of the driver on the way to a pickup spot.

To do this, get current state of this driver's device, identified by driverDeviceId as shown in the snippet below:

hypertrackView.getDeviceMovementStatus(
driverDeviceId,
new Consumer<MovementStatus>() {
@Override
public void accept(MovementStatus movementStatus) {
Log.d(TAG, "Got movement status data " + movementStatus);
}
});

In the callback, you'll receive MovementStatus object which describes the current state of the driver's device. This object also contains location that you may able to use to render the current driver location with its status in the passenger's app.

Subscribe to streaming updates to get location data

You can receive device state changes updates as shown in the snippet below. In the example below, you can see the following callback methods:

  • onLocationUpdateReceived - gives you the location update for a device
  • onBatteryStateUpdateReceived - battery state change update
  • onStatusUpdateReceived - device status change
  • onTripUpdateReceived - provides a trip status update
  • onError - provides feedback about errors that may occur in streaming
  • onCompleted - notifies about a successful completion of subscription being stopped
hypertrackView.subscribeToDeviceUpdates(
driverDeviceId,
new DeviceUpdatesHandler() {
@Override
public void onLocationUpdateReceived(@NonNull Location location) {
Log.d(TAG, "onLocationUpdateReceived: " + location);
}
@Override
public void onBatteryStateUpdateReceived(@BatteryState int i) {
Log.d(TAG, "onBatteryStateUpdateReceived: " + i);
}
@Override
public void onStatusUpdateReceived(@NonNull StatusUpdate statusUpdate) {
Log.d(TAG, "onStatusUpdateReceived: " + statusUpdate);
}
@Override
public void onTripUpdateReceived(@NonNull Trip trip) {
Log.d(TAG, "onTripUpdateReceived: " + trip);
}
@Override
public void onError(Exception exception, String deviceId) {
Log.w(TAG, "onError: ", exception);
}
@Override
public void onCompleted(String deviceId) {
Log.d(TAG, "onCompleted: " + deviceId);
}
}
);

Tracking trips with Views SDK

Examples above illustrate how to create a passenger app and use Views SDK to track a driver. You may create a trip for the driver as explained in Track live route and eta to destination guide.

Since each trip created has a device id, you may use this device id to subscribeToDeviceUpdates. This way, you will get trip status updates, which include ETA, ETA changes, as well as delays via onTripUpdateReceived callback.

Streaming location data from multiple devices

In use cases where you need to track multiple devices in realtime in the app, you can easily accomplish this goal by subscribing to more than one device.

In the example below, you may execute subscribeToDeviceUpdates to get streaming updates for driverDeviceId_1 and driverDeviceId_2.

hypertrackView.subscribeToDeviceUpdates(
driverDeviceId_1,
new DeviceUpdatesHandler() {
@Override
public void onLocationUpdateReceived(@NonNull Location location) {
Log.d(TAG, "onLocationUpdateReceived: " + location);
}
}
hypertrackView.subscribeToDeviceUpdates(
driverDeviceId_2,
new DeviceUpdatesHandler() {
@Override
public void onLocationUpdateReceived(@NonNull Location location) {
Log.d(TAG, "onLocationUpdateReceived: " + location);
}
}
);

Stopping real-time streaming updates in app

Finally, if you wish to stop streaming updates or if the app user exits the screen where this experience is no longer required, you should invoke stopAllUpdates method in your HyperTrack Views instance.

hypertrackView.stopAllUpdates();

Live location streaming on iOS

The iOS Views SDK is used for getting live location and movement data for devices and trips directly to your native Android app.

Please follow steps below to learn how to integrate the SDK and get started with its API.

Getting started with Views SDK on iOS

Clone HyperTrack Views iOS repository

git clone https://github.com/hypertrack/views-ios.git
cd views-ios
Install Views SDK dependency

Please use CocoaPods dependency manager to install the latest version of the HyperTrackViews library. Using the latest version of CocoaPods is advised.

If you don't have CocoaPods, install it first. Run pod install inside the cloned directory. After CocoaPods creates the ViewsExample.xcworkspace workspace file, open it with Xcode.

Set your Publishable Key and Device ID

Open the ViewsExample project inside the workspace and set your Publishable Key and Device ID inside the placeholder in the ViewController.swift file.

Run the ViewsExample app

Run the app on your phone or simulator and you should see the map with your device on it. You can see the subscription status and full MovementStatus data structure in Console logs inside Xcode (for apps built in DEBUG mode).

Integrate HyperTrackViews library
note

HyperTrackViews supports iOS 11.2 and above, using Swift language.

Add HyperTrackViews to your project

We use CocoaPods to distribute the library, you can install it here.

Using command line run pod init in your project directory to create a Podfile. Put the following code (changing target placeholder to your target name) in the Podfile:

platform :ios, '11.2'
inhibit_all_warnings!
target '<Your app name>' do
use_frameworks!
pod 'HyperTrackViews'
end

Run pod install. CocoaPods will build the dependencies and create a workspace (.xcworkspace) for you.

Create an instance

To create an instance of HyperTrackViews, pass it your publishable key:

let hyperTrackViews = HyperTrackViews(publishableKey: publishableKey)

You can initialize the library wherever you want. If reference gets out of scope, library will cancel all subscriptions and network state after itself.

Get current location of tracked device

Please review the above section on how to get a device id for the device that needs to be traceked.

You can get a snapshot of your device movement status with movementStatus(for:completionHandler:) function:

let cancel = hyperTrackViews.movementStatus(for: "Paste_Your_Device_ID_Here") {
[weak self] result in
guard let self = self else { return }
switch result {
case let .success(movementStatus):
// Update your UI with movementStatus structure
case let .failure(error):
// React to errors
}
}

Update your UI using data from MovementStatus structure.

You can use cancel function to cancel the request if you want, just run cancel() to cancel the request.

You can ignore the return value from movementStatus(for:completionHandler:) by using let _ = moveme... pattern (The use of the pattern is needed until Apple will fix SR-7297 bug).

Subscribe to streaming updates to get location data

You can get movement status continuously every time tracked device updates its location. This function makes a movementStatus(for:completionHandler:) call under the hood, so you'll get initial status right away.

let cancel = hyperTrackViews.subscribeToMovementStatusUpdates(
for: driverDeviceId) { [weak self] result in
guard let self = self else { return }
switch result {
case .success(let movementStatus):
// Update your UI with movementStatus structure
case .failure(let error):
// React to subscription errors
}
}

You need to hold on to the cancel() function until you don't need subscription results.

If this function gets out of scope, subscription will automatically cancel and all network resources and memory will be released. This is useful if subscription is needed only while some view or controller is in the scope.

Tracking trips with Views SDK

Examples above illustrate how to create a passenger app and use Views SDK to track a driver. You may create a trip for the driver as explained in Track live route and eta to destination guide.

Since each trip created has a device id, you may use this device id to subscribeToMovementStatusUpdates. This way, you will get trip status updates, which include ETA, ETA changes, as well as delays via onTripUpdateReceived callback.

Streaming location data from multiple devices

In use cases where you need to track multiple devices in realtime in the app, you can easily accomplish this goal by subscribing to more than one device.

In the example below, you may execute subscribeToMovementStatusUpdates to get streaming updates for driverDeviceId_1 and driverDeviceId_2.

let cancel = hyperTrackViews.subscribeToMovementStatusUpdates(
for: driverDeviceId_1) { [weak self] result in
guard let self = self else { return }
switch result {
case .success(let movementStatus):
// Update your UI with movementStatus structure
case .failure(let error):
// React to subscription errors
}
}
let cancel = hyperTrackViews.subscribeToMovementStatusUpdates(
for: driverDeviceId_2) { [weak self] result in
guard let self = self else { return }
switch result {
case .success(let movementStatus):
// Update your UI with movementStatus structure
case .failure(let error):
// React to subscription errors
}
}

Special note on Xcode 10.1 Support

If you want to run the project on Xcode 10.1 that doesn't support Swift 5, you need to add this post_install script at the end of your Podfile. For this project you can copy-paste the following snippet below:

platform :ios, '9.0'
target 'ViewsExample' do
use_frameworks!
pod 'HyperTrackViews'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
if ['HyperTrackViews', 'AWSCore', 'AWSAppSync', 'ReachabilitySwift', 'SQLite.swift'].include? target.name
target.build_configurations.each do |config|
config.build_settings['SWIFT_VERSION'] = '4.2'
end
end
end
end

This script will set Swift 4.2 for all HyperTrackViews dependencies, so you don't need to do this every time.

Then you need to go to the Pods project inside the workspace then Pods > SQLite.swift > standard > Foundation.swift and change datatypeValue function to:

public var datatypeValue: Blob {
return withUnsafeBytes { (pointer: UnsafePointer<UInt8>) -> Blob in
return Blob(bytes: pointer, length: count)
}
}

Select Unlock when Xcode prompts, then build the project. You'll need to change datatypeValue function every pod reinstall, until this issue is closed.

Summary

HyperTrack Views SDK for both Android and iOS allow you to stream location data from devices using HyperTrack SDK.

HyperTrack SDKs for for Android and iOS, including Flutter and ReactNative modules, allow you to integrate location tracking. They automatically send location in real-time whenever you use HyperTrack Devices and Trips API to control their location tracking.

With HyperTrack Devices and Trips APIs, HyperTrack SDKs, and HyperTrack Views SDKs you have a full set of tools powered by HyperTrack infrastructure to help you create apps such as carpooling, ridesharing, as well as any other use cases requiring real-time native app tracking experiences. We can't wait to see you focus on what you do best: create and build apps while leaving the worries of location tracking infrastructure and tools to HyperTrack.

Stream data to front-ends using GraphQL

You can create compelling live location tracking views on mobile devices and desktop applications for your app users without having to provision your infrastructure.

For example, with HyperTrack, you can implement ride sharing applications where passengers can view their drivers arriving to the pickup location live on their phone. Your delivery customers can track delivery driver whereabouts and ETA in the native experience of your app. A foreman in the field can track live locations of crew members in the field, in real-time.

Using GraphQL to power live tracking views

To help achieve the goal of live tracking of your app users, HyperTrack utilizes GraphQL. HyperTrack GraphQL schema defines queries and subscriptions that drive and support native app experiences as well as custom web apps you may decide to build.

important

This is a pre-release feature which is under active development and implementation may be subject to change. If you would like to get access to create live views in your app, please contact us.

Getting started

HyperTrack uses AWS AppSync to provide support for its GraphQL schema.

You need the following to get started:

  • GraphQL schema that can be found here.
  • Access to GraphQL server URL with an API Key.
note

Get in touch with us to obtain access to HyperTrack GraphQL end point.

GraphQL schema

Please follow detailed examples of queries and subscriptions below that can power your app.

Query to get device movement status and its trips

HyperTrack supports an ability to create trips with Trips API as explained in this guide.

Query getMovementStatus gives you detailed information about device status as well as actively ongoing trips. Use a device_id which you want to track live in your app in both native mobile app and as well as in a web app.

In order to perform this query, you must also obtain a publishable key available in your HyperTrack Dashboard Setup page.

query GetMovementStatus($device_id: String!, $publishable_key: String!) {
getMovementStatus(device_id: $device_id, publishable_key: $publishable_key) {
device_id metadata
location {
accuracy bearing speed
geometry { coordinates }
recorded_at
}
battery
device_status {
value
active { activity recorded_at }
inactive { reason recorded_at }
disconnected { recorded_at }
}
device_info { app_name app_version_string app_version_number device_brand device_model name os_name os_version sdk_version }
trips {
trip_id device_id started_at completed_at metadata
status eta_relevance_data { status reason }
views { embed_url share_url }
destination {
geometry { coordinates }
radius address scheduled_at arrived_at exited_at
}
geofences {
geofence_id
metadata
geometry { type center vertices }
radius
arrived_at exited_at
}
estimate {
route {
distance duration remaining_duration
start_address end_address
polyline { coordinates }
}
}
trip_summary {
distance duration started_at completed_at
locations { coordinates { coordinate timestamp} }
markers {type data {
__typename
... on GeofenceMarkerData {
geofence_visit_duration: duration
arrival {location {recorded_at geometry {coordinates}}}
exit {location {recorded_at geometry {coordinates}}}
geofence {
geofence_id radius arrived_at exited_at metadata
geometry {type center vertices}
}
route_to {
duration distance
start_location {recorded_at geometry {coordinates}}
}
}
... on TripMarkerData {
recorded_at metadata
location {coordinates}
route_to {
duration distance
start_location {recorded_at geometry {coordinates}}
}
}
... on DeviceStatusMarkerData {
distance duration reason value activity
start {recorded_at location {geometry {coordinates}}}
end {recorded_at location {geometry {coordinates}}}
}
}}
}
}
}
}

The query will return current location of the device identified by device_id, along with its device_status and trips data.

To get understanding of device status and trips data structures, please visit this GraphQL schema file and following guides:

  • Device status as explained in this guide.
  • Trips API create trips response section.

Query to get trip data

Once you know trip_id and want to optimize getting specific trip data, you can use getTrip query which will retrieve current trip data:

query GetTrip($trip_id: String!, $publishable_key: String!) {
getTrip(trip_id: $trip_id) {
trip_id device_id started_at completed_at metadata
status eta_relevance_data { status reason }
views { embed_url share_url }
destination {
geometry { coordinates }
radius address scheduled_at exited_at arrived_at
}
geofences {
geofence_id
metadata
geometry { type center vertices }
radius
arrived_at exited_at
}
estimate {
route {
distance duration remaining_duration
start_address end_address
polyline { coordinates }
}
}
trip_summary {
distance duration started_at completed_at
locations { coordinates { coordinate timestamp} }
markers {type data {
__typename
... on GeofenceMarkerData {
geofence_visit_duration: duration
arrival {location {recorded_at geometry {coordinates}}}
exit {location {recorded_at geometry {coordinates}}}
geofence {
geofence_id radius arrived_at exited_at metadata
geometry {type center vertices}
}
route_to {
duration distance
start_location {recorded_at geometry {coordinates}}
}
}
... on TripMarkerData {
recorded_at metadata
location {coordinates}
route_to {
duration distance
start_location {recorded_at geometry {coordinates}}
}
}
... on DeviceStatusMarkerData {
distance duration reason value activity
start {recorded_at location {geometry {coordinates}}}
end {recorded_at location {geometry {coordinates}}}
}
}}
}
}
}

Query to get trip destination, estimate, and metadata

Additionally, in the use case where you already have a trip rendered and want to query updates involving only the following:

  • Destination being reached and exited
  • Trip ETA being changed
  • Trip metadata changes if any

you can perform getTrip query with only these query attributes you are interested in:

query GetTripDestination($trip_id: String!, $publishable_key: String!) {
getTrip(trip_id: $trip_id) {
trip_id device_id
destination {
geometry { coordinates }
radius address scheduled_at arrived_at exited_at
}
}
}
query GetTripEstimate($trip_id: String!, $publishable_key: String!) {
getTrip(trip_id: $trip_id) {
trip_id device_id
eta_relevance_data { status reason }
estimate {
route {
distance duration remaining_duration
start_address end_address
polyline { coordinates }
}
}
}
}
query GetTripMetadata($trip_id: String!) {
getTrip(trip_id: $trip_id) { trip_id device_id metadata }
}
### Query to get trip geofences and summary
query GetTripGeofencesAndSummary($trip_id: String!, $publishable_key: String!) {
getTrip(trip_id: $trip_id) {
trip_id device_id
geofences {
geofence_id
metadata
geometry { type center vertices }
radius
arrived_at exited_at
}
trip_summary {
distance duration started_at completed_at
locations { coordinates { coordinate timestamp} }
markers {type data {
__typename
... on GeofenceMarkerData {
geofence_visit_duration: duration
arrival {location {recorded_at geometry {coordinates}}}
exit {location {recorded_at geometry {coordinates}}}
geofence {
geofence_id radius arrived_at exited_at metadata
geometry {type center vertices}
}
route_to {
duration distance
start_location {recorded_at geometry {coordinates}}
}
}
... on TripMarkerData {
recorded_at metadata
location {coordinates}
route_to {
duration distance
start_location {recorded_at geometry {coordinates}}
}
}
... on DeviceStatusMarkerData {
distance duration reason value activity
start {recorded_at location {geometry {coordinates}}}
end {recorded_at location {geometry {coordinates}}}
}
}}
}
}
}

Live location tracking

Finally, to help create live experience in your app, use subscribeToLatestEvent subscription to get latest device location, battery, device status, as well as trip updates streamed to your device.

subscription SubscribeToLatestEvent($device_id: String!, $publishable_key: String!) {
subscribeToLatestEvent(device_id: $device_id, publishable_key: $publishable_key) {
device_id
publishable_key
location {
geometry { coordinates }
accuracy bearing speed recorded_at
}
battery
device_status {
value
active {activity recorded_at}
inactive {reason recorded_at}
disconnected {recorded_at}
}
trip_update {trip_id change_reason}
}
}

Trip change reasons can be one of the following as explained in the schema:

enum TripChangeReason {
completed
created
delayed
destination_arrival
destination_exit
geofence_enter
geofence_exit
metadata_change
recalculated
remaining_duration_update
}

Using API key to access HyperTrack GraphQL end point

Please follow this example to perform a query against HyperTrack GraphQL end point:

curl -X "POST" "<hypertrack_graphql_url>" \
-H 'X-Api-Key: <api_key>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"query": "query Trips( ... ",
"variables": {
"input": {
"publishable_key": "your-publishable-key"
}
}
}
note
Contact us with us to obtain access to HyperTrack GraphQL end point.

Questions?

If you have questions or comments on any of the topics above, please do not hesitate to contact us.