Skip to main content

Messaging

Since you need to display logical informations (Sites, Operations, Routes, etc...), your application need to communicate these informations to the Map for rendering.

For this purpose, Axioroute expose a Map API.
Although you can use this API directly, this SDK is here to simplify the communication between your application and the Map.

Configuration​

The configuration is available for the whole application (as default connfiguration), but can be find tuned for each message.

Author​

First you need to identify the default Author of the messages for your app.

import { ARMessage } from "@axioroute-sinari/axioroute-sdk";
ARMessage.setAuthor("my-app");

If multiple apps may send messages to the map, it will be easier to identify them on map side (for debug purpose for example).

Note

This is only an identification. It has no security / role / permission purpose. Any app able to reach the map will be trusted. Security / Auth layers need to be implemented on your side and happened before that.

Targets​

This is the communication channel between your app and the map.
There are two main type of targets:

  • Iframe Window (via PostMessage): straightforward, simple but requires the map to be embedded within the client app itself
  • Websocket: more flexible, but requires a Websocket Server

Example with iframe:

See the Map Integration Section for the iframe setup. The code below assume you have it setup correctly with id my-app-map

ARMessage.setDefaultTarget({
  targetWindow: document.getElementById("my-app-map").contentWindow,
});

Example with websocket:

ARMessage.setDefaultTarget({
  socket: ARMessage.createSocket("ws://myapp.example.com"),
});

Recipients​

If you are using Websocket messaging, you may also need to set Recipients.
It's in case a single webserver is used with multiple apps / maps and you don't want all the messages to be listened by all apps/maps.

Let's say you have an App AppA that should communicate with a Map MapA and an App AppB that should communicate with a Map MapB through the same Websocket Server

Your App AppA should have the following line:

ARMessage.setDefaultRecipients(["MapA"]); //MapA is the Author Name of the Map

While your App AppB should have:

ARMessage.setDefaultRecipients(["MapB"]); //MapB is the Author Name of the Map

This way there will be no conflicts with both app messaging, even if they share the same websocket server.

Note

This is a client side filtering. This means that even if messages are broadcasted to all apps/maps using the same websocket server, message will be filtered after reception (and not before sending).

To prevent broadcasting all messages to all apps/maps, you can setup the same kind of filter server side.
There is an example for this in the Websocket Section

Message Content​

Message content is very flexible, to enable usage for any kind of purpose.
There is two requirements for their content

  • type: string (used to bind Message Listeners)
  • message: JSON formated Object (the payload of the message itself)

To know how to set or read the payload of your messages, please refer to the Map API guides and reference:

Sending Messages​

Here is an example using Messaging from your App to Set entities to be displayed on the Map:

const myAxiorouteState: {...}
ARMessage.send({
   type: "SET_WEBVIEW_ENTITIES",
      payload: myState,
  });

Listening to Messages​

The Map will send Messages back to your App like interactions, new Status, etc...
For example here is the first Message you'll have to listen before interacting with your Map:

ARMessage.on("MAP_READY", (message) => {
  //Do some operation on the Map
});