Inband Objects

Inband objects enables clients to subscribe to LiveObjects updates in realtime, even on platforms that don't yet have a native LiveObjects Realtime client implementation.

Inband objects works by delivering changes to channel objects as regular channel messages, similar to inband occupancy. Two modes are available:

• objects streams the full state of channel objects as a sequence of messages on attach and whenever the state changes.
• notification sends a lightweight notification whenever the state changes, with a link to retrieve the full state via the REST API.

Objects mode

The objects mode streams the full state of channel objects to the client. On attach, the client receives a sequence of [meta]objects messages describing the complete set of objects on the channel. When objects are updated, the client receives additional messages with the updated state.

Enable objects mode

Enable objects mode using the objects channel parameter when getting a channel:

// When getting a channel instance
const channelOpts = { params: { objects: 'objects' } };
const channel = realtime.channels.get('my-channel', channelOpts);

// Or using setOptions on an existing channel
await channel.setOptions({ params: { objects: 'objects' } });

Subscribe to updates

The client receives [meta]objects messages whenever the objects on the channel are updated. These messages provide a snapshot of the current set of objects on the channel.

Subscribe to [meta]objects messages like you would any other message on the channel. For convenience, use a message name filter to only receive messages with the name [meta]objects in your listener:

// Subscribe to [meta]objects messages
channel.subscribe('[meta]objects', (message) => {
  const { syncId, nextCursor, object } = message.data;
  console.log("Received inband objects message:", syncId, nextCursor, JSON.stringify(message.data));
});

Message format

Inband objects messages are sent as a sequence of messages, where each message contains a snapshot of a single object on the channel. Taken together, a set of messages belonging to the same sequence describes the complete set of objects on the channel.

Each inband objects message has a message name of [meta]objects.

The message data is a JSON object with the following top-level properties:

The shape of the object is the same as the response format of an object when listing them via the REST API.

Notification mode

The notification mode sends a [meta]objects message whenever the channel objects are updated. The message contains a link to retrieve the current state via the REST API rather than the full object state.

Unlike objects mode, the client does not receive the initial state on attach. The first [meta]objects message is sent when the state changes.

Enable notification mode

Enable notification mode using the objects channel parameter with a value of 'notification':

const channelOpts = { params: { objects: 'notification' } };
const channel = realtime.channels.get('my-channel', channelOpts);

Subscribe to notifications

Subscribe to [meta]objects messages to receive notifications when channel objects are updated:

channel.subscribe('[meta]objects', (message) => {
  const { link } = message.data;
  console.log("Objects updated, retrieve state from:", link);
});

Notification message format

Each notification message has a message name of [meta]objects.

The message data is a JSON object with the following property: