Fleet Freedom
Main Site
Overview
WebSocket
JavaScript
Behaviours
Provisioning
Pictures
Reports
Events
Return to site

Getting Started

Guide
Tuesday, September 1, 2015
By Alex Lein

WebSocket is a protocol that provides full-duplex communication channel between a client and a server over single TCP connection. We only use the secure connection protocol wss://, not the insecure ws:// protocol.

WebSocket Address

The WebSocket is exposed on ports 443 (standard WSS communication port) and on the unused port 40,000 for spacial cases.

wss://socket.fleetfreedom.com/ghostId
and/or
wss://socket.fleetfreedom.com:40000/ghostId

Establishing a connection

To establish a connection with the WebSocket server, the client must send a request to wss://socket.fleetfreedom.com/ghostId where ghostId is blank, or your session identifier (described below).

Using JavaScript, creating a connection is as simple as:

var socket = new WebSocket("wss://socket.fleetfreedom.com/ghostId");

However, the socket server is not ready for commands until you receive a connectionResponse message.

connectionResponse {
  "errorCode": number, /* one of the ErrorCode values */
  "message": string,
  "serverTime": string, /* datetime format */
  "ghostId": string,
  "expiry": string, /* datetime format */
  "user": { /* see User for details */ },
  "sessionPolicy": { /* see SessionPolicy for details */ },
  "passwordPolicy": { /* see PasswordPolicy for details */ }
}

Fields that are always returned:

errorCode
Code that is assigned to a specific error. Refer to list of Error Codes below.
message
Message that describes the error.
serverTime
The current time on the server
ghostId
Unique session identifier generated by the server.
expiry
String representation of the session expiration time.

Optional fields that are returned only if the user has logged-in:

user
An object that represents the current session user
sessionPolicy
An object that represents the session policy of the current user's company.
passwordPolicy
An object that represents the password policy of the current user's company.

Logging in

If you do not provide a valid ghostId when connecting, then after receivig the connectionResponse message, you need to send a login command.

socket.send("login " + JSON.stringify({
  "reqId": 1,
  "username": "email@address.com",
  "password": "password",
  "userAgent": "a short name to identify your application"
}));

When successful, the loginResponse message contains all the same important information as the connectionResponse, including your valid ghostId.

Sending commands

The client must wait for the connectionResponse message from the server, before sending any further messages.

All commands can optionally use the reqId key to associate requests with responses. In addition, each response message will always contain the keys errorCode, and message.

  1. All get<Type> and remove<Type> commands require the request object to contain a key of the type, with the value of a JSON object with the correct id.
  2. All merge<Type> commands require the request object to contain a key of the type, with the value of a JSON object with the correct id, and the correct v value.
  3. All messages sent to and from the server are strings with following format:

Request format

cmdName<space>{JSON}

Request example

getCompany {
  "reqId": 1,
  "company": {
    "id": 42
  }
}

Response format

cmdNameResponse<space>{JSON}

Response example

getCompanyResponse {
  "reqId": 1,
  "errorCode": 0,
  "message": "Company retrieved",
  "company": Company
}

Using JavaScript, sending a command is as simple as:

socket.send("getCompany " + JSON.stringify({ "reqId": 1, "company": { "id": 42 } }));

For a list of all supported commands, please see the command reference.

Synchronization messages

The client can receive a constant feed from the server by subscribing to any of the SubscriptionTypes for a particular company. These subscriptions are per-company, not global to all companies.

There are two types of synchronization messages sent from the server:

Merged messages

Sent when an object is changed by you, another user, a behaviour script, or by some other system.

Format

<type>Merged {JSON}

Deleted messages

Sent when an object is deleted by you, another user, a behaviour script, or by some other system.

Format

<type>Deleted { "id": number, "company": number }

To subscribe to specific synchronization message types, send a subscribe command. For example:

Request

subscribe {
  "reqId": 2,
  "company": {
    "id": 42
  },
  "subscriptionTypes": [
    "assetGeneral",
    "assetAdvanced"
  ]
}

Response

After you receive your subscribeResponse, you begin to receive synchronization messages for those subscriptions.

assetDeleted { "id": 123456, "company": 42 } assetGeneralMerged { /* AssetGeneral */ } assetAdvancedMerged { /* AssetAdvanced */ }

For a list of all supported subscription types, please see the subscription reference.

You can also use the v property of all synchronized objects to see if the version you've received from the server is more recent than the version you have in your cache. In the case of complex objects like assets, providers, and users, the general version flag is always the first number in the v array, and the advanced is always the second. Companies follow the order: general, billing, directory, labels and tags, then policies.

  • Back to Websocket Articles
  • Full Websocket Reference
Trak iT® Wireless and Fleet Freedom® are Trademarks of Trak iT® Wireless Inc.
All content contained within this site is the property of Trak iT® Wireless unless otherwise stated.