diff --git a/content/chat/connect.textile b/content/chat/connect.textile index 31e2591eab..eef2d446cd 100644 --- a/content/chat/connect.textile +++ b/content/chat/connect.textile @@ -5,6 +5,7 @@ product: chat languages: - javascript - react + - swift --- When you "instantiate":/chat/setup#instantiate a client, a realtime connection is established and maintained with Ably. You can interact with the connection using the @ChatClient.connection@ object in order to monitor a client's connection status. @@ -21,8 +22,8 @@ A connection can have any of the following statuses: | suspended | A long term failure condition when no current connection exists because there is no network connectivity or available host. The suspended status is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended status, an SDK will periodically attempt to open a new connection every 30 seconds. Rooms will be reattached on a successful reconnection, however message history will not be automatically recovered. | | failed | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. | -blang[javascript]. - Use the "@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.ConnectionStatus.html#current property to check which status a connection is currently in: +blang[javascript,swift]. + Use the "@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.ConnectionStatus.html#current"@status@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus property to check which status a connection is currently in: blang[react]. Use the "@currentStatus@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseChatConnectionResponse.html#currentStatus property returned in the response of the "@useChatConnection@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useChatConnection.html hook to check which status a connection is currently in: @@ -44,6 +45,10 @@ const MyComponent = () => { }; ``` +```[swift] +let status = await chatClient.connection.status +``` + blang[react]. Hooks related to chat features, such as @useMessages@ and @useTyping@, also return the current @connectionStatus@ in their response. @@ -61,10 +66,10 @@ blang[react]. }; ``` -blang[javascript]. +blang[javascript,swift]. -blang[javascript]. - Use the "@connection.status.onChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.ConnectionStatus.html#onChange method to register a listener for status change updates: +blang[javascript,swift]. + Use the "@connection.status.onChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.ConnectionStatus.html#onChange"@connection.onStatusChange()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connection/onstatuschange%28%29-76t7 method to register a listener for status change updates: blang[react]. Listeners can also be registered to monitor the changes in connection status. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a status change listener. Changing the value provided for a listener will cause the previously registered listener instance to stop receiving events. All messages will be received by exactly one listener. @@ -86,20 +91,38 @@ const MyComponent = () => { }; ``` +```[swift] +let subscription = chatClient.connection.onStatusChange() +for await statusChange in subscription { + print("Connection status changed to: \(statusChange.current)") +} +``` + blang[javascript]. - To remove the connection status listener, call the @off()@ function returned in the @subscribe()@ response: + Use the @off()@ function returned in the @onStatusChange()@ response to remove a listener: + +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a listener: +blang[javascript,swift]. ```[javascript] off(); ``` + ```[swift] + subscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript]. Use the "@connection.status.offAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.ConnectionStatus.html#offAll method to remove all connection status listeners: ```[javascript] chatClient.connection.status.offAll(); ``` -blang[react]. +blang[react,swift]. h2(#discontinuity). Handle connection discontinuity @@ -107,7 +130,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":/chat/rooms/history. -blang[javascript]. +blang[javascript,swift]. 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. blang[react]. @@ -136,19 +159,37 @@ const MyComponent = () => { }; ``` -blang[react]. +```[swift] +let subscription = room.messages.onDiscontinuity() +for await error in subscription { + print("Recovering from the error: \(error)") +} +``` blang[javascript]. Use the @off()@ function returned in the @onDiscontinuity()@ response to remove a listener: +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a listener: + +blag[react]. + +blang[javascript,swift]. ```[javascript] off(); ``` + ```[swift] + subscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript,swift]. The following discontinuity handlers are available: - * "Messages":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#onDiscontinuity - * "Presence":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#onDiscontinuity - * "Occupancy":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#onDiscontinuity - * "Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#onDiscontinuity - * "Room reactions":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#onDiscontinuity + * "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 diff --git a/content/chat/rooms/history.textile b/content/chat/rooms/history.textile index ac5239acca..91fba9a3bf 100644 --- a/content/chat/rooms/history.textile +++ b/content/chat/rooms/history.textile @@ -5,14 +5,15 @@ product: chat languages: - javascript - react + - swift --- The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 24 hours by default. You can extend this up to 30 days by "contacting us":https://forms.gle/SmCLNFoRrYmkbZSf8. h2(#get). Retrieve previously sent messages -blang[javascript]. - Use the "@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get method to retrieve messages that have been previously sent to a room: +blang[javascript,swift]. + Use the "@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get"@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/get%28options%3A%29 method to retrieve messages that have been previously sent to a room: blang[react]. Use the "@get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#get method available from the response of the @useMessages@ hook to retrieve messages that have been previously sent to a room. @@ -50,20 +51,38 @@ const MyComponent = () => { }; ``` +```[swift] +let paginatedResult = try await room.messages.get(options: .init(orderBy: .newestFirst)) +print(paginatedResult.items) +if let next = try await paginatedResult.next { + print(next.items) +} else { + print("End of messages") +} +``` + The following optional parameters can be passed when retrieving previously sent messages: -|_. Parameter |_. Description | -| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | -| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | -| direction | The direction in which to retrieve messages from; either @forwards@ or @backwards@. | -| limit | Maximum number of messages to be retrieved, up to 1,000. | +blang[javascript]. + |_. Parameter |_. Description | + | start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | + | end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | + | direction | The direction in which to retrieve messages from; either @forwards@ or @backwards@. | + | limit | Maximum number of messages to be retrieved, up to 1,000. | + +blang[swift]. + |_. Parameter |_. Description | + | start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | + | end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | + | orderBy | The direction in which to retrieve messages from; either @oldestFirst@ or @newestFirst@. | + | limit | Maximum number of messages to be retrieved, up to 1,000. | h2(#subscribe). Retrieve messages sent prior to subscribing Users can also retrieve historical messages that were sent to a room before the point that they registered a listener by "subscribing":/chat/rooms/messages#subscribe. The order of messages returned is from most recent, to oldest. This is useful for providing conversational context when a user first joins a room, or when they subsequently rejoin it later on. It also ensures that the message history they see is continuous, without any overlap of messages being returned between their subscription and their history call. -blang[javascript]. - Use the "@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#getPreviousMessages function returned as part of a "message subscription":/chat/rooms/messages#subscribe response to only retrieve messages that were received before the listener was subscribed to the room: +blang[javascript,swift]. + Use the "@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#getPreviousMessages"@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscription/getpreviousmessages%28params%3A%29 function returned as part of a "message subscription":/chat/rooms/messages#subscribe response to only retrieve messages that were received before the listener was subscribed to the room: blang[react]. Use the "@getPrevious()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#getPreviousMessages method available from the response of the @useMessages@ hook to only retrieve messages that were received before the listener subscribed to the room. As long as a defined value is provided for the listener, and there are no message discontinuities, @getPreviousMessages()@ will return messages from the same point across component renders. If the listener becomes undefined, the subscription to messages will be removed. If you subsequently redefine the listener then @getPreviousMessages()@ will return messages from the new point of subscription. @@ -114,6 +133,17 @@ const MyComponent = () => { }; ``` +```[swift] +let messagesSubscription = try await room.messages.subscribe() +let paginatedResult = try await messagesSubscription.getPreviousMessages(params: .init(limit: 50)) // `orderBy` here is ignored and always `newestFirst` +print(paginatedResult.items) +if let next = try await paginatedResult.next { + print(next.items) +} else { + print("End of messages") +} +``` + The following parameters can be passed when retrieving previously sent messages: |_. Parameter |_. Description | diff --git a/content/chat/rooms/index.textile b/content/chat/rooms/index.textile index f53b049797..00d390cf2b 100644 --- a/content/chat/rooms/index.textile +++ b/content/chat/rooms/index.textile @@ -5,6 +5,7 @@ product: chat languages: - javascript - react + - swift --- 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. @@ -15,8 +16,8 @@ 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. -blang[javascript]. - 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 method: +blang[javascript,swift]. + 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 method: 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. @@ -53,6 +54,10 @@ const App = () => { }; ``` +```[swift] +let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: RoomOptions()) +``` + blang[react]. -blang[javascript]. - -blang[javascript]. - 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 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. +blang[javascript,swift]. + 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 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. ```[javascript] const presence = {enter: false}; @@ -73,6 +76,15 @@ blang[javascript]. const room = chatClient.rooms.get('basketball-stream', {presence, reactions, typing, occupancy}); ``` + ```[swift] + let presence = PresenceOptions(enter: false) + let typing = TypingOptions(timeout: 5.0) // seconds + // using defaults for reactions and occupancy + let options = RoomOptions(presence: presence, typing: typing, reactions: nil, occupancy: nil) + let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: options) + ``` + +blang[javascript]. You can also use the @RoomOptionsDefaults@ property for each @RoomOption@ to configure whether the default settings should be used: ```[javascript] @@ -85,15 +97,23 @@ blang[javascript]. const room = chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}}); ``` -blang[react]. +blang[react,swift]. Enable each feature using its associated option. The details of the options available to each feature are documented on their respective pages: -| Feature | @RoomOption@ | Default settings | -| "Presence":/chat/rooms/presence | @presence@ | @RoomOptionsDefaults.presence@ | -| "Occupancy":/chat/rooms/occupancy | @occupancy@ | @RoomOptionsDefaults.occupancy@ | -| "Typing indicators":/chat/rooms/typing | @typing@ | @RoomOptionsDefaults.typing@ | -| "Room reactions":/chat/rooms/reactions | @reactions@ | @RoomOptionsDefaults.reactions@ | +blang[javascript]. + | Feature | @RoomOption@ | Default settings | + | "Presence":/chat/rooms/presence | @presence@ | @RoomOptionsDefaults.presence@ | + | "Occupancy":/chat/rooms/occupancy | @occupancy@ | @RoomOptionsDefaults.occupancy@ | + | "Typing indicators":/chat/rooms/typing | @typing@ | @RoomOptionsDefaults.typing@ | + | "Room reactions":/chat/rooms/reactions | @reactions@ | @RoomOptionsDefaults.reactions@ | + +blang[swift]. + | Feature | @RoomOption@ | Default settings | + | "Presence":/chat/rooms/presence | @presence@ | @PresenceOptions()@ | + | "Occupancy":/chat/rooms/occupancy | @occupancy@ | @OccupancyOptions()@ | + | "Typing indicators":/chat/rooms/typing | @typing@ | @TypingOptions()@ | + | "Room reactions":/chat/rooms/reactions | @reactions@ | @RoomReactionsOptions()@ | h3(#release). Release a room @@ -101,13 +121,17 @@ Releasing a room allows the underlying resources to be garbage collected or rele 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. -blang[javascript]. - Once "@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#release 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. +blang[javascript,swift]. + 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 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. ```[javascript] await rooms.release('basketball-stream'); ``` + ```[swift] + try await rooms.release(roomID: "basketball-stream") + ``` + blang[react]. By default the @ChatRoomProvider@ will automatically call "@release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#release on the room when it unmounts. Set the "@release@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.ChatRoomProviderProps.html#release property to @false@ to change this behavior and have the room only "detach":#detach when the component unmounts. You can manually control this attachment behavior using the "@useRoom@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useRoom.html hook. @@ -115,10 +139,10 @@ h2(#attach). Attach to a room As soon as a client is attached to a room, Ably will begin streaming messages and events to them, regardless of whether or not they have registered any listeners to receive those messages and events. -blang[javascript]. +blang[javascript,swift]. Once a reference to a room has been created using @rooms.get()@, clients attach to it in order to ensure it is created in the Ably system. - Use the "@attach()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach method on a room to attach to it: + Use the "@attach()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach"@attach()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/attach%28%29 method on a room to attach to it: blang[react]. By default the @ChatRoomProvider@ will automatically call "@attach()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach on the room when it first mounts. Set the "@attach@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.ChatRoomProviderProps.html#attach property to @false@ to manually control the attachment using the "@useRoom@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useRoom.html hook instead. @@ -142,15 +166,23 @@ const MyComponent = () => { }; ``` +```[swift] +try await room.attach() +``` + h3(#detach). Detach from a room -blang[javascript]. - Use the "@detach()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#detach method on a room to detach from it and stop receiving messages and events: +blang[javascript,swift]. + Use the "@detach()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#detach"@detach()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/detach%28%29 method on a room to detach from it and stop receiving messages and events: ```[javascript] await room.detach(); ``` + ```[swift] + try await room.detach() + ``` + blang[react]. By default the @ChatRoomProvider@ will automatically call "@release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#release on the room when it unmounts. Set the "@release@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.ChatRoomProviderProps.html#release property to @false@ to change this behavior and have the room only "detach":#detach when the component unmounts. You can manually control this attachment behavior using the "@useRoom@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useRoom.html hook. @@ -174,8 +206,9 @@ A room can have any of the following statuses: | suspended | The room, having previously been attached, has lost continuity. This is normally due to the client being disconnected from Ably for more than two minutes. The client will automatically attempt to reattach as soon as connectivity is restored. | | failed | An indefinite failure condition. This status is entered if an error has been received from Ably, such as an attempt to attach without the necessary access rights. | -blang[javascript]. - Use the "@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#current property to check which status a room is currently in: + +blang[javascript,swift]. + Use the "@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#current"@status@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomstatus property to check which status a room is currently in: blang[react]. Use the @roomStatus@ property to view the current "@Room@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html status changes. The @roomError@ property is its associated error. Any hooks that take an optional listener have these properties available in their response, such as @useMessages@ or @useTyping@. It is more common that you will monitor the room status in the specific feature hooks rather than needing to use @useRoom@. These events are related to the room instance of the nearest "@ChatRoomProvider@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatRoomProvider.html. For example, with the @useMessages@ hook: @@ -203,28 +236,55 @@ const MyComponent = () => { }; ``` -blang[javascript]. +```[swift] +let status = try await room.status +``` + +blang[javascript,swift]. You can also subscribe to room status updates by registering a listener. An event will be emitted whenever the status of the room changes. - Use the "@room.status.onChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#onChange method in a room to register a listener for status change updates: + Use the "@room.status.onChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#onChange"@room.onStatusChange()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/onstatuschange%28%29-s9g method in a room to register a listener for status change updates: ```[javascript] const { off } = room.onStatusChange((change) => console.log(change)); ``` - To remove the room status listener, call the provided @off()@ function: + ```[swift] + let statusSubscription = try await room.onStatusChange() + for await status in statusSubscription { + print("Room status: \(status)") + } + ``` + +blang[javascript]. + Use the @off()@ function returned in the @onStatusChange()@ response to remove a room status listener: + +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a room status listener: + +blang[react]. +blang[javascript,swift]. ```[javascript] off(); ``` + ```[swift] + statusSubscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript]. Use the "@room.status.offAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#offAll method to remove all room status listeners in a room: ```[javascript] room.status.offAll(); ``` +blang[swift]. + blang[react]. Listeners can also be registered to monitor the changes in room status. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a status change listener. Changing the value provided for a listener will cause the previously registered listener instance to stop receiving events. All messages will be received by exactly one listener. diff --git a/content/chat/rooms/messages.textile b/content/chat/rooms/messages.textile index b6a7ab46fd..fa23ec396a 100644 --- a/content/chat/rooms/messages.textile +++ b/content/chat/rooms/messages.textile @@ -5,14 +5,15 @@ product: chat languages: - javascript - react + - swift --- You can send and receive messages in a chat room with any number of participants. These users subscribe to messages by registering a listener, and send messages to all users that are subscribed to receive them. h2(#subscribe). Subscribe to messages -blang[javascript]. - Subscribe to receive messages in a room by registering a listener. Use the "@messages.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe method in a room to receive all messages that are sent to it: +blang[javascript,swift]. + Subscribe to receive messages in a room by registering a listener. Use the "@messages.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe"@messages.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/subscribe%28%29-360z1 method in a room to receive all messages that are sent to it: blang[react]. Subscribe to messages with the "@useMessages@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useMessages.html hook. Supply a listener and the hook will automatically subscribe to messages sent to the room. As long as a defined value is provided, the subscription will persist across renders. If the listener value is undefined, the subscription will be removed until it becomes defined again. @@ -40,6 +41,13 @@ const MyComponent = () => { }; ``` +```[swift] +let messagesSubscription = try await room.messages.subscribe() +for await message in messagesSubscription { + print("Message received: \(message)") +} +``` + h3(#structure). Message structure The following is the structure of a message: @@ -70,10 +78,15 @@ The following are the properties of a message: h3(#unsubscribe). Unsubscribe from messages blang[javascript]. - Unsubscribe from messages to remove previously registered listeners. + Use the @unsubscribe()@ function returned in the @subscribe()@ response to remove a chat message listener: - Use the "@unsubscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#unsubscribe function returned in the @subscribe()@ response to remove a listener: +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a chat message listener: +blang[react]. + When you unmount the component that is using the @useMessages@ hook, it will automatically handle unsubscribing any associated listeners registered to receive messages. + +blang[javascript,swift]. ```[javascript] // Initial subscription const { unsubscribe } = room.messages.subscribe((message) => console.log(message)); @@ -82,12 +95,23 @@ blang[javascript]. unsubscribe(); ``` + ```[swift] + messagesSubscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript]. Use the "@messages.unsubscribeAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#unsubscribeAll method to deregister all chat message listeners in a room: ```[javascript] await room.messages.unsubscribeAll(); ``` +blang[react,swift]. + +blang[javascript,swift]. + blang[react]. - When you unmount the component that is using the @useMessages@ hook, it will automatically handle unsubscribing any associated listeners registered to receive messages. h2(#send). Send a message -blang[javascript]. - Use the "@messages.send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#send method to send a message in a chat room. All users that are "subscribed":#subscribe to messages on that room will receive it: +blang[javascript,swift]. + Use the "@messages.send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#send"@messages.send()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/send%28params%3A%29 method to send a message in a chat room. All users that are "subscribed":#subscribe to messages on that room will receive it: blang[react]. - Use the "@send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#send method available from the response of the @useMessages@ hook to to send a message to the room: + Use the "@send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#send method available from the response of the @useMessages@ hook to send a message to the room: ```[javascript] await room.messages.send({text: 'hello'}); @@ -126,3 +149,7 @@ const MyComponent = () => { ); }; ``` + +```[swift] +let message = try await room.messages.send(params: .init(text: "hello")) +``` diff --git a/content/chat/rooms/occupancy.textile b/content/chat/rooms/occupancy.textile index 8847151036..8bc39086d9 100644 --- a/content/chat/rooms/occupancy.textile +++ b/content/chat/rooms/occupancy.textile @@ -5,6 +5,7 @@ product: chat languages: - javascript - react + - swift --- 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. @@ -15,8 +16,8 @@ Occupancy enables you to view the number of users currently online in a room. Th h2(#subscribe). Subscribe to room occupancy -blang[javascript]. - Subscribe to a room's occupancy by registering a listener. Occupancy events are emitted whenever the number of online users within a room changes. Use the "@occupancy.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#subscribe method in a room to receive updates: +blang[javascript,swift]. + Subscribe to a room's occupancy by registering a listener. Occupancy events are emitted whenever the number of online users within a room changes. Use the "@occupancy.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#subscribe"@occupancy.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/subscribe%28%29-3loon method in a room to receive updates: blang[react]. Subscribe to a room's occupancy with the "@useOccupancy@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useOccupancy.html hook. @@ -27,6 +28,13 @@ const {unsubscribe} = room.occupancy.subscribe((event) => { }); ``` +```[swift] +let occupancySubscription = try await room.occupancy.subscribe() +for await event in occupancySubscription { + occupancyInfo = "Connections: \(event.presenceMembers) (\(event.connections))" +} +``` + ```[react] import { useOccupancy } from '@ably/chat/react'; @@ -74,10 +82,15 @@ The following are the properties of an occupancy event: h3(#unsubscribe). Unsubscribe from room occupancy blang[javascript]. - Unsubscribe from room occupancy to remove previously registered listeners. + Use the @unsubscribe()@ function returned in the @subscribe()@ response to remove a room occupancy listener: - Use the "@unsubscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.OccupancySubscriptionResponse.html#unsubscribe function returned in the @subscribe()@ response to remove a listener: +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a room occupancy listener: +blang[react]. + When you unmount the component that is using the @useOccupancy@ hook, it will automatically handle unsubscribing any associated listeners registered for room occupancy. + +blang[javascript,swift]. ```[javascript] // Initial subscription const { unsubscribe } = room.occupancy.subscribe((event) => { @@ -88,26 +101,36 @@ blang[javascript]. unsubscribe(); ``` - Use the "@occupancy.unsubscribeAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#unsubscribeAll method to remove all occupancy listeners in a room: + ```[swift] + occupancySubscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript]. + Use the "@occupancy.unsubscribeAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#unsubscribeAll method to remove all room occupancy listeners in a room: ```[javascript] await room.occupancy.unsubscribeAll(); ``` -blang[react]. - When you unmount the component that is using the @useOccupancy@ hook, it will automatically handle unsubscribing any associated listeners registered for room occupancy. +blang[react,swift]. h2(#retrieve). Retrieve room occupancy -blang[javascript]. +blang[javascript,swift]. The occupancy of a room can be retrieved in one-off calls instead of subscribing to updates. - Use the "@occupancy.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#get method to retrieve the occupancy of a room: + Use the "@occupancy.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#get"@occupancy.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/get%28%29 method to retrieve the occupancy of a room: ```[javascript] const occupancy = await room.occupancy.get(); ``` + ```[swift] + let occupancy = try await room.occupancy.get() + ``` + blang[react]. Use the "@connections@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseOccupancyResponse.html#connections and "@presenceMembers@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseOccupancyResponse.html#presenceMembers properties available from the response of the @useOccupancy@ hook to view the occupancy of a room. diff --git a/content/chat/rooms/presence.textile b/content/chat/rooms/presence.textile index d581985726..8479feee5d 100644 --- a/content/chat/rooms/presence.textile +++ b/content/chat/rooms/presence.textile @@ -5,6 +5,7 @@ product: chat languages: - javascript - react + - swift --- 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. @@ -15,8 +16,8 @@ Subscribe to the online status of room members using the presence feature. Prese h2(#subscribe). Subscribe to presence -blang[javascript]. - Subscribe to users' presence status by registering a listener. Presence events are emitted whenever a member enters or leaves the presence set, or updates their user data. Use the "@presence.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#subscribe method in a room to receive updates: +blang[javascript,swift]. + Subscribe to users' presence status by registering a listener. Presence events are emitted whenever a member enters or leaves the presence set, or updates their user data. Use the "@presence.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#subscribe"@presence.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/subscribe%28event%3A%29-95gdn method in a room to receive updates: blang[react]. Subscribe to users' presence status with the "@usePresenceListener@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.usePresenceListener.html hook. Supply an optional listener to receive presence status updates, or use the "@presenceData@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UsePresenceListenerResponse.html#presenceData property returned by the hook. @@ -57,7 +58,14 @@ const MyComponent = () => { }; ``` -blang[javascript]. +```[swift] +let presenceSubscription = try await room.presence.subscribe(events: [.enter, .leave, .update]) +for await event in presenceSubscription { + print("Presence event `\(event.action)` from `\(event.clientId)` with data `\(event.data)`") +} +``` + +blang[javascript,swift]. You can also subscribe to only specific presence events, or an array of presence events: ```[javascript] @@ -72,6 +80,14 @@ blang[javascript]. }); ``` + ```[swift] + // Subscribe to only 'enter' events: + let presenceSubscription = try await room.presence.subscribe(event: .enter) + + // Subscribe to 'update' and 'leave' events: + let presenceSubscription = try await room.presence.subscribe(events: [.leave, .update]) + ``` + blang[react]. h3(#event-structure). Presence event structure @@ -98,10 +114,15 @@ The following are the properties of a presence event: h3(#unsubscribe). Unsubscribe from presence blang[javascript]. - Unsubscribe from online presence to remove previously registered listeners. + Use the @unsubscribe()@ function returned in the @subscribe()@ response to remove a presence listener: - Use the "@unsubscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.PresenceSubscriptionResponse.html#unsubscribe function returned in the @subscribe()@ response to remove a listener: +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a presence listener: +blang[react]. + When you unmount the component that is using the @usePresenceListener@ hook, it will automatically handle unsubscribing any associated listeners registered for presence status updates. + +blang[javascript,swift]. ```[javascript] // Initial subscription const { unsubscribe } = room.presence.subscribe((event) => { @@ -112,14 +133,20 @@ blang[javascript]. unsubscribe(); ``` + ```[swift] + presenceSubscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript]. Use the "@presence.unsubscribeAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#unsubscribeAll method to remove all presence listeners in a room: ```[javascript] await room.presence.unsubscribeAll(); ``` -blang[react]. - When you unmount the component that is using the @usePresenceListener@ hook, it will automatically handle unsubscribing any associated listeners registered for presence status updates. +blang[react,swift]. h2(#set). Set user presence @@ -129,8 +156,8 @@ Users can enter and leave the presence set of a room to indicate when they are o

Users must be identified to enter into the presence set. This means that they must set a @clientId@ when "instantiating their client":/chat/setup#instantiate.

-blang[javascript]. - Use the "@presence.enter()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#enter method to indicate when a user joins a room. This will send a presence event to all users subscribed to presence indicating that a new member has joined the chat. You can also set an optional data field with information such as the status of a user: +blang[javascript,swift]. + Use the "@presence.enter()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#enter"@presence.enter()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/enter%28data%3A%29 method to indicate when a user joins a room. This will send a presence event to all users subscribed to presence indicating that a new member has joined the chat. You can also set an optional data field with information such as the status of a user: blang[react]. Indicate when a user joins a room with the "@usePresence@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.usePresence.html hook. Users will automatically be entered into the presence set when the component mounts. @@ -159,8 +186,12 @@ const MyComponent = () => { }; ``` -blang[javascript]. - Use the "@presence.update()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#update method when a user wants to update their data, such as an update to their status, or to indicate that they're raising their hand. Updates will send a presence event ao all users subscribed to presence: +```[swift] +try await room.presence.enter(data: .init(userCustomData: ["status": .string("Online")])) +``` + +blang[javascript,swift]. + Use the "@presence.update()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#update"@presence.update()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/update%28data%3A%29 method when a user wants to update their data, such as an update to their status, or to indicate that they're raising their hand. Updates will send a presence event to all users subscribed to presence: blang[react]. Use the "@update()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UsePresenceResponse.html#update property available from the response of the @usePresence@ hook to update a user's data, such as setting their status to 'Away from keyboard'. @@ -191,8 +222,12 @@ const MyComponent = () => { }; ``` +```[swift] +try await room.presence.update(data: .init(userCustomData: ["status": .string("Busy")])) +``` + blang[javascript]. - Use the "@presence.leave()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#leave method to explicitly remove a user from the presence set. This will send a presence event to all users subscribed to presence. You can also set an optional data field such as setting a status of 'Back later'. + Use the "@presence.leave()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#leave"@presence.leave()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/leave%28data%3A%29 method to explicitly remove a user from the presence set. This will send a presence event to all users subscribed to presence. You can also set an optional data field such as setting a status of 'Back later'. blang[react]. Indicate when a user leaves a room with the "@usePresence@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.usePresence.html hook. Users will automatically be removed from the presence set when the component unmounts. @@ -218,6 +253,10 @@ const MyComponent = () => { }; ``` +```[swift] +try await room.presence.leave(data: .init(userCustomData: ["status": .string("Be back later!")])) +``` + When a user goes offline or closes their "connection":/chat/connect, a leave event is also emitted and they are removed from the presence set. h2(#options). Presence options @@ -237,10 +276,10 @@ blang[react]. h2(#retrieve). Retrieve the presence set -blang[javascript]. +blang[javascript,swift]. The online presence of users can be retrieved in one-off calls. This can be used to check the status of an individual user, or return the entire presence set as an array. - Use the "@presence.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#get method to retrieve an array of all users currently entered into the presence set, or individual users: + Use the "@presence.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#get"@presence.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/get%28%29 method to retrieve an array of all users currently entered into the presence set, or individual users: ```[javascript] // Retrieve all users entered into presence as an array: @@ -250,14 +289,29 @@ blang[javascript]. const presentMember = await room.presence.get({ clientId: 'clemons123' }); ``` - Alternatively, use the "@presence.isUserPresent()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#isUserPresent method and pass in a user's @clientId@ to check whether they are online or not. This will return a boolean: + ```[swift] + // Retrieve all users entered into presence as an array: + let presentMembers = try await room.presence.get() + + // Retrieve the status of specific users by their clientId: + let presentMember = try await room.presence.get(params: .init(clientID: "clemons123")) + ``` + +blang[react]. + Use the "@presenceData@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UsePresenceListener.html#presenceData property available from the response of the @usePresence@ hook to view a list of all member's presence status in the room. + +blang[javascript,swift]. + Alternatively, use the "@presence.isUserPresent()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#isUserPresent"@presence.isUserPresent()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/isuserpresent%28clientid%3A%29 method and pass in a user's @clientId@ to check whether they are online or not. This will return a boolean: ```[javascript] const isPresent = await room.presence.isUserPresent('clemons123'); ``` + ```[swift] + let isPresent = try await room.presence.isUserPresent(clientID: "clemons123") + ``` + blang[react]. - Use the "@presenceData@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UsePresenceListener.html#presenceData property available from the response of the @usePresence@ hook to view a list of all member's presence status in the room. h3(#member-structure). Presence member structure diff --git a/content/chat/rooms/reactions.textile b/content/chat/rooms/reactions.textile index 2e771dab4d..307a646903 100644 --- a/content/chat/rooms/reactions.textile +++ b/content/chat/rooms/reactions.textile @@ -5,6 +5,7 @@ product: chat languages: - javascript - react + - swift --- Users can send reactions to the entire chat room to show their sentiment as to what is happening. For example, agreeing with the content in a livestream using a thumbs up, or sending a heart when their team scores in a sports game. @@ -17,11 +18,11 @@ Room reactions are ephemeral and not stored or aggregated by Ably. The intention h2(#subscribe). Subscribe to room reactions -blang[javascript]. - Subscribe to room reactions by registering a listener. These events are emitted whenever a user sends a reaction, such as by hitting a 'like' button or clicking a heart emoji. Use the "@reactions.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#subscribe method in a room to receive reactions: +blang[javascript,swift]. + Subscribe to room reactions by registering a listener. Use the "@reactions.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#subscribe"@reactions.subscribe()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/subscribe%28%29-64gdf method in a room to receive reactions: blang[react]. - Subscribe to room reactions with the "@useRoomReactions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useRoomReactions.html hook. Supply an optional listener to receive the room reactions. + Subscribe to room reactions with the "@useRoomReactions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat_react.useRoomReactions.html hook. Supply an optional listener to receive the room reactions. ```[javascript] const {unsubscribe} = room.reactions.subscribe((reaction) => { @@ -42,6 +43,13 @@ const MyComponent = () => { }; ``` +```[swift] +let reactionSubscription = try await room.reactions.subscribe() +for await reaction in reactionSubscription { + print("Received a reaction of type \(reaction.type), and metadata \(reaction.metadata)") +} +``` + h3(#structure). Room reaction event structure The following is the structure of a room reaction event: @@ -72,10 +80,15 @@ The following are the properties of a room reaction: h3(#unsubscribe). Unsubscribe from room reactions blang[javascript]. - Unsubscribe from receiving room reactions to remove previously registered listeners. + Use the @unsubscribe()@ function returned in the @subscribe()@ response to remove a room reaction listener: - Use the "@unsubscribe()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactionsSubscriptionResponse.html#unsubscribe function returned in the @subscribe()@ response to remove a listener: +blang[swift]. + Use the @unsubscribe()@ method on the returned subscription to remove a room reaction listener: +blang[react]. + When you unmount the component that is using the @useRoomReactions@ hook, it will automatically handle unsubscribing any associated listeners registered for room reactions. + +blang[javascript,swift]. ```[javascript] // Initial subscription const {unsubscribe} = room.reactions.subscribe((reaction) => { @@ -86,19 +99,25 @@ blang[javascript]. unsubscribe(); ``` - Use the "@reactions.unsubscribeAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#unsubscribeAll method to remove all reaction listeners in a room: + ```[swift] + reactionSubscription.unsubscribe() + ``` + +blang[react]. + +blang[javascript]. + Use the "@reactions.unsubscribeAll()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#unsubscribeAll method to remove all room reaction listeners in a room: ```[javascript] await room.reactions.unsubscribeAll(); ``` -blang[react]. - When you unmount the component that is using the @useRoomReactions@ hook, it will automatically handle unsubscribing any associated listeners registered for room reactions. +blang[react,swift]. h2(#send). Send a room reaction -blang[javascript]. - Use the "@reactions.send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#send method to send a room-level reaction. The most common way of using this method is to trigger it whenever a user clicks an emoji button in a room: +blang[javascript,swift]. + Use the "@reactions.send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#send"@reactions.send()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/send%28params%3A%29 method to send a room-level reaction. The most common way of using this method is to trigger it whenever a user clicks an emoji button in a room: blang[react]. Use the "@send()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseRoomReactionsResponse.html#send method available from the response of the @useRoomReactions@ hook to emit an event when a user reacts, for example when they click an emoji button: @@ -126,3 +145,10 @@ const MyComponent = () => { ); }; ``` + +```[swift] +try await room.reactions.send(params: .init(type: "like")) + +try await room.reactions.send(params: .init(type: "heart", + metadata: ["effect": "fireworks"])) +``` diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index caee9146f1..87df65425c 100644 --- a/content/chat/rooms/typing.textile +++ b/content/chat/rooms/typing.textile @@ -5,9 +5,10 @@ product: chat languages: - javascript - react + - swift --- -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 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.