Track work day with visit notes

Introduction

For example, you are building a location aware sales force tracking solution. Operations managers have fleets of sales reps visiting customers during their working day.

At each customer visit site, sales reps can make notes in their app in real-time. Operations managers get full visibility where their sales reps are at any given moment, and at the same time can audit notes sales reps make in their dashboard on the map. At the same time, it's important to enable location tracking for sales rep's app to only track during work hours to protect their privacy outside during personal hours.

This guide will explain how to:

Track only during work hours

To track app users only during work hours, use Devices API to start and stop tracking for sales reps devices.

HyperTrack Devices APIs give you the power to control tracking on all devices using apps with HyperTrack SDKs pointing to your account. As you perform Device API calls from your servers, you are can remotely start and stop tracking devices with apps running HyperTrack SDK integration.

Start tracking

Call Devices API call to start tracking for your device.

In order to start and stop tracking on your app user's device, you should be able to obtain, store, and reference your users' HyperTrack device_id when calling this API from your server.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to start tracking
hypertrack.devices
.startTracking(deviceId)
.then(() => {
// Tracking started
})
.catch(error => {
// Error handling
});

Stop tracking

To protect the app user's privacy during personal hours, make a Devices API stop tracking call. Once you issue this call from the server, HyperTrack Device API will remotely stop tracking for your device with device_id.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to stop tracking
hypertrack.devices
.stopTracking(deviceId)
.then(() => {
// Tracking started
})
.catch(error => {
// Error handling
});

Use custom markers to make notes

Use custom markers to generate notes from the user's app. 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 a note your app user may make.

For example, to represent a customer visit, you may want to create this payload as shown below:

{
"product_id": "Kent Ace",
"action": "sold",
"quantity": 5,
"customer_name": "Amit K"
}

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 Kent Acee identifying your app event location and provide you with distance tracking for your mobile application app events.

Sending visit notes as custom markers from your user's 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("product_id", "Kent Ace");
payload.put("action", "sold");
payload.put("quantity", 5);
payload.put("customer_name", "Amit K");
sdkInstance.addTripMarker(payload);

Observe visit notes in operations dashboard

HyperTrack dashboard will display these visit notes as custom markers in 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 customer marker with sales rep visit notes. Each blue dot represents a visit note your app user made from the app by sending a custom marker to HyperTrack.

Custom Event Marker in Dashboard

This view demonstrates how your a visit note will be displayed by HyperTrack after it's delivered as a custom marker from your user's mobile app. HyperTrack also provides location and timestamp in addition to the payload data from the example above.

Integrate visit notes in real-time with your app backend via webhooks

If your app business workflow requires real-time integration of app user's notes as they take place, 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 custom marker 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 user's app.

Plus, you get location that HyperTrack captures for you when your app user generates a note in the app.

{
"created_at": "2019-07-01T14:01:00.000000Z",
"recorded_at": "2019-07-01T14:00:00.000000Z",
"data": {
"metadata": {
"product_id": "Kent Ace",
"action": "sold",
"quantity": 5,
"customer_name": "Amit K"
},
"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"
}

Make annotations at the end of the day

For example, a sales exec has stops on the route that are longer than expected and business rules require annotations for each stop that took place.

POST   https://v3.api.hypertrack.com/trips

Create a trip to start tracking

Use Trips API to create trips and remotely start tracking for your app user's devices once the trip is created at the beginning of the work day.

Device tracking will be started remotely if you have integrated push notifications for your app with HyperTrack SDK on iOS and Android.

Starting and completing trips would automatically control the start and stop of tracking on the device. This way, you manage device tracking through just one API.

// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let tripData = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF"
};
hypertrack.trips.create(tripData).then(trip => {
// Trip created
}).catch(error => {
// Error handling
})

Stop tracking with trip completion

In order to complete the trip, HyperTrack provides you Trips complete API. In the response, you will get markers for activity and outages as to capture history of device movement. Completed trips also include a summary with total duration, distance and steps.

POST   https://v3.api.hypertrack.com/trips/{trip_id}/complete

Once this method is invoked, HyperTrack will proceed to complete your trip and thereby stop tracking for your app user's device.

Get trip summary and annotate stops

HyperTrack provides GET Trips APIs to retrieve completed trip data.

For all completed trips, a summary object is returned as part of the trip response payload.

GET   https://v3.api.hypertrack.com/trips/{trip_id}

Please review completed trip summary data as part of GET Trips API response payload below. The summary object contains, among others, these attributes:

  • locations - object representing the location time series of the full trip. It follows GeoJSON geometry of type LineString
  • markers - an array of markers representing device status (such as a stop, drive, etc), geofence events, custom markers, as well as a destination marker in case of a trip with destination. Please that each marker is assigned a unique marker_id upon completion of the trip.

To understand the trip response payload data in full, please visit this reference documentation section

Trips API: Summary available for completed trips
{
"trip_id":"5ce3ec28-3d73-48c0-bf25-fca5563557c5",
"device_id":"3318AB96-2B43-4BCE-8639-A48D020EEC72",
"started_at":"2020-05-09T06:18:11.541213Z",
"completed_at":"2020-05-09T06:18:27.653353Z",
"status":"completed",
"views":{
"embed_url":"https://embed.hypertrack.com/trips/5ce3ec28-3d73-48c0-bf25-fca5563557c5?publishable_key={key}",
"share_url":"https://trck.at/abcdef"
},
"device_info":{
"os_version":"13.3.1",
"sdk_version":"4.0.2-rc.6"
},
"destination":{
"geometry":{
"type":"Point",
"coordinates":[
-122.51031,
37.764022
]
},
"radius":30,
"scheduled_at":null,
"address":"YYYY Great Hwy, San Francisco, CA 94121, USA"
},
"summary":{
"locations":{
"type":"LineString",
"coordinates":[
...
]
},
"distance":0,
"duration":16,
"started_at":"2020-05-09T06:18:11.541213Z",
"steps":0,
"completed_at":"2020-05-09T06:18:27.653369Z",
"device_id":"3318AB96-2B43-4BCE-8639-A48D020EEC72",
"markers":[
{
"marker_id":"e05ef2ac-8671-41ee-9d3f-285083998814",
"type":"device_status",
"data":{
"value":"active",
"start":{
"recorded_at":"2020-05-09T06:18:11.541Z"
},
"end":{
"recorded_at":"2020-05-09T06:18:27.653Z"
},
"activity":"stop",
"steps":0,
"duration":16
}
},
{
"type":"destination",
"marker_id":"8479e48c-0de6-422e-a2ac-319b087a783b",
"data":{
"address":"1098 Great Hwy, San Francisco, CA 94121, USA",
"geofence":{
"geofence_id":"6bda6e9c-5a44-474b-9895-eb93dbdbf9a2",
"geometry":{
"type":"Point",
"coordinates":[
-122.51031,
37.764022
]
},
"radius":30,
"metadata":null
}
}
}
],
"start_address":"XXXX Nth Ave, San Francisco, CA 94122, USA",
"end_address":"YYYY Great Hwy, San Francisco, CA 94121, USA"
},
"analytics":{
"total_duration":0,
"active_count":1,
"active_duration":16,
"stop_count":1,
"stop_duration":16
},
"eta_relevance_data":{
"status":true
}
}

Inside trip summary, retrieve all markers of type device_status that have duration longer than threshold suitable for your use case.

note

This API is in limited Beta with select customers. Please contact us to get access.

Each marker inside trip summary can be annotated with metadata that can displayed in the operations dashboard.

Use this PATCH Trips API call to set metadata for the stop that can be found by its marker_id.

PATCH   https://v3.api.hypertrack.com/trips/{trip_id}/marker

with a request body as in an example below as explained in Trips Marker API reference documentation:

[
{
"marker_id": "e05ef2ac-8671-41ee-9d3f-285083998814",
"metadata": {
"note": "considering purchase quantity and competitive pricing",
"note_recorded_at": "May 9th, 2020"
}
}
]

The metadata needs to be a valid JSON object and can contain any keys and values that support your marker annotation use case. This PATCH Trips markers API supports updates for one or more trip summary markers at once.

important

Annotation for markers can only be made for completed trip summaries. Setting marker metadata will remove original content and replaced with the metadata sent in the PATCH Trips API method.

Once the PATCH request is made successfully, GET Trips API for will return the same trip summary along with updated trip summary marker metadata for marker_id e05ef2ac-8671-41ee-9d3f-285083998814 as shown in the abbreviated example below:

{
"trip_id":"5ce3ec28-3d73-48c0-bf25-fca5563557c5",
...
"summary":{
"markers":[
{
"marker_id":"e05ef2ac-8671-41ee-9d3f-285083998814",
"type":"device_status",
"data":{
"metadata": {
"note": "considering purchase quantity and competitive pricing",
"note_recorded_at": "May 9th, 2020"
},
"value":"active",
"start":{
"recorded_at":"2020-05-09T06:18:11.541Z"
},
"end":{
"recorded_at":"2020-05-09T06:18:27.653Z"
},
"activity":"stop",
"steps":0,
"duration":16
}
}
...
]
...
}
}

Questions?

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