Events

After you plug in the SDK, HyperTrack generates Events that happen in the life of the user. For example, user arrived at a destination, user delayed by X minutes, and user turned off location. Read this case study to see how our customers use events to run their business.

events

Which events can I can choose from?

You can choose the events that you are interested in and only those would be sent to you. We are continuously adding to our list of events. You may customise your alerts to be delivered to specific groups of users.

Where can I receive events?

HyperTrack creates an event object for each event. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Event objects can currently be delivered to you in real-time over 2 channels:

  • webhooks: HyperTrack sends the event object to URLs that you provide.
  • slack alerts: HyperTrack sends a human readable message on a slack channel of your choice with details about the event and a link to dig deeper.

How do I start receiving events?

The prerequisite is to plug in the HyperTrack SDK into your user’s app. Once you see the first user on your dashboard, use these links to setup setup webhooks and setup slack alerts.

Want a new event or a new platform to receive them?

We are happy to integrate new delivery mechanisms to push events to you on your favourite platform. If you want to request a new event type or delivery platform, please write to us.

The Event object

Property Type Description
id uuid string Unique identifier for the object
user_id uuid string Identifier for the user object to which the event belongs
type string Description of the event, e.g. trip.ended, task.completed. More types listed below.
recorded_at ISO datetime string Timestamp of when the event occurred
data JSON JSON containing data associated with the event
has_been_delivered boolean Indicates whether the event was delivered via webhook or not
delivered_at ISO datetime string Timestamp of when the event was delivered via webhook
created_at ISO datetime string Timestamp of when the event was created

Event types

This is a list of all the types of events we currently send. You'll notice that these events follow a pattern, resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against. Clicking on the event name will show you a sample event of that type. You can also fire sample events from account settings on dashboard.

User events

These events describe a User. They are generated as soon as the SDK is plugged into your app.

Event type Description
user.created Occurs when a user is created on HyperTrack
tracking.started Occurs when tracking is started and the user goes online
tracking.ended Occurs when tracking is ended and the user goes offline
trip.started Occurs when the user has started moving on a trip
trip.ended Occurs when the user has stopped moving
stop.started Occurs when the user is making a stop
stop.ended Occurs when the user is moving after making a stop
user.activity.walking Occurs when the user starts walking from being stationery or using some other mode of transport
user.activity.running Occurs when the user starts running
user.activity.cycling Occurs when the user starts cycling
user.activity.automotive Occurs when the user starts driving
device.location.disabled Occurs when the user disables location on device
device.location.enabled Occurs when the user enables location on device
device.location_permission.disabled Occurs when the user revokes location permission from the app on device
device.location_permission.enabled Occurs when the user grants location permission to the app on device
device.secondary.ignored Occurs when a user starts tracking on a secondary device when a tracking session is already active on a device.
user.speeding Occurs when the user is speeding above the speed limit of the road
user.stuck_in_traffic Occurs when the user is stuck in traffic while on a trip

Action events

These events generated only after actions have been integrated in your app. They describe an Action or a User.

Event type Description
action.assigned Occurs when an action is assigned to a user
action.leaving_now Occurs when the action is next in queue and user hasn't started moving
action.on_the_way Occurs when that action is next in queue and user is on the way to perform that action
action.arriving Occurs when the user is arriving at the expected place of action
action.delayed Occurs when user is delayed from her earlier estimated time of arrival
action.on_time Occurs when user is back on schedule for an action from being delayed earlier
action.arrived Occurs when the user has arrived at the expected place of action
action.completed Occurs when the action has been completed
action.completed_at_different_place_than_expected Occurs when the user has completed action at a place different than expected
action.device.location.disabled Occurs when the user disables location on device, at a time when the user has pending actions (assigned but not yet completed/canceled). It is like device.location.disabled event but occurs only under the condition that the user has pending actions
action.device.location_permission.disabled Occurs when the user revokes location permission from the app on device, at a time when the user has pending actions (assigned but not yet completed/canceled). It is like device.location_permission.disabled event but occurs only under the condition that the user has pending actions
action.tracking.ended Occurs when location tracking is ended for the user, at a time when the user has pending actions (assigned but not yet completed/canceled). It is like tracking.ended event but occurs only under the condition that the user has pending actions
action.device.location.enabled Occurs when the user enables location on device, at a time when the user has pending actions (assigned but not yet completed/canceled). It is like device.location.enabled event but occurs only under the condition that the user has pending actions
action.device.location_permission.enabled Occurs when the user grants location permission to the app on device, at a time when the user has pending actions (assigned but not yet completed/canceled). It is like device.location_permission.enabled event but occurs only under the condition that the user has pending actions
action.tracking.started Occurs when location tracking is started for the user, at a time when the user has pending actions (assigned but not yet completed/canceled). It is like tracking.started event but occurs only under the condition that the user has pending actions

Geofence events

These events describe an instance of a user satisfying the rules laid down by a Geofence. They are useful in being notified of instances when a geofence is triggered.

Event type Description
geofence.time.triggered Occurs when a time-based geofence is triggered (user spends more than X amount of time at any place where X was defined by you when you created the geofence)
geofence.location.entered Occurs when a user enters a location-based geofence (any point of interest that you have defined by creating a geofence)
geofence.location.exited Occurs when a user leaves a location-based geofence (any point of interest that you have defined by creating a geofence)

Retrieve a Event

This API retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook. All events share a common structure, detailed below. The only property that will differ is the data property.

In each case, the data dictionary will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, a order.created event will have the same information as retrieving the relevant order would.

HTTP Request

GET https://api.hypertrack.com/api/v1/events/<id>/

Returns

Returns an event object if a valid identifier was provided.

curl "https://api.hypertrack.com/api/v1/events/e686fe05-b64d-464d-a4e5-c65e278c1bf1/"
  -H "Authorization: token YOUR_SK_TOKEN"

Example response

{
   "id":"000225ce-5841-4cfa-afa0-5c61697d4e0c",
   "user_id":"809c85e8-e1ea-4545-9c6a-58664190d163",
   "recorded_at":"2017-04-06T22:59:44.465916Z",
   "type":"action.on_the_way",
   "data":{
      "object":{
         "id":"229a1aa9-0726-40fa-8a2e-c59f6ce79baf",
         "user":{
            "id":"809c85e8-e1ea-4545-9c6a-58664190d163",
            "group_id":null,
            "lookup_id":null,
            "name":"Toivo Pollari",
            "phone":null,
            "photo":"https://randomuser.me/api/portraits/men/54.jpg",
            "availability_status":"offline",
            "vehicle_type":"unknown",
            "pending_actions":[

            ],
            "last_location":{
               "geojson":{
                  "type":"Point",
                  "coordinates":[
                     -122.4640349,
                     37.7687697
                  ]
               },
               "recorded_at":"2017-04-07T06:49:33.787879+00:00"
            },
            "last_online_at":"2017-04-07T04:51:24.787879Z",
            "last_heartbeat_at":"2017-04-07T06:51:44.862080Z",
            "location_status":"location_available",
            "display":{
               "activity_text":"",
               "status_text":"Offline",
               "sub_status_text":"Last updated 36 minutes ago",
               "has_new_sdk":true,
               "is_warning":false
            },
            "created_at":"2017-04-06T13:01:32.181804Z",
            "modified_at":"2017-04-07T06:51:44.862723Z"
         },
         "type":"pickup",
         "vehicle_type":"unknown",
         "started_place":{
            "id":"a18ad5e1-4c3e-4b1a-8786-5b2cc6b035f9",
            "name":"",
            "location":{
               "type":"Point",
               "coordinates":[
                  -122.42813323979513,
                  37.80378573707798
               ]
            },
            "address":"1263 Bay St, San Francisco, CA 94123, USA",
            "landmark":"",
            "zip_code":"94123",
            "city":"SF",
            "state":"CA",
            "country":"US",
            "created_at":"2017-04-06T22:59:21.776499Z",
            "modified_at":"2017-04-06T22:59:21.776529Z"
         },
         "started_at":"2017-04-06T22:58:48.157260Z",
         "expected_place":{
            "id":"812fdbcc-31e8-44b3-8245-e5b7167c9407",
            "name":"",
            "location":{
               "type":"Point",
               "coordinates":[
                  -122.41729555196481,
                  37.76292051400294
               ]
            },
            "address":"637-659 S Van Ness Ave, San Francisco, CA 94110, USA",
            "landmark":"",
            "zip_code":"94110",
            "city":"SF",
            "state":"CA",
            "country":"US",
            "created_at":"2017-04-06T22:59:21.402646Z",
            "modified_at":"2017-04-06T22:59:21.402674Z"
         },
         "expected_at":null,
         "completed_place":null,
         "completed_at":"2017-04-07T00:38:37.362650Z",
         "assigned_at":"2017-04-06T22:59:21.500233Z",
         "suspended_at":"2017-04-07T00:24:51.602806Z",
         "canceled_at":null,
         "status":"completed",
         "eta":null,
         "initial_eta":"2017-04-06T23:17:40.782848Z",
         "short_code":"QynE7jlo",
         "tracking_url":"https://trck.at/QynE7jlo",
         "lookup_id":"HMKFO",
         "created_at":"2017-04-06T22:59:21.412968Z",
         "modified_at":"2017-04-07T00:38:37.362833Z",
         "display":{
            "duration_remaining":0,
            "status_text":"Completed",
            "sub_status_text":"",
            "show_summary":true
         }
      }
   },
   "created_at":"2017-04-06T22:59:44.466227Z"
}

results matching ""

    No results matching ""