Real-time Events API Quick Reference

Real-time events are consumed using a Websockets API. Open a websocket connection using socket.io to get a real-time notification of events, including real-time location.

Using Websockets

Connect to the Websocket API at https://events.vehiclemind.com by passing a token parameter in the query string that has the Client ID and Client Secret separated by a colon (:).

For example, if the client ID is 1234 and the client secret is 9876, the url to connect to is https://events.vehiclemind.com?token=1234:9876.

Using socket.io, listen for any event type that the application needs and listen for error messages.

Websocket URL

https://events.vehiclemind.com?token={client_id}:{client_secret}

Example Listener in Javascript

var io = require('socket.io-client')

var socket = io('https://events.vehiclemind.com?token={client_id}:{client_secret}')

// Listen for``trip:finished`` event
socket.on('`trip:finished`', function(eventJSON) {
  console.log('Trip Finished', eventJSON);
});

// Handle`error` messages
socket.on('error', function(errorMessage) {
  console.log('Error', errorMessage);
});

Timeliness and Delivery

Timeliness Caveats

We will generally try to send an event when that event happens, in real-time. But in some cases events may fire much later, e.g. when an active internet connection is not available in an underground parking lot. In that case, a trip is uploaded to our servers only well after the trip took place. The associated trip:finished event would only be sent once our server received the trip, which could be hours or days later.

If a user hasn't uploaded data for a while, we may end up sending many trip:finished events in rapid succession. It is imperative that the application inspect the timestamp of each event and react appropriately. In the case of trip:finished, e.g., this would be the embedded trip object's started_at and ended_at fields.

False Negative Caveats

Other events, however, may never be sent via websockets at all under certain situations, where the time-window of sending them no longer makes sense. ignition:on is one such event. If our servers don’t receive an event within a few minutes of it happening, and instead receive it hours or days later, we will not attempt to send it via a webhook or over a websocket. Specific time limits are stated in each event’s description.

False Positive Caveats

There are some drive events which will be sent via a webhook or over a websocket in real-time but which will be later filtered out by our trip processing algorithm and thus not make it to the REST object. The events which are filtered out are considered invalid for a variety of reasons and should not count against a behavioral assessment.

Delivery Caveats

When we attempt to send an event, we have no way to guarantee that the application will receive it. We also cannot guarantee that the application will receive an event only once. De-duplication logic should be built into the application to ensure that events are not duplicated on the same trip. See the Expected Response section for more info.