diff --git a/content/chat/connect.textile b/content/chat/connect.textile index 3c71c7650b..e5ca34079a 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. @@ -24,6 +25,9 @@ A connection can have any of the following statuses: 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[swift]. + Use the "@status@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.ConnectionStatus.html#status 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 +48,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,7 +69,7 @@ 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: @@ -69,6 +77,9 @@ blang[javascript]. 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. +blang[swift]. + Use the "@connection.onStatusChange(bufferingPolicy: .unbounded)@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Connection.html#onStatusChange method to create a subscription through which you can asynchronously iterate for the status updates: + ```[javascript] const { off } = chatClient.connection.status.onStatusChange((change) => console.log(change)); ``` @@ -86,6 +97,13 @@ const MyComponent = () => { }; ``` +```[swift] +let subscription = chatClient.connection.onStatusChange(bufferingPolicy: .unbounded) +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: @@ -101,14 +119,21 @@ blang[javascript]. blang[react]. +blang[swift]. + To stop the subscription from firing new status events, call its @unsubscribe()@ method: + + ```[swift] + subscription.unsubscribe() + ``` + h2(#discontinuity). Handle connection discontinuity If a client briefly loses connection to Ably, for example when driving through a tunnel, the SDK will attempt to recover the connection. If the disruption lasts for less than 2 minutes, then on reconnection the SDK will automatically reattach to any rooms and replay any missed messages. 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]. - 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[javascript,swift]. + Each feature of the Chat SDK provides an @subscribeToDiscontinuities()@ 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]. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a listener to be notified of, and handle, periods of discontinuity. @@ -136,6 +161,13 @@ const MyComponent = () => { }; ``` +```[swift] +let subscription = room.messages.subscribeToDiscontinuities() +for await error in subscription { + print("Recovering from the error: \(error)") +} +``` + blang[react]. blang[javascript]. @@ -145,10 +177,28 @@ blang[javascript]. off(); ``` +blang[swift]. + To cancel discontinuity subscribtion, call the provided @unsubscribe()@ method: + + ```[swift] + subscription.unsubscribe() + ``` + +blang[javascript,swift]. The following discontinuity handlers are available: + +blang[react]. +blang[javascript]. * "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 + +blang[swift]. + * "Messages":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Messages.html#subscribeToDiscontinuities + * "Presence":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Presence.html#subscribeToDiscontinuities + * "Occupancy":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Occupancy.html#subscribeToDiscontinuities + * "Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Typing.html#subscribeToDiscontinuities + * "Room reactions":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.RoomReactions.html#subscribeToDiscontinuities diff --git a/content/chat/rooms/history.textile b/content/chat/rooms/history.textile index 9ebffa2401..902478bdd5 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-swift/main/typedoc/interfaces/chat.Messages.html#get 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-swift/main/typedoc/interfaces/chat.MessageSubscription.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[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(bufferingPolicy: .unbounded) +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 438804e1b4..744b159266 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. @@ -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-swift/main/typedoc/interfaces/chat.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. ```[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,12 +121,16 @@ 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-swift/main/typedoc/interfaces/chat.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. ```[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. @@ -142,6 +166,10 @@ const MyComponent = () => { }; ``` +```[swift] +try await room.attach() +``` + h3(#detach). Detach from a room blang[javascript]. @@ -150,6 +178,10 @@ blang[javascript]. ```[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,8 @@ 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 "@status@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.RoomStatus.html 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,6 +235,10 @@ const MyComponent = () => { }; ``` +```[swift] +let status = try await room.status +``` + blang[javascript]. You can also subscribe to room status updates by registering a listener. An event will be emitted whenever the status of the room changes. @@ -243,3 +279,19 @@ blang[react]. return
Occupancy Component
; }; ``` + +blang[swift]. + You can also create a subscribtion to the room status updates. An event will be emitted whenever the status of the room changes. + + ```[swift] + let statusSubscription = try await room.onStatusChange(bufferingPolicy: .unbounded) + for await status in statusSubscription { + print("Room status: \(status)") + } + ``` + + To cancel the room status subscribtion, call the provided @unsubscribe()@ method: + + ```[swift] + statusSubscription.unsubscribe() + ``` diff --git a/content/chat/rooms/messages.textile b/content/chat/rooms/messages.textile index 9d87513e4b..d74d82ed20 100644 --- a/content/chat/rooms/messages.textile +++ b/content/chat/rooms/messages.textile @@ -5,6 +5,7 @@ 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. @@ -19,6 +20,9 @@ blang[react]. Providing a listener will also enable you to retrieve messages that have been "previously sent to the room.":/chat/rooms/history +blang[swift]. + Subscribe to receive messages in a room by creating a subscription. Use the "@messages.subscribe(bufferingPolicy: .unbounded)@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Messages.html#subscribe method in a room to receive all messages that are sent to it: + ```[javascript] const {unsubscribe} = room.messages.subscribe((message) => { console.log(message); @@ -40,6 +44,13 @@ const MyComponent = () => { }; ``` +```[swift] +let messagesSubscription = try await room.messages.subscribe(bufferingPolicy: .unbounded) +for await message in messagesSubscription { + print("Message received: \(message)") +} +``` + h3(#structure). Message structure The following is the structure of a message: @@ -88,19 +99,26 @@ blang[javascript]. await room.messages.unsubscribeAll(); ``` - - 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[swift]. + To cancel the room messages subscribtion, call the provided @unsubscribe()@ method: + + ```[swift] + messagesSubscription.unsubscribe() + ``` + + + 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-swift/main/typedoc/interfaces/chat.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[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: @@ -126,3 +144,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 b4ac2dede0..bd91b7010a 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. @@ -21,12 +22,22 @@ blang[javascript]. 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. +blang[swift]. + Subscribe to a room's occupancy by creating a subscription. Use the "@occupancy.subscribe(bufferingPolicy: .unbounded)@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Occupancy.html#subscribe method in a room to receive updates: + ```[javascript] const {unsubscribe} = room.occupancy.subscribe((event) => { console.log(event); }); ``` +```[swift] +let occupancySubscription = try await room.occupancy.subscribe(bufferingPolicy: .unbounded) +for await event in occupancySubscription { + occupancyInfo = "Connections: \(event.presenceMembers) (\(event.connections))" +} +``` + ```[react] import { useOccupancy } from '@ably/chat/react'; @@ -97,9 +108,16 @@ blang[javascript]. 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[swift]. + To cancel the room occupancy subscribtion, call the provided @unsubscribe()@ method: + + ```[swift] + occupancySubscription.unsubscribe() + ``` + 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: @@ -107,6 +125,10 @@ blang[javascript]. ```[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 8fdb0e7675..22203d6be8 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. @@ -23,6 +24,9 @@ blang[react]. To enter the presence set of a room, use the "@usePresence@":#set hook instead. +blang[swift]. + Subscribe to users' presence status by creating a subscription. 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-swift/main/typedoc/interfaces/chat.Presence.html#subscribe method in a room to receive updates: + ```[javascript] const { unsubscribe } = room.presence.subscribe((event) => { console.log(`${event.clientId} entered with data: ${event.data}`); @@ -57,7 +61,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 +83,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 @@ -121,6 +140,13 @@ blang[javascript]. 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[swift]. + To cancel the room presence subscribtion, call the provided @unsubscribe()@ method: + + ```[swift] + presenceSubscription.unsubscribe() + ``` + h2(#set). Set user presence Users can enter and leave the presence set of a room to indicate when they are online or offline. They can also set user data when entering and leaving the set, such as their current status. Presence is also linked to a user's "connection status":/chat/connect. For example, if a user goes offline then a leave event will be emitted for them. @@ -129,8 +155,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-swift/main/typedoc/interfaces/chat.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[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 +185,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-swift/main/typedoc/interfaces/chat.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 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 +221,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-swift/main/typedoc/interfaces/chat.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'. 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 +252,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 +275,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-swift/main/typedoc/interfaces/chat.Presence.html#get 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,15 +288,32 @@ 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]. + +blang[javascript,swift]. + Alternatively, use the "@presence.isUserPresent()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Presence.html#isUserPresent 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. +blang[javascript,swift]. + h3(#member-structure). Presence member structure The following is the structure of an individual presence member within the presence set: diff --git a/content/chat/rooms/reactions.textile b/content/chat/rooms/reactions.textile index e4c3dad798..3606cb2031 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,16 @@ Room reactions are ephemeral and not stored or aggregated by Ably. The intention h2(#subscribe). Subscribe to room reactions +Room reactions events are emitted whenever a user sends a reaction, such as by hitting a 'like' button or clicking a heart emoji. + 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: + 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 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. + +blang[swift]. + Subscribe to a room reactions by creating a subscription. Use the "@reactions.subscribe(bufferingPolicy: .unbounded)@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.RoomReactions.html#subscribe method in a room to receive reactions: ```[javascript] const {unsubscribe} = room.reactions.subscribe((reaction) => { @@ -42,6 +48,13 @@ const MyComponent = () => { }; ``` +```[swift] +let reactionSubscription = try await room.reactions.subscribe(bufferingPolicy: .unbounded) +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: @@ -95,10 +108,17 @@ blang[javascript]. 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[swift]. + To cancel the room reactions subscribtion, call the provided @unsubscribe()@ method: + + ```[swift] + reactionSubscription.unsubscribe() + ``` + 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-swift/main/typedoc/interfaces/chat.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[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 +146,10 @@ const MyComponent = () => { ); }; ``` + +```[swift] +try await room.reactions.send(params: .init(type: "like")) + +try await room.reactions.send(params: .init(type: "heart", + metadata: ["effect": .string("fireworks")])) +``` diff --git a/content/chat/rooms/typing.textile b/content/chat/rooms/typing.textile index cb3f20077a..97f93bbcc9 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 can be emitted when a user starts or stops typing.