Websocket Protocol
Endpoint: wss://api.insiders.live/v1/ws/preprocessed-data/{device}/
Sent by the server upon reception of an update from the device. When the device is connected to both GNSS and network signal, updates are sent every second.
Server message
Sent by server.
Token message
Sent by client as an authorization attempt.
This message must be sent by the client within the first 3 seconds of the connection, otherwise the websocket connection will be closed.
Parameters (deprecated)
In addition to the token key in the authentication message, an optional params key can be specified.
By default, messages are forwarded to the WebSocket client as soon as they are ready, without any guarantee of arriving in the right order. This problem is inherent to the real-time and distributed architecture but can be mitigated by setting the parameters such that the messages are buffered and reordered first. If buffer_size is set to some value n > 0, the last n messages are held in the buffer and the oldest (according to its timestamp) is released when the buffer exceeds n messages. This ensures the right ordering of messages up to the last n messages. By default, buffer_size is set to 0 meaning that no buffering is performed.
Note: buffering n messages implies a delay of about n seconds.
If a message arrives that is older than the last forwarded message (meaning it is about n seconds late at least), it will still be forwarded unless drop_older is set to true, in which case it is simply dropped. Dropping these messages is the only way to completely guarantee the right order.
To ensure all messages are forwarded even after device disconnection, the buffer is flushed (in the right order) after flush_timeout seconds.
The following table explains the params utility
| Param | Possible values | Default | Description |
|---|---|---|---|
buffer_size | integer in [0,60] | 0 | Size of reordering buffer |
drop_older | true | false | false | Control if incoming message older than the last forwarded one should still be sent or dropped |
flush_timeout | integer in [2,62] | 10 | Timeout after which the messages in the buffer will be forwarded, should be greater or equal to buffer_size + 2 |
Note: in most cases, when messages arrive in wrong order without any params, it is just one message arriving right after its successor. So, a buffer of size 3 would cover a majority of cases, and the delay is not so big (~ 3 seconds)