diff --git a/src/pages/docs/channels/options/index.mdx b/src/pages/docs/channels/options/index.mdx index a6e2f99999..4b491b1260 100644 --- a/src/pages/docs/channels/options/index.mdx +++ b/src/pages/docs/channels/options/index.mdx @@ -430,7 +430,7 @@ Occupancy events have a payload in the `data` property with a value of `occupanc ### Inband Objects -[Inband objects](/docs/liveobjects/inband-objects) allows clients to subscribe to changes to [LiveObjects](/docs/liveobjects) channel objects as regular channel messages. +[Inband objects](/docs/liveobjects/inband-objects) allows clients to subscribe to changes to [LiveObjects](/docs/liveobjects) channel objects as regular channel messages. Set the `objects` channel parameter to `'objects'` to stream the full state, or `'notification'` to receive change notifications. When using inband objects, the client receives messages with the special name `[meta]objects` that describe the current set of objects on a channel. diff --git a/src/pages/docs/liveobjects/concepts/billing.mdx b/src/pages/docs/liveobjects/concepts/billing.mdx index a4d0420107..580954e5cd 100644 --- a/src/pages/docs/liveobjects/concepts/billing.mdx +++ b/src/pages/docs/liveobjects/concepts/billing.mdx @@ -157,9 +157,9 @@ await myObject.get('visits').batch((ctx) => { ## Synchronization -During initial synchronization and resynchronization, each object on the channel is sent as a message. +During initial synchronization and resynchronization, each object on the channel is sent as one or more messages. Large objects, such as maps with many entries, may be split across multiple messages. -For example, if a channel contains 10 objects (such as `LiveMap` and `LiveCounter` instances), a client attaching to the channel will receive 10 messages during synchronization. +For example, if a channel contains 10 objects (such as `LiveMap` and `LiveCounter` instances), a client attaching to the channel will receive at least 10 messages during synchronization. Similarly, if a client becomes disconnected and needs to resynchronize, it will receive messages for each object that needs to be synchronized. diff --git a/src/pages/docs/liveobjects/concepts/synchronization.mdx b/src/pages/docs/liveobjects/concepts/synchronization.mdx index c1c28a28b0..2820461e8c 100644 --- a/src/pages/docs/liveobjects/concepts/synchronization.mdx +++ b/src/pages/docs/liveobjects/concepts/synchronization.mdx @@ -41,7 +41,7 @@ When a channel first becomes active in a region, the channel loads the object da While Ably maintains the source of truth on the channel, each connected client keeps a local representation of the objects on the channel. -When the client first attaches to the channel, the state of the channel objects is streamed to the client. [Lifecycle events](/docs/liveobjects/lifecycle#synchronization) allow your application to be notified when the local state is being synchronized with the Ably service. +When the client first attaches to the channel, the state of the channel objects is streamed to the client. Large objects, such as maps with many entries, may be delivered across multiple messages during synchronization. [Lifecycle events](/docs/liveobjects/lifecycle#synchronization) allow your application to be notified when the local state is being synchronized with the Ably service. -Inband objects works by delivering changes to channel objects as regular channel messages, similar to [inband occupancy](/docs/channels/options#occupancy). +Inband objects works by delivering changes to channel objects as regular channel messages, similar to [inband occupancy](/docs/channels/options#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](/docs/liveobjects/rest-api-usage). -## Enable Inband Objects + + +## 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. -To enable inband objects, use the `objects` [channel parameter](/docs/channels/options#objects) when getting a channel: +### Enable objects mode + +Enable `objects` mode using the `objects` [channel parameter](/docs/channels/options#objects) when getting a channel: ```javascript @@ -58,13 +69,9 @@ await channel.setOptions({ params: { objects: 'objects' } }); ``` - - -## Subscribe to updates +### Subscribe to updates -When using inband objects, the client will receive special `[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. +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.