@vinka/viper-api v1.3.2
Vinka Driver App API
WebSocket Events
Login
Not a real login in the sense that there is no authentication but this message is used for sending the vehicle number to the server. This event needs to be resent every time the socket connection drops and re-establises. So, clients should do something like this in their Socket.io initialization code:
socket.on('connect', async () => {
try {
await login();
} catch (e) {
// login failed
}
});
async login() {
return new Promise((res, rej) => {
socket.on('loginOk', res);
socket.emit('login', {vehicleNumber: 1});
});
}
- key:
login
- direction: client -> server
- payload:
export interface Login {
vehicleNumber: number,
}
Upon successful login, the server will send following message:
- key:
loginOk
- direction: server -> client
- payload: no payload
Error:
- key:
loginError
- direction: server -> client
Get Itinerary
Client may use this request to get the current itinerary from server.
- key:
getItinerary
- direction: client -> server
- payload: no payload
Client requests current itinerary. Server will respond with itinerary
event.
- key:
itinerary
- direction: server -> client
- payload: list of
ItineraryItem
s. Note that the list is ordered by time, so there should be no need to sort the list on the client. See definition below:
Error:
- key:
getItineraryError
- direction: server -> client
export interface Rider {
firstName: string,
lastName: string,
}
export interface Address {
lat: number;
lng: number;
street: string;
streetNumber: string;
city: string;
}
export interface ItineraryItem {
itemId: number; // unique id among all items in the itinerary list
itemType: string; // "stop", "break-start", "break-end", "shift-start", "shift-end"
itemAction: string; // stops: "pick", "drop", breaks and shifts: "start", "end"
entityId: number; // entity's (stop, break, shift) own id
status: string;
plannedTime: string;
}
export interface StopItem extends ItineraryItem {
tripId: number;
routeId: number;
passenger: Rider;
address: Address;
eta: string;
}
export interface BreakItem extends ItineraryItem {
eta: string;
}
export interface ShiftItem extends ItineraryItem {
}
Itinerary Update
- key:
itineraryUpdate
- direction: server -> client
- payload: top level properties are:
upsertedItems
: these items are either new or existing items that are being updated. Content of this property is the same as initinerary
event. The list is sorted by time.removedItems
: these items have been removed from the itinerary. Each item is
export interface RemovedItineraryItem {
itemType: string; // "stop", "break-start", "break-end", "shift-start", "shift-end"
itemId: number; // unique id among all items in the itinerary list
entityId: number; // entity's (stop, break, shift) own id
}
Send Location
Vehicle should send the location to server periodically.
- key:
location
- direction: client -> server
- payload
export interface GpsData {
lat: number;
lng: number;
timestamp: string;
accuracy: number;
speed: number;
bearing: number;
}
export interface Location {
vehicleNumber: number;
routeId: number; // null if not on a route at the moment (between routes)
vehicleTime: string; // device's time
gps: GpsData;
}
Send Stop Perform
When driver performs (or arrives to) a stop, this event should be sent.
- key:
stopPerform
- direction: client -> server
- payload
export interface Perform {
itemType: string; // "stop", "break-start", "break-end", "shift-start", "shift-end"
itemId: number; // optional
entityId: number; // stop id (required)
status: string; // "arrived", "performed", "no-show"
vehicleTime: string;
gps: GpsData;
}
Request Last Location
This event is mainly for simulations. Vehicle may use this event to request its last recorded location. This is a handy way for simulated vehicles to resume driving from their last location if the service has been restarted.
- key:
getLastLocation
- direction: client -> server
- payload: no payload
The server will respond with following message:
- key:
lastLocation
- direction: server -> client
- payload: the
GpsData
Error:
- key:
getLastLocationError
- direction: server -> client
Errors
In case an operation fails (e.g. getItinerary
) fails, server sends and event
with Error
suffix (e.g. getItineraryError
) and following payload:
export interface Error {
code: string,
description: string,
}
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago