Skip to main content

connect

Opens a socket.io connection and returns the Socket. Sign the user in first; see Authentication for what the socket currently receives.

Description​

The server sends every message on the socket.io event notification, for events that have the WebSocket option enabled in the Events module.

Each message has message (the event's message text) type (product, order, user, form or refund) and, except for workflow notifications, attributes (the event's own attributes). Product events add product (id, status, info with the localized title, and attributes). Order events add order (id, attributes) and user. User events add user (notificationData, attributes). Form events (reply or status mode) add email and formData. Refund events add user and refund (id, amount, note, sessions). Notifications sent from a workflow have type: "notification" and the event marker in eventIdentifier.

Attributes are keyed by attribute marker; each value is an object with identifier, type and value fields.

Examples​

Minimal example​

// connect() is synchronous: don't await it.
const socket = WS.connect();

// The server emits every message on the 'notification' event.
socket.on('notification', (payload) => {
  console.log(payload);
});

socket.io-client is imported the first time connect() is called, so it stays out of bundles that never open a socket. Handlers you register on the returned socket right away are queued and replayed before the connection can deliver anything, so no event is lost. See Bundle Size & Module Formats.

Product example​

{
  "message": "Product updated",
  "type": "product",
  "attributes": {},
  "product": {
    "id": 10,
    "info": {
      "title": "Pink Planet"
    },
    "status": {
      "identifier": "available",
      "info": {
        "title": "ADD TO CART"
      }
    },
    "attributes": {
      "currency": {
        "identifier": "currency",
        "type": "string",
        "value": "USD"
      }
    }
  }
}

User example​

{
  "message": "Profile updated",
  "type": "user",
  "attributes": {},
  "user": {
    "notificationData": {
      "email": "john@example.com",
      "phonePush": [],
      "phoneSMS": "+12025550147"
    },
    "attributes": {}
  }
}

Order example​

{
  "message": "Order status changed",
  "type": "order",
  "attributes": {},
  "user": {
    "notificationData": {},
    "attributes": {}
  },
  "order": {
    "id": 1,
    "attributes": {}
  }
}

Form example​

{
  "message": "Your application was approved",
  "type": "form",
  "email": "john@example.com",
  "attributes": {},
  "formData": {}
}

Example notification payload​

connect() returns a socket.io Socket; the example and schema below describe the payload of a notification event.

{
    "message": "Message",
    "type": "product",
    "attributes": {
      "company": {
        "identifier": "company",
        "type": "string",
        "value": "OneEntry"
      }
    }
}

Response schema​

Schema: notification payload

message: string
Message text set for the event; an empty string if none.
example: "Message"

type: string
Source of the event: product, order, user, form, refund, or notification for workflow notifications.
example: "product"

attributes: Record<string, any>
Attributes of the event, keyed by marker.
example:

{
  "company": {
    "identifier": "company",
    "type": "string",
    "value": "OneEntry"
  }
}