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.

In order to perform API calls from your server, you need to first obtain AccountId and Secret Key.

Start tracking

For example, if you would like to start tracking when your app at the start of working hours, or work assignment, or app login, you may want to call Devices API call to start tracking for your device. In order to start tracking on your device, you should be able to obtain, store, and reference your users' HyperTrack device_id when calling this API from your server.

To start tracking your device, you may make a Devices API call as shown below.

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

In order to protect the privacy of workers using your app, you are strongly encouraged to stop tracking when the user either logs out, ends working hours, completes all assigned work, etc. To do so, you may 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
});

Get the device ID(s) of the user(s) you want to track

The SDK should have added a device name and metadata upon initialization in the user's app: (iOS, Android).

If you have already sent and stored this information to your servers, get the user's device ID from your application database. Else, get the list of registered devices from the Devices API and use the device name or metadata to identify the user(s) you want to track.

HyperTrack views and developer integrations rely on the device names and metadata for filtering, selection, and more. Customizing these device properties makes navigation and identification of users easier. Developers often add unique identifiers, grouping information, or annotations that are frequently accessed for devices.

Device name and custom metadata
{
"name": "Alex’s Phone",
"metadata": {
"customer_id": "ABC123"
}
}

By default, the property name is set to the name of the device as configured in the device settings. With the SDK, you can set and customize this name. Additionally, the Devices API provides you an ability to update device name and metadata via an HTTP PATCH.

note

The Devices API is authoritative when it comes to setting the device name and/or metadata. Once you have updated the device name by invoking the Devices API above, the HyperTrack mobile SDK will not be able to make subsequent changes to the device name. Similarly, if you update the device metadata via the Devices API call, the HyperTrack mobile SDK will not be able to make changes as well.

Use geotags to make notes

Use geotags to generate notes from the user's app. HyperTrack provides geotags on iOS and Android.

Every important app event that is generated by your app user can be captured as a geotag with a payload that represents it. HyperTrack platform will process geotags 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.

Geotag payload structure and example

An geotag 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 geotags 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 geotag 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 geotags 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 geotag 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 geotag 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 geotag 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"
}

Questions?

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