From d62366f321778c72d0557a0c7282cf4b36981acb Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 17:08:19 +0100 Subject: [PATCH 1/6] Chat: Updated the chat docs for the single room migration --- content/chat/connect.textile | 12 ++------ content/chat/rooms/index.textile | 41 ++++++++-------------------- content/chat/rooms/presence.textile | 9 ++---- content/chat/rooms/reactions.textile | 4 --- content/chat/rooms/typing.textile | 4 --- content/chat/setup.textile | 12 ++++++-- 6 files changed, 25 insertions(+), 57 deletions(-) diff --git a/content/chat/connect.textile b/content/chat/connect.textile index c2036095c0..ea198448b5 100644 --- a/content/chat/connect.textile +++ b/content/chat/connect.textile @@ -144,7 +144,7 @@ If a client briefly loses connection to Ably, for example when driving through a During periods of discontinuity greater than 2 minutes then you will need to take steps to recover any missed messages, such as by calling "history":/docs/chat/rooms/history. blang[javascript,swift,kotlin]. - Each feature of the Chat SDK provides an @onDiscontinuity()@ handler to assist with this. These methods enable you to register a listener that will be notified when discontinuity occurs in that feature so that you can handle it, as needed. + The Chat SDK provides an @onDiscontinuity()@ handler exposed via the Room object to assist with this. This method enables you to register a listener that will be notified when discontinuity occurs in the room so that you can handle it, as needed. blang[react]. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a listener to be notified of, and handle, periods of discontinuity. @@ -152,7 +152,7 @@ blang[react]. For example, for messages: ```[javascript] -const { off } = room.messages.onDiscontinuity((reason?: ErrorInfo) => { +const { off } = room.onDiscontinuity((reason?: ErrorInfo) => { // Recover from the discontinuity }); ``` @@ -207,10 +207,4 @@ blang[react,swift]. blang[react]. blang[javascript,swift,kotlin]. - The following discontinuity handlers are available: - - * "Messages":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#onDiscontinuity"Messages":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages - * "Presence":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#onDiscontinuity"Presence":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence - * "Occupancy":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#onDiscontinuity"Occupancy":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy - * "Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#onDiscontinuity"Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing - * "Room reactions":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#onDiscontinuity"Room reactions":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions + The discontinuity handler is accessible via the "Room":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#onDiscontinuity"Room":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room object. diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 794656727e..a040a65c7d 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -11,11 +11,9 @@ languages: Rooms are used to organize and logically separate your users and chat messages into 'rooms'. They are the entry object into using chat and provide access to all other chat features, such as messages, online status and typing indicators. A room can represent a 1:1 chat between an agent and a customer, a private message between two users in a chat application, a large group conversation, or the chat section of a livestream with thousands of users. -You also control which features are enabled in a room when you create one. For instance, you might only want to utilize typing indicators in direct messages between users. - h2(#create). Create or retrieve a room -Users send messages to a room and subscribe to the room in order to receive messages. Other features, such as indicating which users are online, or which users are typing are configured as part of a room's options. +Users send messages to a room and subscribe to the room in order to receive messages. Other features, such as indicating which users are online, or which users are typing can be configured as part of a room's options. blang[javascript,swift,kotlin]. A @room@ is created, or an existing one is retrieved from the @rooms@ collection using the "@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#get"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/get%28roomid%3Aoptions%3A%29"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-rooms/get.html method: @@ -23,19 +21,19 @@ blang[javascript,swift,kotlin]. blang[react]. The "@ChatRoomProvider@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatRoomProvider.html provides access to a specific chat room to all child components in the component tree. - Pass in the ID of the room to use, and select which which additional chat features you want enabled for that room. This is configured by passing a "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html object to the provider. + Pass in the ID of the room to use. If you need to provide further feature configuration, such as enabling occupancy messages, you can pass in an optional "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html object to the provider. ```[javascript] -const room = await chatClient.rooms.get('basketball-stream', AllFeaturesEnabled); +const room = await chatClient.rooms.get('basketball-stream', {occupancy: {enableEvents: true}}); ``` ```[react] import * as Ably from 'ably'; -import { ChatClientProvider, ChatRoomProvider, LogLevel, AllFeaturesEnabled } from '@ably/chat'; +import { ChatClientProvider, ChatRoomProvider, LogLevel } from '@ably/chat'; const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: 'clientId' }); const chatClient = new ChatClient(realtimeClient); @@ -45,7 +43,7 @@ const App = () => { @@ -70,12 +68,9 @@ blang[react]. blang[javascript,swift,kotlin]. - When you create or retrieve a room using @rooms.get()@, you need to choose which additional chat features you want enabled for that room. This is configured by passing a "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room-options/index.html object as the second argument. In addition to setting which features are enabled, @RoomOptions@ also configures the properties of the associated features, such as the timeout period for typing indicators. + When you create or retrieve a room using @rooms.get()@, you can provide custom configuration for some features for that room by passing a "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room-options/index.html object as the second argument. If you do not provide a @RoomOptions@ object, the default settings will be used. ```[javascript] - const presence = {enter: false}; - const reactions = {}; - const occupancy = {}; const typing = {timeoutMs: 5000}; const room = await chatClient.rooms.get('basketball-stream', {presence, reactions, typing, occupancy}); ``` @@ -95,29 +90,15 @@ blang[javascript,swift,kotlin]. val room = chatClient.rooms.get(roomId = "basketball-stream", options = options) ``` -blang[javascript]. - You can also use the @AllFeaturesEnabled@ property for each @RoomOption@ to configure whether preconfigured example settings should be used: - - ```[javascript] - const room = await chatClient.rooms.get('basketball-stream', {presence: AllFeaturesEnabled.presence}); - ``` - - Or configure each feature using your own values: - - ```[javascript] - const room = await chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}}); - ``` - blang[react,swift,kotlin]. -Enable each feature using its associated option. The details of the options available to each feature are documented on their respective pages: +The details of the options available to each feature are documented on their respective pages: blang[javascript]. | Feature | @RoomOption@ | Default settings | - | "Presence":/docs/chat/rooms/presence | @presence@ | @AllFeaturesEnabled.presence@ | - | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @AllFeaturesEnabled.occupancy@ | - | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @AllFeaturesEnabled.typing@ | - | "Room reactions":/docs/chat/rooms/reactions | @reactions@ | @AllFeaturesEnabled.reactions@ | + | "Presence":/docs/chat/rooms/presence | @presence@ | @DefaultRoomOptions.presence@ | + | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @DefaultRoomOptions.occupancy@ | + | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @DefaultRoomOptions.typing@ | blang[swift,kotlin]. | Feature | @RoomOption@ | Default settings | @@ -130,7 +111,7 @@ h3(#release). Release a room Releasing a room allows the underlying resources to be garbage collected or released. -Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it is may be more beneficial. +Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it may be more beneficial. blang[javascript,swift,kotlin]. Once "@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#release"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/release%28roomid%3A%29"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-rooms/release.html has been called, the room will be unusable and a new instance will need to be created using "@rooms.get()@":#create if you want to reuse it. diff --git a/content/chat/rooms/presence.textile b/content/chat/rooms/presence.textile index 01d55510b8..f582851370 100644 --- a/content/chat/rooms/presence.textile +++ b/content/chat/rooms/presence.textile @@ -11,10 +11,6 @@ languages: Subscribe to the online status of room members using the presence feature. Presence enables you to show which members are currently online, indicate when a user goes offline, and have users optionally set additional information about their profile, or their current status within the application. - - h2(#subscribe). Subscribe to presence blang[javascript,swift,kotlin]. @@ -300,13 +296,12 @@ The following options can be set when "creating a room":/docs/chat/rooms#create blang[javascript]. |_. Property |_. Description |_. Default | - | enter | Set whether the client has permissions to enter the presence set. Calling @presence.enter()@ is still required. | true | - | subscribe | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true | + | enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true | blang[react]. |_. Property |_. Description |_. Default | - | subscribe | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true | + | enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true | h2(#retrieve). Retrieve the presence set diff --git a/content/chat/rooms/reactions.textile b/content/chat/rooms/reactions.textile index dbf8a9fa15..07c0d92e52 100644 --- a/content/chat/rooms/reactions.textile +++ b/content/chat/rooms/reactions.textile @@ -13,10 +13,6 @@ Users can send reactions to the entire chat room to show their sentiment as to w Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time. - - h2(#subscribe). Subscribe to room reactions blang[javascript,swift,kotlin]. diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index 129f9b86af..af0b57fc0b 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -11,10 +11,6 @@ languages: Typing indicators enable you to display which users are currently writing a message in a room. This feature can be used to display a message such as __Sandi is typing...__, or when a certain threshold is reached you could instead display __Multiple people are typing...__ or _12 people are typing..._. Typing events are emitted whenever a user starts or stops typing. - - h2(#subscribe). Subscribe to typing events blang[javascript,swift,kotlin]. diff --git a/content/chat/setup.textile b/content/chat/setup.textile index a41901ab65..4b5ee7f12d 100644 --- a/content/chat/setup.textile +++ b/content/chat/setup.textile @@ -20,7 +20,7 @@ h2(#authentication). Authentication An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using "token authentication":/docs/auth/token. "Sign up":https://ably.com/sign-up to Ably to create an API key in the dashboard or use the "Control API":/docs/account/control-api to create an API key programmatically. @@ -32,12 +32,12 @@ API keys and tokens have a set of "capabilities":/docs/auth/capabilities assigne | Message history | Subscribe, History | | Online status | Subscribe, Presence | | Room occupancy | Subscribe, Channel Metadata | -| Typing indicators | Publish, Subscribe, Presence | +| Typing indicators | Publish, Subscribe | | Room reactions | Publish, Subscribe | When setting the capabilities for Chat, you need to apply them to either a wildcard resource, or a wildcard resource prefixed with the chat namespace, for example: -* @[chat]*@ and @*@, or +* @[chat]*@ or * @[*]*@ h2(#install). Install @@ -53,6 +53,12 @@ blang[javascript,react]. npm install @ably/chat ``` + Currently, React is also required as a peer dependency. This will be removed in a future release. + + ```[sh] + npm install react + ``` + Import the SDKs into your project: ```[javascript] From d59aeac6d78c5eb627c1c4f2c08326b0292de389 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 17:59:02 +0100 Subject: [PATCH 2/6] Add explanation of Channel-Room relationship in documentation --- content/chat/rooms/index.textile | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index a040a65c7d..e23ce4ec03 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -11,6 +11,13 @@ languages: Rooms are used to organize and logically separate your users and chat messages into 'rooms'. They are the entry object into using chat and provide access to all other chat features, such as messages, online status and typing indicators. A room can represent a 1:1 chat between an agent and a customer, a private message between two users in a chat application, a large group conversation, or the chat section of a livestream with thousands of users. +h2(#channel-relationship). Channel <> Room relationship + +It is important to note that each room is backed by a single Ably Pub/Sub channel. +The channel name is the same as the room ID with an appended suffix of @::$chat@ (e.g @some-room-id::$chat@). In most cases, you will not need to worry about this, as the Chat SDK handles the channel creation and management for you and capabilities can be configured at the room level. + +However, you may need to be aware of this when using some integrations with Ably, such as the "Pulsar":https://ably.com/docs/integrations/streaming/pulsar#creating-pulsar-rule connectors, or if you are operating in an environment where a Chat SDK is not available. + h2(#create). Create or retrieve a room Users send messages to a room and subscribe to the room in order to receive messages. Other features, such as indicating which users are online, or which users are typing can be configured as part of a room's options. From 2d52ea22900074917dcc17a4e3a946eb8796d752 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 18:22:28 +0100 Subject: [PATCH 3/6] Add note on occupancy feature's default state and costs --- content/chat/rooms/occupancy.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/chat/rooms/occupancy.textile b/content/chat/rooms/occupancy.textile index 0916c7f438..e8c165b9a0 100644 --- a/content/chat/rooms/occupancy.textile +++ b/content/chat/rooms/occupancy.textile @@ -12,7 +12,7 @@ languages: Occupancy enables you to view the number of users currently online in a room. This feature can be used to display user counts to highlight popular, or trending chat rooms. h2(#subscribe). Subscribe to room occupancy From 27eb5d98f9cc296d28972a588f63b4345d6ff3d1 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 18:26:05 +0100 Subject: [PATCH 4/6] Add note styling for integration details in chat rooms doc --- content/chat/rooms/index.textile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index e23ce4ec03..2f37fbf4ac 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -16,7 +16,9 @@ h2(#channel-relationship). Channel <> Room relationship It is important to note that each room is backed by a single Ably Pub/Sub channel. The channel name is the same as the room ID with an appended suffix of @::$chat@ (e.g @some-room-id::$chat@). In most cases, you will not need to worry about this, as the Chat SDK handles the channel creation and management for you and capabilities can be configured at the room level. -However, you may need to be aware of this when using some integrations with Ably, such as the "Pulsar":https://ably.com/docs/integrations/streaming/pulsar#creating-pulsar-rule connectors, or if you are operating in an environment where a Chat SDK is not available. + h2(#create). Create or retrieve a room From 133acccd1ddb0fa74e7add7d36a69b7e2d3e9e04 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 11 Apr 2025 10:42:02 +0100 Subject: [PATCH 5/6] Update RoomOption defaults and property references in table --- content/chat/rooms/index.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 2f37fbf4ac..3289bebef1 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -105,9 +105,9 @@ The details of the options available to each feature are documented on their res blang[javascript]. | Feature | @RoomOption@ | Default settings | - | "Presence":/docs/chat/rooms/presence | @presence@ | @DefaultRoomOptions.presence@ | - | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @DefaultRoomOptions.occupancy@ | - | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @DefaultRoomOptions.typing@ | + | "Presence":/docs/chat/rooms/presence | @presence.enableEvents@ | @true@ | + | "Occupancy":/docs/chat/rooms/occupancy | @occupancy.enableEvents@ | @false@ | + | "Typing indicators":/docs/chat/rooms/typing | @typing.heartbeatThrottleMs@ | @10000@ | blang[swift,kotlin]. | Feature | @RoomOption@ | Default settings | From 6e45ff278fe9f4885ccc040e8818847027cc5bdf Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Tue, 29 Apr 2025 10:52:44 -0300 Subject: [PATCH 6/6] chat: Update Swift documentation for single channel Based on the JS changes in 448fc4b..133accc. --- content/chat/connect.textile | 2 +- content/chat/rooms/index.textile | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/chat/connect.textile b/content/chat/connect.textile index ea198448b5..4e2456cf8a 100644 --- a/content/chat/connect.textile +++ b/content/chat/connect.textile @@ -173,7 +173,7 @@ const MyComponent = () => { ``` ```[swift] -let subscription = room.messages.onDiscontinuity() +let subscription = room.onDiscontinuity() for await error in subscription { print("Recovering from the error: \(error)") } diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 3289bebef1..d13114645d 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -62,7 +62,7 @@ const App = () => { ``` ```[swift] -let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: RoomOptions()) +let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: .init(occupancy: .init(enableEvents: true))) ``` ```[kotlin] @@ -103,13 +103,13 @@ blang[react,swift,kotlin]. The details of the options available to each feature are documented on their respective pages: -blang[javascript]. +blang[javascript,swift]. | Feature | @RoomOption@ | Default settings | | "Presence":/docs/chat/rooms/presence | @presence.enableEvents@ | @true@ | | "Occupancy":/docs/chat/rooms/occupancy | @occupancy.enableEvents@ | @false@ | | "Typing indicators":/docs/chat/rooms/typing | @typing.heartbeatThrottleMs@ | @10000@ | -blang[swift,kotlin]. +blang[kotlin]. | Feature | @RoomOption@ | Default settings | | "Presence":/docs/chat/rooms/presence | @presence@ | @PresenceOptions()@ | | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @OccupancyOptions()@ |