Track distance between app events

Tracking distance between important app events

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 custom markers.

Custom markers as app events

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

Every important app event that is generated by your app user can be captured as a custom marker with a payload that represents it. HyperTrack platform will process custom markers sent from your mobile app in the cloud and process them in real-time with analysis for location accuracy.

Additionally, even if your app user's device is temporarily disconnected due to a network loss, app events generated by your users will be nevertheless captured and sent to HyperTrack once connection is restored.

Custom marker payload structure and example

An custom marker 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 customer event marker payload. HyperTrack will take care identifying your app event location and provide you with distance tracking for your mobile application app events.

Sending app events as custom markers 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 custom marker 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.addTripMarker(payload);

Observing app events in dashboard in real-time

As you generate app events via custom markers from your mobile app, HyperTrack dashboard will display these events as custom markers in your device history 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 custom marker event 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 custom marker 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

Measuring distance between custom markers

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

Tracking distance between app events 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"
}

Getting tracked distance between app events via 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.