Workforce automation, logistics and fleet management apps are often built for users to fulfill a list of jobs assigned at the start of the work day. User visits these places and then returns to base. Business wants to track how time was spent, what routes were taken, and map it with enterprise application data to measure productivity scores and improve efficiency. This guide will show you how to:
- Start and complete trips that represent a work shift
- Get arrival and exit notifications at geofences for real-time use cases
- Get time spent and route to geofences to merge with application data
- Embed trip view in ops dashboard
- Get trip summary data for the day's record
Start and complete trip
Use the Trips API when you want to track the movement of the device to a list of geofences. Post the geofences as an array to get get arrival, exit, time spent and route to geofences, embed URL for ops dashboards, and markers for activity and outages as the device moves. Completed trips include a summary with total duration, distance and steps.
- Objective C
To start such a trip, the
geofences array is required. The array should include objects with a GeoJSON object called
Polygon are supported in the GeoJSON object.
Point will set a circular geofence area with a radius of 30 meters by default.
Polygon will set a polygon geofence through an array of locations where the first and last location must be the same.
To change the default radius, you can pass a
radius property (interger in meters) to the geofence object.
metadata to identify each geofence in HyperTrack with the place of interest in your application. The metadata is returned through the respective APIs, webhooks, and views.
To identify a HyperTrack Trip with your application's work day, and geofences with your places of interest, please use the metadata object for trip and geofences respectively.
The Trips API responds with an active trip object that returns the original payload with additional properties.
- Objective C
Complete the trip at the end of the work day, e.g. when all jobs are done, end of work hours, assets returns to the station.
If active trips are not completed after 72 hours since trip start time, HyperTrack will automatically complete them to ensure best API performance and experience.
It is important to understand that trip completion cannot be confirmed right away with the API response. This is due to communication required between the HyperTrack platform, the mobile SDK on the phone, and post processing to create a trip summary.
- Objective C
It usually takes a few seconds to confirm a pending trip completion. As soon as the trip is completed, HyperTrack will send a trip completion webhook. The payload of the webhooks includes the trip ID and metadata.
Get arrival and exit
The geofence objects in the trips payload have
exited_at properties. These are
null initially. As soon as the tracked device enters the geofence, arrival time is updated for that geofence. Similarly, when the device exits the geofence, the exit time is set for that geofence.
Upon arrival or exit of a geofence, HyperTrack sends a geofence webhook. The payload of the webhook includes the trip ID and metadata as well as the geofence metadata.
Update geofence metadata
Users who want to update geofence metadata after trip creation can PATCH geofence metadata. Use this when new application data has been recieved about that place of interest, and you wish to display them in views and add them to the trip summary object for record.
Get time spent and route to
The geofence markers in trip summary have
route_to properties. The
route_to object includes distance, duration, start location and array of locations for the route from previous geofence (or from start in case of the first geofence).
Embed trip view in dashboard
The Trip payload includes the
views object. Every trip gets assigned unique URLs to share and embed views of the trip. The URLs will remain active after trip completion. In that case, the views will show a summary of the trip, along with geofence markers, start and complete location, distance, duration, arrival time, device info, trip metadata, and the actual route taken to the destination.
While shareable views are accessible to everyone with the URL, embed views include the HyperTrack publishable key. The embed_URL includes the publishable key and is available to use as-is. That said, your publishable key is available in the Setup page of your HyperTrack dashboard.
The embed URL format is
Iframes have important properties to be considered during implementation. Please read the following instructions carefully to ensure a seamless integration:
- Iframe size: By default, Iframes are sized with 200 pixels height and 300 pixels width. It is recommended to implement responsiveness using CSS. Here is a sample implementation
- Responsive views: All embeddable views are responsive and the mobile views will be displayed when the Iframe size is below 500 pixels
- Security: When you activate the
sandboxproperty for this Iframe, please include
- Compatibility: Please review browser compatibility of IFrame properties you want to use
Trips API generates embed_URL for all trips. More details can be found in the Trips API reference.
Get trip summary data
Trip summary provides powerful data about the device's trip visiting geofences.
- Start and complete time
- Aggregate distance, duration, steps
- Array of locations
- Array of markers, each marker has a type and associated data
- Device status markers include stop, walk, drive, inactive and disconnected segments with associated context
- Geofence markers include arrival/exit time and location, duration and route with array of locations
- Trip and geofences come with metadata as set at the time of creation or patched later