PubSub

PubSub documentation

PubSub service enable applications to subscribe to events on the FFS network.
It's a secure Websocket service accessible using this address: wss://pubsub-ffs.zerator.com or on the test server: wss://pubsub-ffs-test.zerator.com/

Each packets sended by the client or the server must be encoded in Json format. If a non-json or an unknown packet is sent to the server, the client will be disconnected.

The packet format looks like this:

{
  "type":"<packet_type>",
  ...
}

The packet_type variable represents the packet type. It will define wich type of packet we are processing.

The server needs a constant Hearthbeat from the client. The client must send a PING packet to the server at least every 30 seconds. The server will consider that the client has died if it didn't received the PING packet and will disconnect the client.
The server will respond PONG at each PING packet sended by the client. If the PONG packet is not received 5 seconds after the send of a PING request, you can consider the connection as timed out and reconnect the client to the server.

PING request format:

{
  "type":"PING"
}

PONG request format:

{
  "type":"PONG"
}

Subscribing to topics

As you use the PubSub service to subscribe to an event, it's important to know how to subscribe to events!
The format for the Subscription packet looks like this:

{
  "type":"SUBSCRIBE",
  "nonce":"ZdsLMadsqLMkdaz",
  "topics":["event-score-v1.4242"],
  "auth_token":"AUTH_TOKEN"
}

and has to be sent from the client to the server when needed.
nonce represents a random string used to identify the response associated with this request. Must be generated by the client.
topics is the list of topics you want to subscribe to. auth_token some topics will need an authentication process. This variable must contain the authentication token generated by the API. If it's not needed by any of the topics, it can be ignored.

The server's response for this Subscribe request will look like this:

{
  "type":"RESPONSE",
  "nonce":"ZdsLMadsqLMkdaz",
  "error":null
}

nonce the nonce provided by the client.
error if there is an error, this variable will take thoes values: ERR_BADMESSAGE, ERR_BADAUTH, ERR_SERVER, ERR_BADTOPIC

To unsubscribe from events, simply use this packet format:

{
  "type":"UNSUBSCRIBE",
  "nonce":"DSlkdzaDSQlka",
  "topics":["event-score-v1.4242"]
}

Available topics

Topic	Require Auth	Receive message when
event-score-v1.<event_id>	false	A score value is updated

Receiving events

When an event for your subscription is raised, you will receive a MESSAGE packet.
This packet format looks like:

{
  "type":"MESSAGE",
  "data": {
    "topic":"<topic>",
    "message":"<JSON blob>"
  }
}

Example with a event-score-v1 message:

{
  "type":"MESSAGE",
  "data": {
    "topic":"event-score-v1.4242",
    "message":"{\"event_id\":42,\"round_id\":42,\"user_id\":42,\"score\":42}"
  }
}

event_id represents the event's ID.
round_id represents the round's ID.
user_id represents the user's ID.
score represents the new score value for this score entry in the event.