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:

To enable inband objects, use the objects channel parameter when getting a channel. Set the value to either objects or notification depending on which mode you want to use:

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

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

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

Limitations

Inband objects has some constraints to be aware of when designing your application.

Maximum object size

Individual objects sent via inband objects mode cannot exceed the maximum message size limit (64KB by default). If an object's size exceeds this limit, then no inband object messages will be received on the connection and the sync sequence will fail with an error.

Inband objects are delivered as regular channel messages, which are subject to the standard message size constraints.

To avoid hitting this limit when using inband objects:

• Keep individual object sizes small by distributing data across multiple objects
• Consider using notification mode and fetching large objects via the REST API on demand

Subscribe to updates

The client receives [meta]objects messages whenever the objects on the channel are updated.

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) => {
  console.log("Received inband objects message:", JSON.stringify(message.data));
});

Objects mode

The objects mode sends the full state of all objects on the channel. When a client attaches to the channel, it immediately receives the current state. Subsequent updates are sent whenever the objects change.

Enable objects mode

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

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

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

Objects 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:

Inband Counter Message

{
  "name": "[meta]objects",
  "data": {
    "syncId": "1148d241",
    "nextCursor": "root",
    "object": {
      "objectId": "counter:APjeaY7i_IQmrlxV5sEcR7NLTualutgS1QF3wNVJNYI@1769502401136",
      "counter": {
        "count": 12
      },
      "siteTimeserials": {
        "cbf": "01769502451073-000@cbfpt5aQQByRKW13548557:000"
      },
      "tombstone": false
    }
  }
}

Inband Map Message

{
  "name": "[meta]objects",
  "data": {
    "syncId": "95ad3a9f",
    "object": {
      "objectId": "root",
      "map": {
        "semantics": 0,
        "entries": {
          "hello": {
            "timeserial": "01769446125853-000@cbfpt5aQQByRKW61375059:000",
            "data": {
              "string": "world"
            },
            "tombstone": false
          },
          "votes": {
            "timeserial": "01769502401144-000@cbfpt5aQQByRKW13548557:001",
            "data": {
              "objectId": "counter:APjeaY7i_IQmrlxV5sEcR7NLTualutgS1QF3wNVJNYI@1769502401136"
            },
            "tombstone": false
          }
        }
      },
      "siteTimeserials": {
        "cbf": "01769446125853-000@cbfpt5aQQByRKW61375059:000"
      },
      "tombstone": false
    }
  }
}

Notification mode

The notification mode sends a [meta]objects message whenever the channel objects are updated, without sending the full state data. This reduces bandwidth for use cases where clients only need to know that an operation occurred and can fetch the state on demand.

Unlike objects mode, notification mode does not send an initial state when the client attaches to the channel. The first notification is sent immediately when the first object operation is received. The message contains a link to retrieve the current state via the REST API rather than the full object state.

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);

Notification message format

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

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

// Subscribe to [meta]objects messages in notification mode
channel.subscribe('[meta]objects', async (message) => {
  const { link } = message.data;
  console.log("Objects operation received, fetching state from:", link);

  // Fetch the current state using the REST API
  const response = await ablyREST.request('GET', link);
  if (response.items.length > 0 ) {
    console.log("Current state:", response.items[0]);
  }
});

When to use objects or notification mode

Use notification mode when:

• You want to minimize bandwidth usage and only fetch state when needed.
• Your application can tolerate fetching state on demand rather than receiving it immediately.
• You have infrequent operations and don't need continuous state updates.

Use objects mode when:

• You need the full state immediately on attach.
• You want to receive state updates in realtime without additional REST API calls.
• Your application requires continuous synchronization of state.