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:
- Start and stop tracking based on work hours
- How to add notes during customer visits
- How to make annotations at the end of the day in completed trip summaries
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.
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.
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
Use custom markers to make notes
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:
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:
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.
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
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.
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.
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.
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.
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.
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.
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
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_idupon completion of the trip.
To understand the trip response payload data in full, please visit this reference documentation section
Inside trip summary, retrieve all markers of type
device_status that have
duration longer than threshold suitable for your use case.
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
with a request body as in an example below as explained in Trips Marker API reference documentation:
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.
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
e05ef2ac-8671-41ee-9d3f-285083998814 as shown in the abbreviated example below:
If you have questions or comments on any of the topics above, please do not hesitate to contact us.