Websocket

One of the channel by which Apps and Maps can communicate is Websocket.

It has some advantages over the PostMessage channel:

• It can be used outside of web browser context (like a desktop application without webview)
• It enables multiple Apps to communicate with a single Map, or single App with multiple Maps and even a mix of that

Its main constraint is that it requires a Websocket server to be running.

Since it requires additional setup, we advise you to use Window PostMessage channel if you don't earn any benefit from advantages listed above

Websocket Server

A websocket Server is a server that can handle websocket connections initiated by the clients (Apps and Maps).

Here is a sample implementation of a Websocket Server in NodeJS (but you can create a websocket server a lot of other languages), that will be fine to use with your local development team but that could need some tuning to be used in production.

minimal-websocket-server.js

ws = require("ws");
const port = "5179"; // use any available port

wsServer = new ws.Server({ port });
wsServer.on("connection", function (socket) {
  socket.on("message", function incoming(message) {
    try {
      wsServer.clients.forEach(function (client) {
        client.send(message.toString());
      });
    } catch (e) {}
  });
});

To run your server just run node minimal-websocket-server.js in your terminal.

Recipients

If you are using Websocket messaging, you also need to set Recipients.
Recipients are Apps and Maps that should receive a given message.

You can have a better understanding of recipients from the Messaging Section

If left empty all clients connected to the websocket server will receive the messages (if you use the implementation above).

You can also filter recipients server side with a more advanced implementation of the websocket server, like the one below:

filtered-websocket-server.js

ws = require("ws");
const port = "5179"; // use any available port

let clientsDictionnary = {};
wsServer = new ws.Server({ port });
wsServer.on("connection", function (socket) {
  socket.on("message", function incoming(message) {
    try {
      const messageObject = JSON.parse(message.toString());
      const { type, author, recipients } = messageObject;

      //we register the client when we receive "AUTH" message type
      if (type === "AUTH") {
        clientsDictionnary[author] = socket;
      }

      //instead sending to all clients, we only send messages to the registered clients within the recipient list
      if (recipients.length > 0) {
        const recipientClients = recipients.map((r) => clientsDictionnary[r]);

        const clients = recipientClients;

        clients.forEach(function (client) {
          client.send(message.toString());
        });
      }
    } catch (e) {}
  });
});

To run your server just run node filtered-websocket-server.js in your terminal.

Note

With the implementation above, recipients have become mandatory.
It's totally up to you to decide if you want to use a more advanced implementation of the websocket server or not based on your needs.

Register Client

In the Webserver implementation above we register clients when we receive a message of type "AUTH". This is mandatory to be able to send messages to a given client.

Axioroute SDK provides a helper to register clients:

ARMessage.authSocket();