Use of WebSockets - App partners

Connecting to the Doshii WebSocket Service is a vital point in the API process flow. It allows you to receive events from the POS in real-time rather than continuously "long" polling the server to find updates.

The following examples are using NodeJS.

Environments

Connection

Best practices

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 live environment.

// Sandbox
wss://socket.sandbox.doshii.co/app/socket?auth=<<authToken>>

// Live
wss://live-socket.doshii.co/app/socket?auth=<<authToken>> 

With <authToken> representing the base64 encoding of YOUR_DOSHII_CLIENT_ID

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

Connection

Here's a JavaScript guide for you on how to establish the connection with Doshii. Those writing other languages will need to adapt the following to suit, guides for your language are coming soon. Further details around the connection can be found here.

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
• btoa library. It turns binary data to base64-encoded ascii.

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

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

var WebSocket = require('ws');
var btoa = require('btoa');

var authToken = btoa(YOUR_DOSHII_CLIENT_ID);

// Establish a connection to the Doshii Sandbox WebSocket
var ws = new WebSocket('wss://socket.sandbox.doshii.co/app/socket?auth=' + 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 appVersion = '1.2.3';
    const payload = JSON.stringify({
        doshii: {
            ping: timestamp,
            version: appVersion
        }
    });
    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);
});

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 Partner 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 Partner API Reference.

Best practices

• Use appropriate GET requests with limited parameters (ie: to/from) to retrieve any events potentially missed since last connection.
• Keep the socket channel open for subsequent events whilst processing the first on a background/asynchronous thread.
• Use the full uri parameter/attribute of events to reference the entity to which an event pertains (rather than by id).