Track actual distance

Actual distances covered by app users is an important input to financial systems for field workers. Distances are used to bill customers and pay out partners. This has direct financial impact for the business, and impacts customer and partner satisfaction. Both under-billing and over-billing have negative consequences for one side of the network, and negatively impact the aggregator business. Accurate distance computation for actual movement saves money due to higher customer/partner satisfaction, and potentially saves money by eliminating expensive maps API costs that are often involved in distance estimation.

This guide provides a simple way to generate actual distances from one app event to the other as they happen. This data is posted over webhooks, and made available through exports and APIs. App events are passed to HyperTrack SDKs using geotags.

Geotag app events

In order to track distance between app events marking your app user's actions, HyperTrack provides geotags on iOS and Android.

Important app events generated by your app users may be geotagged with a payload. HyperTrack geotags the app event with an accurate location, computes distance since previous geotag, and tracks deviation from expected location.

If your app user is temporarily offline, geotags will get captured on the device and synced up to the server when the connection is restored.

Geotag payload structure and example

An geotag payload can be a JSON string describing attributes of your app user's app event.

For example, if you have a delivery rider dropping off a package at the destination. It may be important for your customers to know that this rider was riding a bike, represented a given dispatch station id, package id, route, and how the package was delivered (i.e. left at the doorstep).

To represent the above, you may want to create this payload as shown below:

{
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
}

As you trigger an app event in your app, you do not need to worry about getting location and timing to compose geotag payload. HyperTrack will take care identifying your app event location and provide you with distance tracking for your mobile application app events.

Geotagging app events from your mobile app

The examples below demonstrate how to accomplish this for both iOS and Android with the example payload as discussed:

// create new geotag payload
Map<String,Object> payload = new HashMap<>();
// add event details from the example above
payload.put("Route type", "Car");
payload.put("Station Id", "1BCX");
payload.put("Package Id", "1WUXZ1393");
payload.put("Route Id", "2248311");
payload.put("Action Type", "Reached Doorstep");
sdkInstance.addGeotag(payload);

Verify geotag expected location

With geotags, you can understand potential deviations from locations expected to be visited by your mobile fleet. HyperTrack will provide you real-time feedback to show potential deviations between expected and actual locations at the time geotag is generated by your app user. This way, you can confirm and verify geofence accuracy for visits and actions by your mobile fleet.

To verify geotag expected location, attach expected location to verify that the actual location where action took place matches your expectation.

val expectedLocation = Location("any")
expectedLocation.longitude = -90.0260493
expectedLocation.latitude = 35.0476912
HyperTrack.getInstance(publishableKey).addGeotag(
mapOf("note" to "Handoff at the Market street entrance"),
expectedLocation
)

Deviation between actual and expected might indicate an incorrect address, or incorrect behavior. Deviations will be indicated in the geotag webhooks, displayed in map views, and reported in leaderboard scores.

Analyzing those deviation on regular basis you can improve your dataset quality and refine your business processes.

Observing geotags in dashboard in real-time

As you geotag app events from your mobile app, HyperTrack dashboard will display these events as geotags in your device timeline view. These are fully embeddable views that you can integrate directly into your ops dashboard.

In the map view, once you select the device you are interested in the left column, please click on the pop-up icon next to it to get to a single device view window.

Each app event is denoted as a blue dotted marker in both your device history timeline as well as on the map itself. Once you zoom in and click on the blue dot you are interested in, you can see the card with geotags and associated data.

The image below demonstrates how your example payload data for your app event will be displayed by HyperTrack after it's delivered as a geotag from your mobile app. HyperTrack also provides location and timestamp in addition to the payload data from the example above.

Custom Event Marker in Dashboard

Getting distance between geotags

As HyperTrack processes the stream of app events from your mobile application, it will generate route distance and time between your geotags and provide you this data in real-time via webhooks as well as reports via data exports.

Get geotag distances in real-time via webhooks

If your app business workflow requires real-time tracking of distance between app events, you may use HyperTrack webhooks feature to get this information.

Please review an example payload as shown below.

You can see that not only you get back payload data your app user generated from the mobile app, but also route_to data which contain distance in meters, duration in seconds, start_location from the previous app event for which distance and duration is generated, as well as recorded_at timestamp which captures the time this app event was received from your mobile app.

Lastly, but not least importantly, you get location that HyperTrack captures for you when your app user generates an app event.

{
"created_at": "2019-07-01T14:01:00.000000Z",
"recorded_at": "2019-07-01T14:00:00.000000Z",
"data": {
"metadata": {
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
},
"route_to":{
"distance": 238,
"duration": 63,
"start_location": {
"geometry": {
"coordinates": [
-6.271,
57.6398983
],
"type": "Point"
},
"recorded_at": "2019-07-01T13:52:08.213000Z"
}
}
},
"location": {
"type": "Point",
"coordinates": [
-6.2755,
57.6398983
]
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "custom_marker",
"version": "2.0.0"
}

Get geotag distances as data exports

Additionally, you can get this data by using HyperTrack Devices export API for reporting and tracking distance between app events analysis purposes.

Please review a relevant portion of exported device history data below as an example.

You can see also payload data your app user generated, as well as route_to data and location that is recorded for this app event.

{
...
"data": {
"location": {
"coordinates": [
77.5671771,
13.0709144
],
"type": "Point"
},
"metadata": {
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
}
"recorded_at": "2020-03-10T02:01:59.978000Z",
"route_to": {
"distance": 1243,
"duration": 577,
"start_location": {
"geometry": {
"coordinates": [
77.569829,
13.0655947
],
"type": "Point"
},
"recorded_at": "2020-03-10T01:52:08.213000Z"
}
}
},
"type": "custom_marker"
...
}

Questions?

If your have requirements to increase operational efficiency of your business assets by tracking distance between app events, questions or comments on any of the topics above, please do not hesitate to contact us.