From d049c89c70c997917841170bc33b0668b4b75ceb Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Wed, 12 Mar 2025 11:14:48 +0000 Subject: [PATCH 01/20] Chat: Update typing indicator API documentation Typing is no longer presence-based, the docs have been updated to reflect changes in logic to support this. - Also added details about the new `change` property in typing events and updated the timeout behavior with `start()` calls and grace periods. - `typing.get()` is also now synchronous. --- content/chat/rooms/typing.textile | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index c4cef60554..5c561f5875 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -72,6 +72,10 @@ The following is the structure of a typing event: "clemons", "zoranges", }, + "change": { + "event": "typing.started", + "clientId": "clemons" + } } ``` @@ -79,6 +83,7 @@ The following are the properties of a typing event: |_. Property |_. Description |_. Type | | currentlyTyping | A set of all users currently typing. | Set | +| change | The single change that resulted in the event. | Object | You can use the size of the @currentlyTyping@ set to decide whether to display individual user names, or that multiple people are typing in your user interface. @@ -100,7 +105,7 @@ blang[javascript,kotlin]. ```[javascript] // Initial subscription const { unsubscribe } = room.typing.subscribe((event) => { - console.log(`${event.clientId} is currently typing...`); + console.log('Typing event received: ', event); }); // To remove the listener @@ -130,7 +135,15 @@ blang[javascript,swift,kotlin]. blang[react]. Use the "@start()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseTypingResponse.html#start method available from the response of the @useTyping@ hook to emit an event when a user has started typing. -There is a timeout associated with start events. A stop event will be automatically emitted after it expires if one isn't received before the timeout. The length of this timeout is customizable using the @timeoutMs@ parameter that can be configured in the @RoomOptions@ that you set when you "create a room":/docs/chat/rooms#create. The default is 10000ms. +There is a timeout associated with start events. On first calling `start()`, this timer is set, subsequent calls to `start()` before the timer expires will result in a no-op. The length of this timeout is customizable using the @heartbeatIntervalMs@ parameter that can be configured in the @RoomOptions@ that you set when you "create a room":/docs/chat/rooms#create. The default is 15000ms. + +Consequently, if you want to keep the typing indicator active, you should call `start()` with each key press to ensure a new typing event is emitted after the timeout has expired. + +For a client receiving typing events, the typing indicator they have received will remain active for the duration of the timeout, plus a predefined grace period of 2000ms. If a new typing event is received for the same user before the grace period has expired, the typing indicator will be reset to the full duration of the timeout. For example, if the timeout is 15000ms, the typing indicator will remain active for 17000ms. + + ```[javascript] await room.typing.start(); @@ -205,11 +218,11 @@ blang[javascript,swift,kotlin]. Use the "@typing.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#get"@typing.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/get%28%29"@typing.get()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-typing/get.html method to retrieve a set of @clientId@s for all users that are currently typing in the room: ```[javascript] - const currentlyTypingClientIds = await room.typing.get(); + const currentlyTypingClientIds = room.typing.get(); ``` ```[swift] - let currentlyTypingClientIds = try await room.typing.get() + let currentlyTypingClientIds = try room.typing.get() ``` ```[kotlin] From 56dcef1fc90bd0ef36691e1dcd82c8472d363834 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 14 Mar 2025 14:10:13 +0000 Subject: [PATCH 02/20] Update typing event and timeout parameter names, updating default for `heartbeatThrottleMs` --- content/chat/rooms/typing.textile | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index 5c561f5875..9be24e0c23 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -73,7 +73,7 @@ The following is the structure of a typing event: "zoranges", }, "change": { - "event": "typing.started", + "type": "typing.started", "clientId": "clemons" } } @@ -84,6 +84,8 @@ The following are the properties of a typing event: |_. Property |_. Description |_. Type | | currentlyTyping | A set of all users currently typing. | Set | | change | The single change that resulted in the event. | Object | +| | type: The type of change that occurred. | String | +| | clientId: The @clientId@ of the user that triggered the change. | String | You can use the size of the @currentlyTyping@ set to decide whether to display individual user names, or that multiple people are typing in your user interface. @@ -135,11 +137,11 @@ blang[javascript,swift,kotlin]. blang[react]. Use the "@start()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseTypingResponse.html#start method available from the response of the @useTyping@ hook to emit an event when a user has started typing. -There is a timeout associated with start events. On first calling `start()`, this timer is set, subsequent calls to `start()` before the timer expires will result in a no-op. The length of this timeout is customizable using the @heartbeatIntervalMs@ parameter that can be configured in the @RoomOptions@ that you set when you "create a room":/docs/chat/rooms#create. The default is 15000ms. +There is a timeout associated with start events. On first calling `start()`, this timer is set, subsequent calls to `start()` before the timer expires will result in a no-op. The length of this timeout is customizable using the @heartbeatThrottleMs@ parameter that can be configured in the @RoomOptions@ that you set when you "create a room":/docs/chat/rooms#create. The default is 10000ms. Consequently, if you want to keep the typing indicator active, you should call `start()` with each key press to ensure a new typing event is emitted after the timeout has expired. -For a client receiving typing events, the typing indicator they have received will remain active for the duration of the timeout, plus a predefined grace period of 2000ms. If a new typing event is received for the same user before the grace period has expired, the typing indicator will be reset to the full duration of the timeout. For example, if the timeout is 15000ms, the typing indicator will remain active for 17000ms. +For a client receiving typing events, the typing indicator they have received will remain active for the duration of the timeout, plus a predefined grace period of 2000ms. If a new typing event is received for the same user before the grace period has expired, the typing indicator will be reset to the full duration of the timeout. For example, if the timeout is 15000ms, the typing indicator will remain active for 12000ms. 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}); ``` @@ -96,29 +91,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 | @@ -131,7 +112,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 bce7ea67a0..2d5d082b58 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 232b9e792d..13d0b68e7b 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 262d1f2ff7..fbf25886a5 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 f52fea8295..4f05702129 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 567f010f4d136301df39a7045e03dc3f4bb7a201 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 17:59:02 +0100 Subject: [PATCH 06/20] 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 6623ded245..5f0e5ec8c1 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 aa7540401532847e7208fa43e9bc02710d92c63f Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 18:22:28 +0100 Subject: [PATCH 07/20] 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 ccbcf93e31..7f093a95c4 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 f0cc2d57339d09da2605452ad20e633b07f637f1 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 10 Apr 2025 18:26:05 +0100 Subject: [PATCH 08/20] 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 5f0e5ec8c1..7b6b3de50c 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 1c1d65df7d590d57ccc2e05d0a8ea9ab0ce100aa Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 11 Apr 2025 10:42:02 +0100 Subject: [PATCH 09/20] 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 7b6b3de50c..cbcc0b8562 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -106,9 +106,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 34424514c6f0bf55ccd457d7387f0a3f1360effa Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Tue, 29 Apr 2025 10:52:44 -0300 Subject: [PATCH 10/20] 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 d98a4efba1..c83589be05 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 cbcc0b8562..1322351a7d 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -63,7 +63,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] @@ -104,13 +104,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()@ | From bb24e7ee7c4a2aba5d2356f7ac788a1d4ff590d0 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 1 May 2025 14:00:27 +0100 Subject: [PATCH 11/20] Fixing PR comments --- content/chat/rooms/index.textile | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 1322351a7d..9ebe59c65a 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -13,16 +13,13 @@ Rooms are used to organize and logically separate your users and chat messages i h2(#channel-relationship). Channel <> Room relationship -It is important to note that each room is backed by a single Ably Pub/Sub channel. +It is important to note that each room is backed by a single Ably Pub/Sub channel. 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. 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. - 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. +Users send messages to a room and subscribe to the room in order to receive messages. 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: From e28e281fa07d56829844c26a720835ba453c5b19 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 1 May 2025 14:16:35 +0100 Subject: [PATCH 12/20] Clarify billable message increase --- 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 7f093a95c4..5092f861c0 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 dcf39e672f3642af327ec0217c8f956da12eaf61 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Tue, 6 May 2025 12:24:55 +0100 Subject: [PATCH 13/20] Refactor: Fix blang and

closer --- content/chat/rooms/occupancy.textile | 2 +- content/chat/rooms/presence.textile | 7 +------ 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/content/chat/rooms/occupancy.textile b/content/chat/rooms/occupancy.textile index 5092f861c0..bb16058cb5 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 diff --git a/content/chat/rooms/presence.textile b/content/chat/rooms/presence.textile index 2d5d082b58..1dff7fe188 100644 --- a/content/chat/rooms/presence.textile +++ b/content/chat/rooms/presence.textile @@ -293,12 +293,7 @@ h2(#options). Presence options The following options can be set when "creating a room":/docs/chat/rooms#create that are specific to presence: -blang[javascript]. - - |_. Property |_. Description |_. Default | - | enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true | - -blang[react]. +blang[javascript,react]. |_. Property |_. Description |_. Default | | enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true | From 1642084d6bc616904ac4d072ae527c2174978b16 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 12 May 2025 16:28:12 +0100 Subject: [PATCH 14/20] Update typing set event payload --- content/chat/rooms/typing.textile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index fbf25886a5..1c0a7a29de 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -64,6 +64,7 @@ The following is the structure of a typing event: ```[json] { + "type": "typing.set.changed", "currentlyTyping": { "clemons", "zoranges", @@ -78,6 +79,7 @@ The following is the structure of a typing event: The following are the properties of a typing event: |_. Property |_. Description |_. Type | +| type | The type of the event. | String | | currentlyTyping | A set of all users currently typing. | Set | | change | The single change that resulted in the event. | Object | | | type: The type of change that occurred. | String | @@ -103,7 +105,7 @@ blang[javascript,kotlin]. ```[javascript] // Initial subscription import { TypingEvent } from '@ably/chat'; - const { unsubscribe } = room.typing.subscribe((event: TypingEvent) => { + const { unsubscribe } = room.typing.subscribe((event: TypingSetEvent) => { console.log('Typing event received: ', event); }); From b58b09d114ad533453a12988e54a5a456c457b29 Mon Sep 17 00:00:00 2001 From: Umair Date: Tue, 13 May 2025 12:55:54 +0100 Subject: [PATCH 15/20] update swift code and links to be in line with the upcoming 0.4.0 release --- content/chat/rooms/index.textile | 4 ++-- content/chat/rooms/messages.textile | 6 +++--- content/chat/rooms/typing.textile | 4 ++-- content/chat/setup.textile | 4 ++-- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 9ebe59c65a..240cabf3c5 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -84,9 +84,9 @@ blang[javascript,swift,kotlin]. ```[swift] let presence = PresenceOptions(enter: false) - let typing = TypingOptions(timeout: 5.0) // seconds + let typing = TypingOptions(heartbeatThrottle: 5.0) // seconds // using defaults for reactions and occupancy - let options = RoomOptions(presence: presence, typing: typing, reactions: nil, occupancy: nil) + let options = RoomOptions(presence: presence, typing: typing, reactions: .init(), occupancy: .init()) let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: options) ``` diff --git a/content/chat/rooms/messages.textile b/content/chat/rooms/messages.textile index fe2dafbc73..a6bf659e20 100644 --- a/content/chat/rooms/messages.textile +++ b/content/chat/rooms/messages.textile @@ -305,7 +305,7 @@ const MyComponent = () => { ```[swift] let messagesList: [Message] -let messagesSubscription = try await room().messages.subscribe() +let messagesSubscription = try await room.messages.subscribe() for await message in messagesSubscription { switch message.action { case .create: @@ -415,7 +415,7 @@ const MyComponent = () => { ```[swift] let messageToDelete: Message -let deletedMessage = try await room().messages.delete( +let deletedMessage = try await room.messages.delete( message: messageToDelete, params: .init(description: "Message deleted by user") ) @@ -492,7 +492,7 @@ const MyComponent = () => { ```[swift] let messagesList: [Message] -let messagesSubscription = try await room().messages.subscribe() +let messagesSubscription = try await room.messages.subscribe() for await message in messagesSubscription { switch message.action { case .create: diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index 1c0a7a29de..c52235e909 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -131,7 +131,7 @@ blang[react,swift,kotlin]. h2(#set). Set typing status blang[javascript,swift,kotlin]. - Use the "@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#start"@typing.start()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/start%28%29"@typing.start()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-typing/start.html method to emit a typing event with @type@ set to @typing.started@. + Use the "@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#start"@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/keystroke%28%29"@typing.start()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-typing/start.html method to emit a typing event with @type@ set to @typing.started@. blang[react]. Use the "@keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseTypingResponse.html#keystroke method available from the response of the @useTyping@ hook to emit an event when a user has started typing. @@ -160,7 +160,7 @@ const MyComponent = () => { ``` ```[swift] -try await room.typing.start() +try await room.typing.keystroke() ``` ```[kotlin] diff --git a/content/chat/setup.textile b/content/chat/setup.textile index 4f05702129..04fcb77c4e 100644 --- a/content/chat/setup.textile +++ b/content/chat/setup.textile @@ -101,7 +101,7 @@ blang[swift]. To install the @ably-chat-swift@ package in another Swift Package, add the following to your @Package.swift@: ```[swift] - .package(url: "https://github.com/ably/ably-chat-swift", from: "0.1.0"), + .package(url: "https://github.com/ably/ably-chat-swift", from: "0.4.0"), ``` Import the SDK: @@ -232,7 +232,7 @@ let realtimeOptions = ARTClientOptions() realtimeOptions.key = "{{API_KEY}}" realtimeOptions.clientId = "" let realtime = ARTRealtime(options: realtimeOptions) -let clientOptions = ClientOptions(logHandler: SomeLogHandler(), logLevel: .debug) +let clientOptions = ChatClientOptions(logHandler: SomeLogHandler(), logLevel: .debug) return DefaultChatClient(realtime: realtime, clientOptions: clientOptions) ``` From 320559263998cf2138bd515890a6e2ada6b4e857 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Wed, 14 May 2025 17:53:59 +0530 Subject: [PATCH 16/20] Updated kotlin docs in accordance with single channel changes, bumped up version to latest release --- content/chat/connect.textile | 4 ++-- content/chat/rooms/index.textile | 26 +++++++++++++------------- content/chat/rooms/typing.textile | 6 +++--- content/chat/setup.textile | 13 ++++++------- 4 files changed, 24 insertions(+), 25 deletions(-) diff --git a/content/chat/connect.textile b/content/chat/connect.textile index c83589be05..e159ed920e 100644 --- a/content/chat/connect.textile +++ b/content/chat/connect.textile @@ -180,7 +180,7 @@ for await error in subscription { ``` ```[kotlin] -val subscription = room.messages.onDiscontinuity { reason: ErrorInfo? -> +val subscription = room.onDiscontinuity { reason: ErrorInfo -> // Recover from the discontinuity } ``` @@ -207,4 +207,4 @@ blang[react,swift]. blang[react]. blang[javascript,swift,kotlin]. - 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. + 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"Room":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room/index.html object. diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 240cabf3c5..317da994c2 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -64,7 +64,7 @@ let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: ``` ```[kotlin] -val room = chatClient.rooms.get(roomId = "basketball-stream", options = RoomOptions()) +val room = chatClient.rooms.get(roomId = "basketball-stream") ``` blang[react]. @@ -91,29 +91,29 @@ blang[javascript,swift,kotlin]. ``` ```[kotlin] - val presence = PresenceOptions(enter = false) - val typing = TypingOptions(timeoutMs = 5_000) // 5 seconds - val options = RoomOptions(presence = presence, typing = typing) - val room = chatClient.rooms.get(roomId = "basketball-stream", options = options) + val room = chatClient.rooms.get(roomId = "basketball-stream") { + typing { + heartbeatThrottle = 5.seconds + } + presence { + enableEvents = true + } + occupancy { + enableEvents = true + } + } ``` blang[react,swift,kotlin]. The details of the options available to each feature are documented on their respective pages: -blang[javascript,swift]. +blang[javascript,swift,kotlin]. | 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[kotlin]. - | Feature | @RoomOption@ | Default settings | - | "Presence":/docs/chat/rooms/presence | @presence@ | @PresenceOptions()@ | - | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @OccupancyOptions()@ | - | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @TypingOptions()@ | - | "Room reactions":/docs/chat/rooms/reactions | @reactions@ | @RoomReactionsOptions()@ | - h3(#release). Release a room Releasing a room allows the underlying resources to be garbage collected or released. diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index c52235e909..e107de1d73 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -53,7 +53,7 @@ for await typing in typingSubscription { ``` ```[kotlin] -val subscription = room.typing.subscribe { event: TypingEvent -> +val subscription = room.typing.subscribe { event: TypingSetEvent -> println("currently typing: ${event.currentlyTyping}") } ``` @@ -131,7 +131,7 @@ blang[react,swift,kotlin]. h2(#set). Set typing status blang[javascript,swift,kotlin]. - Use the "@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#start"@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/keystroke%28%29"@typing.start()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-typing/start.html method to emit a typing event with @type@ set to @typing.started@. + Use the "@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#start"@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/keystroke%28%29"@typing.keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-typing/keystroke.html method to emit a typing event with @type@ set to @typing.started@. blang[react]. Use the "@keystroke()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseTypingResponse.html#keystroke method available from the response of the @useTyping@ hook to emit an event when a user has started typing. @@ -164,7 +164,7 @@ try await room.typing.keystroke() ``` ```[kotlin] -room.typing.start() +room.typing.keystroke() ``` blang[javascript,swift,kotlin]. diff --git a/content/chat/setup.textile b/content/chat/setup.textile index 04fcb77c4e..6e3e98da56 100644 --- a/content/chat/setup.textile +++ b/content/chat/setup.textile @@ -116,13 +116,13 @@ blang[kotlin]. The Ably Chat SDK is available on the Maven Central Repository. To include the dependency in your project, add the following to your @build.gradle.kts@ file: ```[kotlin] - implementation("com.ably.chat:chat-android:0.2.0") + implementation("com.ably.chat:chat-android:0.3.0") ``` For groovy: ```[kotlin] - implementation 'com.ably.chat:chat-android:0.2.0' + implementation 'com.ably.chat:chat-android:0.3.0' ``` h2(#instantiate). Instantiate a client @@ -243,11 +243,10 @@ val realtimeClient = AblyRealtime( clientId = "" }, ) -val chatOptions = com.ably.chat.ClientOptions( - logHandler = CustomLogHandler(), // Implements com.ably.chat.LogHandler interface - logLevel = LogLevel.Debug, -) -val chatClient = ChatClient(realtimeClient, chatOptions) +val chatClient = ChatClient(realtimeClient) { + logHandler = CustomLogHandler() // Implements com.ably.chat.LogHandler interface + logLevel = LogLevel.Debug +} ``` blang[javascript,react]. From d746458caa97ce090ed74712a4c28f32494f2ae8 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Wed, 14 May 2025 17:54:31 +0530 Subject: [PATCH 17/20] Fixed js docs for typing, updated doc links as well --- content/chat/getting-started/javascript.textile | 4 ++-- examples/chat-typing-indicator/javascript/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/chat/getting-started/javascript.textile b/content/chat/getting-started/javascript.textile index f5b40f95d8..0b1a80fe92 100644 --- a/content/chat/getting-started/javascript.textile +++ b/content/chat/getting-started/javascript.textile @@ -163,7 +163,7 @@ h2(#step-5). Step 5: Show who is typing a message Typing indicators enable you to display messages to clients when someone is currently typing. An event is emitted when someone starts typing, when they press a keystroke, and then another event is emitted after a configurable amount of time has passed without a key press. -In practice the @typing.start()@ method would be called on keypress, however for demonstration purposes we will call it and wait for the default period of time to pass for a stop event to be emitted. Using your original client, add the following lines to @getStarted()@ to subscribe to typing events and emit one, then run it with @npx ts-node index.ts@: +In practice the @typing.keystroke()@ method would be called on keypress, however for demonstration purposes we will call it and wait for the default period of time to pass for a stop event to be emitted. Using your original client, add the following lines to @getStarted()@ to subscribe to typing events and emit one, then run it with @npx ts-node index.ts@: ```[javascript] room.typing.subscribe((typingEvent) => { @@ -174,7 +174,7 @@ room.typing.subscribe((typingEvent) => { } }); -await room.typing.start() +await room.typing.keystroke() // A client types await room.typing.stop() ``` diff --git a/examples/chat-typing-indicator/javascript/README.md b/examples/chat-typing-indicator/javascript/README.md index 8d451b36d4..528c2c79bc 100644 --- a/examples/chat-typing-indicator/javascript/README.md +++ b/examples/chat-typing-indicator/javascript/README.md @@ -14,8 +14,8 @@ Use the following methods to add typing indicators into a chat application: - [`rooms.get()`](/docs/chat/rooms?lang=javascript#create): creates a new or retrieves an existing `room`. - [`rooms.typing.subscribe()`](/docs/chat/rooms/typing#subscribe): subscribes to typing events by registering a listener. Typing events are emitted when a user starts typing, or when they stop typing. -- [`room.typing.get()`](/docs/chat/rooms/typing?lang=javascript#retrieve): retrieves the list of users currently typing by their clientId. -- [`room.typing.start()`](/docs/chat/rooms/typing?lang=javascript#set): emits a typing event that the user is currently typing, initialising the timeout which will call `room.typing.stop()` if no further events are emitted by the user. +- [`room.typing.get()`](/docs/chat/rooms/typing?lang=javascript#get): retrieves the list of users currently typing by their clientId. +- [`room.typing.keystroke()`](/docs/chat/rooms/typing?lang=javascript#keystroke): emits a typing event that the user is currently typing, initialising the timeout which will call `room.typing.stop()` if no further events are emitted by the user. Find out more about [typing indicators](/docs/chat/rooms/typing). From 220b9f89552dc6ede341b682b2f9632f6a73e3ce Mon Sep 17 00:00:00 2001 From: Steven <67319712+splindsay-92@users.noreply.github.com> Date: Thu, 15 May 2025 11:21:27 +0100 Subject: [PATCH 18/20] Update content/chat/connect.textile Co-authored-by: sachin shinde --- content/chat/connect.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/chat/connect.textile b/content/chat/connect.textile index e159ed920e..aa750d4947 100644 --- a/content/chat/connect.textile +++ b/content/chat/connect.textile @@ -152,7 +152,7 @@ blang[react]. For example, for messages: ```[javascript] -const { off } = room.onDiscontinuity((reason?: ErrorInfo) => { +const { off } = room.onDiscontinuity((reason: ErrorInfo) => { // Recover from the discontinuity }); ``` From 06b2c82d96b51f501f601a5c5d7785e47a2d5248 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 15 May 2025 12:53:18 +0100 Subject: [PATCH 19/20] fixup PR comments --- content/chat/rooms/index.textile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index 317da994c2..5ee7999f3b 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -14,6 +14,7 @@ Rooms are used to organize and logically separate your users and chat messages i h2(#channel-relationship). Channel <> Room relationship It is important to note that each room is backed by a single Ably Pub/Sub channel. 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. + 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. @@ -118,7 +119,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 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. Also, proactively disconnecting rather than waiting for the standard two-minute timeout can help reduce costs and improve performance. 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. From 8a45af41593666f42adf7468c9423a0fb49706ae Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Thu, 15 May 2025 14:18:32 +0100 Subject: [PATCH 20/20] Updating languageData.ts to latest chat sdk versions --- src/data/languages/languageData.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts index c3c2e5f3f7..c3972fc5a9 100644 --- a/src/data/languages/languageData.ts +++ b/src/data/languages/languageData.ts @@ -22,10 +22,10 @@ export default { go: 1.2, }, chat: { - javascript: 0.6, - react: 0.6, - swift: 0.2, - kotlin: 0.2, + javascript: 0.7, + react: 0.7, + swift: 0.4, + kotlin: 0.3, }, spaces: { javascript: 0.4,