Use of WebSockets - POS partners

Doshii's WebSocket service is how the POS and Partner Application stay in sync in real-time.

Our WebSocket connection is intended to represent a location (a single outlet or venue). As such each device, lets say an iPad in a venue does not need to connect individually to Doshii. This design is ideal for legacy, closed loop POS systems who do not have a web presence. Instead they typically have a local server at each site.

For cloud POS systems we do also only accept a single WebSocket connection for all locations, however there are vendor API features available that would allow you to control which location is online/offline.

Environments

Connection

Cloud POS Connection

Listening for Events

Environments

There are currently two environments available in establishing a connection to the Doshii WebSocket. If you're pre-launch (ie. don't have live credentials), that will be the sandbox environment. If you're a live integrator, it will be the aptly named liveenvironment.

// Sandbox
wss://socket.sandbox.doshii.co/pos/socket?token=

// Live
wss://socket.live.doshii.co/pos/socket?token=

With <token> representing the unique location token provided to you by Doshii.

Already using a different URL than above? Older naming patterns for the URL will continue to work.

Connection

Let's do the example in JavaScript. Those writing other languages will need to adapt the following to suit, guides for your language are coming soon.

Let's start by installing a couple of libraries you'll need to make the connection.

• WebSockets "ws" library for fast and easy WebSocket connection

yarn add ws
# Or for you NPMers
npm i -S ws

Now that's all done, let's establish a connection.

const WebSocket = require('ws');

const authToken = location.token;

// Establish a connection to the Doshii Sandbox WebSocket
const ws = new WebSocket('wss://socket.sandbox.doshii.co/pos/socket?token=' + authToken);

After you've connected to the Doshii WebSocket, you'll need to send heartbeats across every 30 seconds so that we know you're still listening.

ws.on('open', function(event) {
  function heartbeat() {
    const timestamp = Date.now();
    const posVersion = '1.2.3';
    const payload = JSON.stringify({
        doshii: {
            ping: timestamp,
            version: posVersion
        }
    });
    ws.send(payload);
  }

  heartbeat(); // Send one immediately to complete the handshake
  setInterval(heartbeat, 30000); // Then 30 every seconds or so thereafter to keep alive
});

It's a good idea to have some error handling in there too.

ws.on('error', function(err) {
  throw new Error('Doshii WebSocket error: ', err);
});

Cloud POS Connection

If you're a Cloud POS Vendor then your connection is slightly different as you no longer need to connect for each location. 

Sandbox URL wss://socket.sandbox.doshii.co/vendor/socket?token=<jwt>&vendor=<apiName> 
Live URL wss://socket.live.doshii.co/vendor/socket?token=<jwt>&vendor=<apiName> 

 The JWT token is built using the same technique described in POS Authentication with the only difference being the Vendor API Name is included rather than the location token.

"vendor": The POS Vendor API name
"timestamp": The current timestamp in EPOC-Seconds for validating the request expiry time, default is 10 minutes.

Listening for Events

Great! Now that you're connected and errors handled, how about we listen for some messages from the server?

ws.addEventListener('message', function(event) {
  if (!event) return;
  console.log(event.type);
  console.log(event.data);
}

The important parts of the event you'll receive are event.type and event.data. The event.type field stores the name of the event that corresponds with the list found in the POS API Reference. For example; order_created or transaction_updated. Generic messages such as the "pong" response to each of your "ping"s will have the message event type. The event.data field stores the relevant information of the event.

Here's a sample "pong" message event.

{
  type: 'message',
  data: {
        doshii: {
            pong: 1539144663417,
            version: '3.2.123'
        }
    },
  target:
    WebSocket {
      ... (connection information)
    }
}

A list of the WebSocket events can be found in the POS API Reference.