From 8df54dace1ed974ef205df1858fe7e7d37952315 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 16 Nov 2026 18:03:34 +0530 Subject: [PATCH 1/6] docs(ios): offline support for the iOS UI Kit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WEaVigCRBjkftm78T25MQA --- docs.json | 1 + ui-kit/ios/core-features.mdx | 27 ++- ui-kit/ios/llms-ios-v5.mdx | 1 + ui-kit/ios/offline-support.mdx | 381 +++++++++++++++++++++++++++++++++ 4 files changed, 409 insertions(+), 1 deletion(-) create mode 100644 ui-kit/ios/offline-support.mdx diff --git a/docs.json b/docs.json index 40eea0779..4663677e8 100644 --- a/docs.json +++ b/docs.json @@ -1409,6 +1409,7 @@ "group": "Chat", "pages": [ "ui-kit/ios/core-features", + "ui-kit/ios/offline-support", "ui-kit/ios/extensions", "ui-kit/ios/ai-features" ] diff --git a/ui-kit/ios/core-features.mdx b/ui-kit/ios/core-features.mdx index 803f8232a..8bd797549 100644 --- a/ui-kit/ios/core-features.mdx +++ b/ui-kit/ios/core-features.mdx @@ -18,7 +18,8 @@ description: "Review CometChat iOS UI Kit core features for messaging, media sha {"name": "threadedConversations", "description": "Reply to specific messages in threads", "component": "CometChatThreadedMessageHeader", "enabledByDefault": true}, {"name": "threadSubscription", "description": "Subscribe to or unsubscribe from a thread's replies", "component": "CometChatMessageList", "enabledByDefault": false}, {"name": "groupChat", "description": "Create and manage group conversations", "component": "CometChatGroups", "enabledByDefault": true}, - {"name": "search", "description": "Search across conversations and messages", "component": "CometChatSearch", "enabledByDefault": true} + {"name": "search", "description": "Search across conversations and messages", "component": "CometChatSearch", "enabledByDefault": true}, + {"name": "offlineSupport", "description": "Show saved chats without a connection and queue sends until reconnect; turn on with UIKitSettings.setOfflineConfig(_:)", "component": "CometChatMessageList", "enabledByDefault": false} ], "relatedComponents": ["CometChatMessageList", "CometChatConversations", "CometChatMessageList", "CometChatMessageComposer"] } @@ -827,6 +828,30 @@ class SearchViewController: UIViewController { - [MessageHeader](/ui-kit/ios/message-header) - Search within conversation - [Conversations](/ui-kit/ios/conversations) - Search conversations +## Offline Support + +*Available since v5.3.0* + +Show chats the user has opened before without a connection, and queue messages sent offline until the connection returns. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. + +```swift lines +import CometChatUIKitSwift +import CometChatSDK + +let uikitSettings = UIKitSettings() + .set(appID: "APP_ID") + .set(region: "REGION") + .set(authKey: "AUTH_KEY") + .setOfflineConfig(OfflineConfig.Builder().setEnabled(true).build()) + .build() + +CometChatUIKit.init(uiKitSettings: uikitSettings) { result in + // Log in and show the UI Kit screens as usual. +} +``` + +Offline support needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for requirements, component behaviour, texts, styling and events. + ## Moderation Automatically filter inappropriate content. diff --git a/ui-kit/ios/llms-ios-v5.mdx b/ui-kit/ios/llms-ios-v5.mdx index 45bffa8d2..165f9d36f 100644 --- a/ui-kit/ios/llms-ios-v5.mdx +++ b/ui-kit/ios/llms-ios-v5.mdx @@ -132,6 +132,7 @@ component-level corrections from the component pages on top. - [Color Resources](/ui-kit/ios/color-resources) ## Features and extras +- [Offline Support](/ui-kit/ios/offline-support) - [Extensions](/ui-kit/ios/extensions) - [Campaigns](/ui-kit/ios/campaigns) - [Localize](/ui-kit/ios/localize) diff --git a/ui-kit/ios/offline-support.mdx b/ui-kit/ios/offline-support.mdx new file mode 100644 index 000000000..7737c85e3 --- /dev/null +++ b/ui-kit/ios/offline-support.mdx @@ -0,0 +1,381 @@ +--- +title: "Offline Support" +sidebarTitle: "Offline Support" +description: "Turn on offline support in the CometChat iOS UI Kit so saved chats open without a connection, sends queue until reconnect, and every list shows clear offline states." +--- + + + +| Field | Value | +| --- | --- | +| Default | Off. Nothing changes until you pass an `OfflineConfig` | +| Enable | `UIKitSettings().setOfflineConfig(OfflineConfig(enabled: true))` before `build()`, then `CometChatUIKit.init(uiKitSettings:)` | +| UI Kit | `CometChatUIKitSwift` 5.3.0 or later (Swift Package Manager) | +| Chat SDK | `CometChatSDK` 4.2.1 or later (resolved by the UI Kit package) | +| `OfflineConfig` options | [iOS SDK offline reference](/sdk/ios/offline-reference) | +| Styling | `CometChatMessageList.offlineStyle` (`CometChatOfflineStyle`) | +| Hide notices | `hideOfflineNotices` on `CometChatMessageList` and `CometChatConversations` | +| Events | `ccMessageSendStateChanged`, `ccOfflineCacheReset` on `CometChatMessageEventListener` | +| Discarded send | `CometChatUIKit.sendFormMessage` / `sendCardMessage` / `sendSchedulerMessage` call `onError` with `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset | + + + +With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Messages sent while offline wait in a queue and go out when the connection returns. Every list shows a clear state when it has nothing saved and can't reach the server. + +The UI Kit builds on the Chat SDK's offline support. This page covers what the UI Kit adds on top. For cache settings, encryption, media caching and sync, see the [iOS SDK offline docs](/sdk/ios/offline-overview). + +## Overview + +**Works offline:** +- Conversations, users, groups and group members you have loaded before show at once from the cache. +- Saved message history, including threads, opens without a connection. +- New messages, including media, are queued and sent automatically on reconnect. A queued message shows a clock until it is sent. +- Images, video, audio and files that are on the device open from the saved copy. +- After a reconnect, the SDK's catch-up brings in what changed while you were away, including a kick, ban or leave in a group. + +**Needs a connection:** +- The first load of any chat or list that was never opened before. +- Keyword search with no saved match. +- Editing or deleting a sent message, and adding or removing a reaction. These aren't queued. They report an error when there is no connection, and a failed reaction is rolled back. +- Message information, call logs, calls and AI streamed replies. +- Media that has no copy on the device. + +## Requirements + +| Requirement | Version | +| --- | --- | +| CometChat iOS UI Kit (`CometChatUIKitSwift`) | 5.3.0 or later | +| CometChat iOS Chat SDK (`CometChatSDK`) | 4.2.1 or later | +| iOS | 15.1 or later | +| Xcode | 16 or later | + +The UI Kit links the Chat SDK directly, so the higher SDK minimum applies to every app on UI Kit 5.3.0, whether or not it turns offline on. The UI Kit calls `CometChat.initFromSettings(offlineConfig:onSuccess:onError:)`, which Chat SDK 4.2.0 doesn't have. UI Kit 5.3.0 therefore needs a later Chat SDK, even though the [SDK offline pages](/sdk/ios/offline-enable) list 4.2.0 for using the SDK on its own. + +Install or update the UI Kit with Swift Package Manager: + +1. Go to **File → Add Package Dependencies** (or select the existing package to update it). +2. Enter the repository URL: + +``` +https://github.com/cometchat/cometchat-uikit-ios +``` + +3. Select **Up to Next Major Version** and enter: + +``` +5.3.0 +``` + +4. Add the **CometChatUIKitSwift** product to your app target. + +Swift Package Manager resolves `CometChatSDK` for you. If your project pins `chat-sdk-ios` to an exact version or to **Up to Next Minor Version** on 4.1.x, package resolution fails. Change that rule to **Up to Next Major Version** from 4.2.1. + + +**CocoaPods:** the latest UI Kit on CocoaPods is 5.1.18, and new releases ship through Swift Package Manager only. Offline support isn't available through CocoaPods. Move CocoaPods projects to Swift Package Manager to use it. + + +## Enable offline support + +Offline support is **off by default**. Turn it on by passing an `OfflineConfig` to `UIKitSettings.setOfflineConfig(_:)` before you call `build()` and `CometChatUIKit.init`. The UI Kit passes the config straight to the Chat SDK and stores nothing of its own. + +```swift lines +import UIKit +import CometChatUIKitSwift +import CometChatSDK + +class SceneDelegate: UIResponder, UIWindowSceneDelegate { + + var window: UIWindow? + + func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) { + guard let windowScene = (scene as? UIWindowScene) else { return } + + // Offline support is off unless you set a config with enabled = true. + let offlineConfig = OfflineConfig.Builder() + .setEnabled(true) + .build() + + let uikitSettings = UIKitSettings() + .set(appID: "APP_ID") // Replace with your App ID + .set(region: "REGION") // Replace with your Region + .set(authKey: "AUTH_KEY") // Replace with your Auth Key (dev only) + .subscribePresenceForAllUsers() + .setOfflineConfig(offlineConfig) + .build() + + CometChatUIKit.init(uiKitSettings: uikitSettings) { result in + switch result { + case .success: + // Log in, then show the UI Kit screens as usual. + debugPrint("CometChat initialized with offline support") + case .failure(let error): + debugPrint("Initialization failed: \(error.localizedDescription)") + } + } + } +} +``` + +`OfflineConfig` has more options, such as cache size, retention, the pending-message limit, encryption and media caching. Set only the ones you need. Every option is described in the [Configuration & API Reference](/sdk/ios/offline-reference#offlineconfig-options). You can also create the config with `OfflineConfig(enabled: true)`, as shown in [Enable Offline Support](/sdk/ios/offline-enable). + + +Offline support is active only while a user is logged in. Call `CometChat.isOfflineEnabled()` at the moment you need to know. See [Verify it is active](/sdk/ios/offline-enable). + + +## How the components behave offline + +### Lists: Conversations, Users, Groups and Group Members + +- Saved rows show first. The server page then loads and updates the list in place. +- Rows already on screen stay when a load can't reach the server. A failure caused by having no connection shows no error view. +- With nothing saved and no connection, the list shows an icon and **Connect to load chats** (or users, groups, members). This state has no Retry button. The list loads once by itself when the connection returns. +- Lists opened with only a filter, such as online users, tags, a scope, banned members or unread chats, behave like a plain list and show **Connect to load …**. +- Only a server answer of an empty page ends paging. + +### Search + +A **keyword** search with no saved match while offline shows **Connect to search** with a second line, **Search needs an internet connection.** It doesn't call `onError`. This applies to a non-empty keyword from the search box or from the list's request builder. A list opened with filters alone shows **Connect to load …** instead. + +`CometChatSearch` shows **Connect to search** when a keyword search can't connect, or when both the conversation and message requests fail because the device isn't connected. Results already on screen stay. A search showing the offline state runs again once when the connection returns. + +### Message list and threads + +- Saved history shows at once. Older and newer pages come from the cache first, then from the server. +- A chat that was never saved, opened offline, shows **Connect to load messages** and calls `onError`. It loads once by itself when the connection returns. +- When the list reaches the end of the saved messages with no connection, it shows a tappable **Connect to load more** row at that edge: older messages at the top, newer ones at the bottom. Tap it to try again. On reconnect each blocked edge loads once by itself, older first. Scrolling loads older messages again once the connection is back. +- Jumping to a message and starting from the first unread anchor on that message first. Paging and live messages don't scroll the list away until it has settled, for at most 6 seconds. If the target isn't saved and the server can't be reached, the chat stays on its newest page. +- When more messages arrive than one refresh can bridge, a **Jump to latest** pill appears. Your reading position stays until you tap it. +- Images, video, audio and files show the on-device copy first. With no copy and no connection, the bubble shows a placeholder with the file name, size and **Available when online**. It redraws as the normal bubble when the connection returns. Tapping it while connected asks the SDK to download the file. + +### Composer and unsent messages + +- A message sent while offline appears at once with a clock. It goes out automatically on reconnect. Media attachments queue the same way. +- An unsent message (pending, sending or failed) offers only **Retry** and **Delete** in its long-press menu and its VoiceOver actions. It offers no Copy, Reply, React or Edit until it has been sent. +- A failed message shows **Not sent. Tap to retry** under the bubble. Tapping that line or the failed icon retries it. Every failed message can be retried, whatever the reason. +- **Retry** asks the SDK to retry the queued message, so it never creates a duplicate. A message the SDK never queued (for example, refused because the queue was full or the file was too large) is sent again as a new send. +- **Delete** removes the unsent message. If it was already sent in the meantime, the sent copy is deleted instead. +- If the message is being sent at that moment, Retry and Delete change nothing and the list shows **Sending… try again in a moment** for 4 seconds. +- A full queue shows **Too many messages waiting to send**. A file that is too big for the offline media cache shows **File too large to send offline**. Each notice shows once per message. + +### Presence + +While the SDK isn't connected, nobody shows as online: there's no online dot in any list and no "Online" or last-seen subtitle in the message header. Presence returns when the UI Kit fetches users again after reconnecting. + +### Pinned, Saved, Reactions and Notifications + +`CometChatPinnedMessages`, `CometChatSavedMessages`, the reaction list and `CometChatNotificationFeed` follow the same rules as the other lists. Saved rows show first. With nothing saved and no connection, they show **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications**. + +### Logout and user switch + +Cached data belongs to the logged-in user. On logout or a user switch, the UI Kit clears every list on screen, search results, the notification feed, the pinned and saved panels and the composer's upload tray before the next user's first frame. Any message still waiting to be sent is answered with `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Send completions](#send-completions). + +## Offline states and texts + +Override any of these texts by defining the same key in your app's `Localizable.strings`, as described in [Localize](/ui-kit/ios/localize). Every language the UI Kit ships includes them. + +| Text | Key | Where it appears | +| --- | --- | --- | +| Connect to load chats | `CONNECT_TO_LOAD_CHATS` | `CometChatConversations` with nothing saved, offline | +| Connect to load users | `CONNECT_TO_LOAD_USERS` | `CometChatUsers` | +| Connect to load groups | `CONNECT_TO_LOAD_GROUPS` | `CometChatGroups` | +| Connect to load members | `CONNECT_TO_LOAD_MEMBERS` | `CometChatGroupMembers` | +| Connect to load messages | `CONNECT_TO_LOAD_MESSAGES` | `CometChatMessageList`, `CometChatPinnedMessages`, `CometChatSavedMessages` | +| Connect to load reactions | `CONNECT_TO_LOAD_REACTIONS` | Reaction list | +| Connect to load notifications | `CONNECT_TO_LOAD_NOTIFICATIONS` | `CometChatNotificationFeed` | +| Connect to search | `CONNECT_TO_SEARCH` | Keyword search in a list, offline, no saved match | +| Connect to search | `CONNECT_TO_SEARCH_MESSAGES` | `CometChatSearch` | +| Search needs an internet connection. | `CONNECT_TO_SEARCH_SUBTITLE` | Second line under "Connect to search" | +| Connect to load more | `CONNECT_TO_LOAD_MORE` | Message list and threads, at a blocked edge | +| Not sent yet | `MESSAGE_NOT_SENT_YET` | VoiceOver label of a queued message's clock | +| Not sent. Tap to retry | `MESSAGE_NOT_SENT_TAP_TO_RETRY` | Under a failed message | +| Sending… try again in a moment | `SEND_IN_FLIGHT` | Retry or Delete on a message being sent | +| Available when online | `MEDIA_AVAILABLE_WHEN_ONLINE` | Media placeholder | +| Jump to latest | `JUMP_TO_LATEST` | Message list pill | +| Too many messages waiting to send | `OFFLINE_QUEUE_FULL` | Notice when the queue is full | +| File too large to send offline | `OFFLINE_FILE_TOO_LARGE` | Notice when media doesn't fit the cache | +| 1 unsent message was removed | `UNSENT_MESSAGE_REMOVED` | Notice | +| 1 message wasn't sent / %d messages weren't sent | `MESSAGES_NOT_SENT_ONE` / `MESSAGES_NOT_SENT_OTHER` | Notice | +| 1 unsent message couldn't be recovered / %d unsent messages couldn't be recovered | `UNSENT_MESSAGES_LOST_ONE` / `UNSENT_MESSAGES_LOST_OTHER` | Notice after the SDK resets its cache | +| Some unsent messages may not have been sent | `UNSENT_MESSAGES_MAYBE_LOST` | Notice after a cache reset with an unknown count | + +## Errors and callbacks + +### When `onError` fires + +With offline support on, every list follows the same rules: + +- **Rows on screen, no connection:** the rows stay. No error view, no `onError`. +- **Rows on screen, any other error:** the rows stay. `onError` fires once if the user or your app started the load: opening the screen, pull to refresh, a new keyword, paging, a jump or Retry. A reload the UI Kit starts itself after a reconnect, sync or cache reset stays quiet. +- **Nothing on screen, no connection:** the **Connect to load …** state shows, and `onError` fires once. +- **Nothing on screen, any other error:** the error view with Retry shows, and `onError` fires. +- **Keyword search offline with nothing saved:** **Connect to search** shows, with no `onError`. +- **Empty server answer:** the normal empty view. + +`CometChatSearch` and the reaction list now also have `set(onError:)`. + +### Send completions + +`CometChatUIKit.sendFormMessage`, `CometChatUIKit.sendCardMessage` and `CometChatUIKit.sendSchedulerMessage` answer each send once: + +- `onSuccess` fires when the server accepts the message. +- `onError` fires when the SDK reports a failure. +- A send that is only queued (offline) calls neither while the session lasts. +- If the user logs out, switches user, or the offline cache is reset before the message was sent, `onError` fires once, quietly, with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. The UI Kit shows no error for it: the message row going away is the only visible signal. + +```swift lines +import CometChatUIKitSwift +import CometChatSDK + +func send(_ formMessage: FormMessage) { + CometChatUIKit.sendFormMessage(formMessage, onSuccess: { sent in + print("Form message sent: \(sent.id)") + }, onError: { error in + if error?.errorCode == "ERROR_OFFLINE_MESSAGE_DISCARDED" { + // Logout, user switch or cache reset before it was sent. Don't show an error. + return + } + print("Send failed: \(error?.errorDescription ?? "")") + }) +} +``` + +The UI Kit's own senders (the composers, stickers and smart replies) handle this case themselves and show no error. + +### Offline events + +`CometChatMessageEventListener` has two events for offline support. Both have empty default bodies, so you implement only the ones you need. Neither fires while offline support is off. + +| Event | Fires when | +| --- | --- | +| `ccMessageSendStateChanged(message:state:reason:)` | An own message moves between `CometChatMessageSendState` values: `.sending`, `.sent`, `.failed` or `.discarded`. `reason` is the SDK's `CometChat.MessageFailureReason`, if any. | +| `ccOfflineCacheReset(reason:pendingMessagesLost:)` | The Chat SDK reset its on-device cache. `pendingMessagesLost` is `CometChat.offlinePendingCountUnknown` (`-1`) when the SDK can't tell how many unsent messages were lost. | + +```swift lines +import UIKit +import CometChatUIKitSwift +import CometChatSDK + +class ChatViewController: UIViewController, CometChatMessageEventListener { + + override func viewDidLoad() { + super.viewDidLoad() + CometChatMessageEvents.addListener("offline-listener", self) + } + + override func viewWillDisappear(_ animated: Bool) { + super.viewWillDisappear(animated) + CometChatMessageEvents.removeListener("offline-listener") + } + + func ccMessageSendStateChanged(message: BaseMessage, state: CometChatMessageSendState, reason: CometChat.MessageFailureReason?) { + print("Message \(message.muid) is now \(state)") + } + + func ccOfflineCacheReset(reason: CometChat.OfflineCacheResetReason, pendingMessagesLost: Int) { + print("Offline cache reset, unsent messages lost: \(pendingMessagesLost)") + } +} +``` + +For the SDK's own reasons and error codes, see the [Configuration & API Reference](/sdk/ios/offline-reference#error-codes). + +## Customization + +### Offline style + +`CometChatMessageList.offlineStyle` is a global `CometChatOfflineStyle`. Each property defaults to the theme's existing error or secondary-text tokens, so nothing changes until you set one. + +| Property | Type | Default | Applies to | +| --- | --- | --- | --- | +| `retryTextColor` | `UIColor` | `CometChatTheme.errorColor` | "Not sent. Tap to retry" | +| `retryTextFont` | `UIFont` | `CometChatTypography.Caption1.medium` | "Not sent. Tap to retry" | +| `failedIconTint` | `UIColor?` | `nil` (the receipt style's error tint) | Failed status icon of an unsent message | +| `notSentYetTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Not sent yet", where shown as text | +| `notSentYetTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Not sent yet", where shown as text | +| `mediaPlaceholderTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Available when online" media placeholder | +| `mediaPlaceholderTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Available when online" media placeholder | +| `footerTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Connect to load more" rows | +| `footerTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Connect to load more" rows | +| `jumpToLatestTextColor` | `UIColor` | `CometChatTheme.white` | "Jump to latest" pill text | +| `jumpToLatestTextFont` | `UIFont` | `CometChatTypography.Caption1.medium` | "Jump to latest" pill text | +| `jumpToLatestBackgroundColor` | `UIColor` | `CometChatTheme.primaryColor` | "Jump to latest" pill background | + +```swift lines +import UIKit +import CometChatUIKitSwift + +var offlineStyle = CometChatOfflineStyle() +offlineStyle.retryTextColor = .systemRed +offlineStyle.footerTextColor = .systemGray +offlineStyle.jumpToLatestTextColor = .white +offlineStyle.jumpToLatestBackgroundColor = .systemIndigo +offlineStyle.jumpToLatestTextFont = .systemFont(ofSize: 13, weight: .semibold) + +CometChatMessageList.offlineStyle = offlineStyle +``` + +### Hide offline notices + +| Property | Component | Default | Hides | +| --- | --- | --- | --- | +| `hideOfflineNotices` | `CometChatMessageList` | `false` | The offline notices (a removed unsent message, a full queue, unsent messages that couldn't be recovered), the "Connect to load more" rows and the "Jump to latest" pill | +| `hideOfflineNotices` | `CometChatConversations` | `false` | Notices about the whole cache, such as unsent messages that couldn't be recovered | + +```swift +let messageList = CometChatMessageList() +messageList.hideOfflineNotices = true + +let conversations = CometChatConversations() +conversations.hideOfflineNotices = true +``` + +### Your own empty and error views + +- If you set a custom error view (`errorStateView` on a list, or `set(errorView:)` on the message list), it shows instead of the UI Kit's **Connect to load …** state. +- If you set `hideErrorView = true`, no offline state shows. +- If you set a custom `emptyStateView`, it shows instead of **Connect to search**. `disableEmptyState = true` hides it. + +## With offline support turned off + +Apps that don't turn on offline support keep today's behaviour, with these exceptions in UI Kit 5.3.0: + +- **Higher Chat SDK minimum.** The UI Kit needs Chat SDK 4.2.1 or later, whether or not offline is on. An exact or up-to-next-minor pin on 4.1.x stops package resolution until you update it. +- **New accessibility identifiers.** `accessibilityIdentifier` is now set on message rows and their menu, notices, list footers, the composer, attachment tray tiles, conversation rows, and the empty and error views. This applies to release builds too. They hold no message text and don't change what VoiceOver reads. A conversation row's identifier includes the user's uid or the group's guid. If your UI tests or view snapshots assert on these identifiers, expect them to change. +- **Group Members and Notification Feed refresh on reconnect.** Each reconnect now reloads the first page. A list on screen is never blanked. +- **`MessageListViewModel.add(message:)` replaces a message that is already shown** with the same server id, instead of adding a second row. +- **A failed reaction is rolled back correctly.** The reaction count, your own reaction and its position return to what they were. +- **The failed-send event keeps your metadata.** `ccMessageSent` with `.error` now carries the message's `metaData` with `error: true` added, instead of replacing it. +- **Paging after a jump skips unsent rows.** The older and newer requests use the oldest and newest message that has a server id. + +## Limitations and known issues + +- If a send acknowledgement is lost, the server can end up with one duplicate of the message. +- After a quick reconnect, missed messages can take up to 15 seconds to appear. +- After an app restart, the reason a message failed may be unknown. It's still offered Retry. +- If a send gets no answer while connected, the chat can stop updating until the next reconnect. +- Keyword search, message information, call logs and AI streamed replies need a connection. +- Media downloaded for offline use is stored unencrypted on the device. The message cache itself can be encrypted. See [Encrypt the Cache](/sdk/ios/offline-encryption). +- Depending on the SDK build, a queue-full or file-too-large refusal can first show as pending. The UI Kit shows these messages as failed either way and shows the notice once. + +## Next steps + + + + How the Chat SDK caches and syncs data + + + Every `OfflineConfig` option, listener and error code + + + The SDK's queue, retry and discard + + + Catch-up after reconnect and cache resets + + + Message list properties and styling + + + Override the offline texts + + From 405c8ca21f1eab399defde5dd6d232debf0b5bfa Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:46:57 +0530 Subject: [PATCH 2/6] docs(ENG-57593): correct the iOS offline support page against UI Kit 5.3.0 Files picked in the attachment tray upload at once and are not queued; only text, voice notes and single-file sends queue. Failed edits, reactions and deletes now show a notice; the compact composer leaves edit mode on Send. Adds "Not sent yet" under queued messages, Retry and Delete removing a message the SDK no longer holds, the reaction list's tabs, the avatar cache, the logout cache wipe, the media-link and cc_media change, and corrects the notices table, presence, the event wording and the catch-up delay (10 s in the SDK). Co-Authored-By: Claude Opus 5.5 --- ui-kit/ios/core-features.mdx | 2 +- ui-kit/ios/offline-support.mdx | 45 +++++++++++++++++++--------------- 2 files changed, 26 insertions(+), 21 deletions(-) diff --git a/ui-kit/ios/core-features.mdx b/ui-kit/ios/core-features.mdx index 8bd797549..fea661c45 100644 --- a/ui-kit/ios/core-features.mdx +++ b/ui-kit/ios/core-features.mdx @@ -832,7 +832,7 @@ class SearchViewController: UIViewController { *Available since v5.3.0* -Show chats the user has opened before without a connection, and queue messages sent offline until the connection returns. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. +Show chats the user has opened before without a connection, and queue messages sent offline until the connection returns. Files picked in the attachment tray still need a connection to upload. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. ```swift lines import CometChatUIKitSwift diff --git a/ui-kit/ios/offline-support.mdx b/ui-kit/ios/offline-support.mdx index 7737c85e3..ffd4d5c18 100644 --- a/ui-kit/ios/offline-support.mdx +++ b/ui-kit/ios/offline-support.mdx @@ -1,7 +1,7 @@ --- title: "Offline Support" sidebarTitle: "Offline Support" -description: "Turn on offline support in the CometChat iOS UI Kit so saved chats open without a connection, sends queue until reconnect, and every list shows clear offline states." +description: "Turn on offline support in the CometChat iOS UI Kit so saved chats open without a connection, messages queue until reconnect, and every list shows clear offline states." --- @@ -20,7 +20,7 @@ description: "Turn on offline support in the CometChat iOS UI Kit so saved chats -With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Messages sent while offline wait in a queue and go out when the connection returns. Every list shows a clear state when it has nothing saved and can't reach the server. +With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Messages sent while offline wait in a queue and go out when the connection returns. Files picked in the attachment tray are the exception: they upload as soon as they're picked, so they need a connection. Every list shows a clear state when it has nothing saved and can't reach the server. The UI Kit builds on the Chat SDK's offline support. This page covers what the UI Kit adds on top. For cache settings, encryption, media caching and sync, see the [iOS SDK offline docs](/sdk/ios/offline-overview). @@ -29,14 +29,16 @@ The UI Kit builds on the Chat SDK's offline support. This page covers what the U **Works offline:** - Conversations, users, groups and group members you have loaded before show at once from the cache. - Saved message history, including threads, opens without a connection. -- New messages, including media, are queued and sent automatically on reconnect. A queued message shows a clock until it is sent. +- New text messages, voice notes and messages sent with the `CometChatUIKit` send methods are queued and sent automatically on reconnect. A queued message shows a clock and **Not sent yet** until it is sent. - Images, video, audio and files that are on the device open from the saved copy. +- Avatars the user has seen are kept on the device (up to 250 MB), so lists and headers show them offline. - After a reconnect, the SDK's catch-up brings in what changed while you were away, including a kick, ban or leave in a group. **Needs a connection:** - The first load of any chat or list that was never opened before. - Keyword search with no saved match. -- Editing or deleting a sent message, and adding or removing a reaction. These aren't queued. They report an error when there is no connection, and a failed reaction is rolled back. +- Uploading a photo, video, audio file or document picked in the attachment tray (`enableMultipleAttachments`, on by default). The message can be sent once its files have uploaded. +- Editing or deleting a sent message, and adding or removing a reaction. These aren't queued. When one fails, the UI Kit shows the notice **No Internet Connection. Please try again later.** (or **Something went wrong, please try again.** for any other error) and the message keeps what it had. A failed reaction is rolled back. - Message information, call logs, calls and AI streamed replies. - Media that has no copy on the device. @@ -143,31 +145,34 @@ A **keyword** search with no saved match while offline shows **Connect to search - Saved history shows at once. Older and newer pages come from the cache first, then from the server. - A chat that was never saved, opened offline, shows **Connect to load messages** and calls `onError`. It loads once by itself when the connection returns. - When the list reaches the end of the saved messages with no connection, it shows a tappable **Connect to load more** row at that edge: older messages at the top, newer ones at the bottom. Tap it to try again. On reconnect each blocked edge loads once by itself, older first. Scrolling loads older messages again once the connection is back. -- Jumping to a message and starting from the first unread anchor on that message first. Paging and live messages don't scroll the list away until it has settled, for at most 6 seconds. If the target isn't saved and the server can't be reached, the chat stays on its newest page. +- Jumping to a message, or starting from the first unread message, shows the list around that message first. Paging and live messages don't scroll the list away until it has settled, for at most 6 seconds. If the target isn't saved and the server can't be reached, the chat stays on its newest page. - When more messages arrive than one refresh can bridge, a **Jump to latest** pill appears. Your reading position stays until you tap it. - Images, video, audio and files show the on-device copy first. With no copy and no connection, the bubble shows a placeholder with the file name, size and **Available when online**. It redraws as the normal bubble when the connection returns. Tapping it while connected asks the SDK to download the file. ### Composer and unsent messages -- A message sent while offline appears at once with a clock. It goes out automatically on reconnect. Media attachments queue the same way. +- A text message or voice note sent while offline appears at once with a clock and **Not sent yet** under the bubble (unless the bubble already has a bottom view). It goes out automatically on reconnect. +- Photos, videos, audio files and documents picked in the attachment tray are **not** queued. Each file starts uploading as soon as it's picked, and uploading needs a connection, so the message can't be sent until its files have uploaded. A tile whose upload failed shows a retry control: tap it to upload that file again once you're back online. With offline support on, the files staged in a chat's tray are kept on the device for that chat, so they come back when the chat is opened again. With `enableMultipleAttachments = false`, a picked file is sent as a single media message, and that message is queued like a text message. - An unsent message (pending, sending or failed) offers only **Retry** and **Delete** in its long-press menu and its VoiceOver actions. It offers no Copy, Reply, React or Edit until it has been sent. -- A failed message shows **Not sent. Tap to retry** under the bubble. Tapping that line or the failed icon retries it. Every failed message can be retried, whatever the reason. +- A failed message shows **Not sent. Tap to retry** under the bubble. Tapping that line or the status icon retries it, and VoiceOver reads the hint "Retry" on both. Every failed message can be retried, whatever the reason. Tapping the clock of a queued message retries it too; a message the SDK is sending at that moment keeps a plain clock. - **Retry** asks the SDK to retry the queued message, so it never creates a duplicate. A message the SDK never queued (for example, refused because the queue was full or the file was too large) is sent again as a new send. - **Delete** removes the unsent message. If it was already sent in the meantime, the sent copy is deleted instead. +- If the SDK no longer holds the unsent message (for example, it was removed after you left the group), Retry and Delete remove it from the list. - If the message is being sent at that moment, Retry and Delete change nothing and the list shows **Sending… try again in a moment** for 4 seconds. - A full queue shows **Too many messages waiting to send**. A file that is too big for the offline media cache shows **File too large to send offline**. Each notice shows once per message. +- **Editing** a message needs a connection. If the edit fails, the message keeps its old text, the composer's `onError` fires, and the UI Kit shows **No Internet Connection. Please try again later.** (or **Something went wrong, please try again.**). `CometChatMessageComposer` keeps the edited text and the edit banner so you can try again. `CometChatCompactMessageComposer` leaves edit mode as soon as you tap Send, so the next message you type is a new message, not another edit. ### Presence -While the SDK isn't connected, nobody shows as online: there's no online dot in any list and no "Online" or last-seen subtitle in the message header. Presence returns when the UI Kit fetches users again after reconnecting. +While the SDK isn't connected (including while it is still connecting), nobody shows as online: there's no online dot in any list and no "Online" or last-seen subtitle in the message header. Presence shows again once the SDK is connected. The users list and the message header also fetch the user again after reconnecting. ### Pinned, Saved, Reactions and Notifications -`CometChatPinnedMessages`, `CometChatSavedMessages`, the reaction list and `CometChatNotificationFeed` follow the same rules as the other lists. Saved rows show first. With nothing saved and no connection, they show **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications**. +`CometChatPinnedMessages`, `CometChatSavedMessages`, the reaction list and `CometChatNotificationFeed` follow the same rules as the other lists. Saved rows show first. With nothing saved and no connection, they show **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications**. The reaction list keeps its tabs visible and shows **Connect to load reactions** below them. ### Logout and user switch -Cached data belongs to the logged-in user. On logout or a user switch, the UI Kit clears every list on screen, search results, the notification feed, the pinned and saved panels and the composer's upload tray before the next user's first frame. Any message still waiting to be sent is answered with `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Send completions](#send-completions). +Cached data belongs to the logged-in user. The Chat SDK deletes the user's offline cache on logout and when a different user logs in, and the UI Kit deletes the avatars it saved on the device. On logout or a user switch, the UI Kit also clears every list on screen, search results, the notification feed, the pinned and saved panels and the composer's upload tray before the next user's first frame. Any message still waiting to be sent is answered with `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Send completions](#send-completions). ## Offline states and texts @@ -186,16 +191,16 @@ Override any of these texts by defining the same key in your app's `Localizable. | Connect to search | `CONNECT_TO_SEARCH_MESSAGES` | `CometChatSearch` | | Search needs an internet connection. | `CONNECT_TO_SEARCH_SUBTITLE` | Second line under "Connect to search" | | Connect to load more | `CONNECT_TO_LOAD_MORE` | Message list and threads, at a blocked edge | -| Not sent yet | `MESSAGE_NOT_SENT_YET` | VoiceOver label of a queued message's clock | -| Not sent. Tap to retry | `MESSAGE_NOT_SENT_TAP_TO_RETRY` | Under a failed message | +| Not sent yet | `MESSAGE_NOT_SENT_YET` | Under a queued or sending message, and the VoiceOver label of its clock | +| Not sent. Tap to retry | `MESSAGE_NOT_SENT_TAP_TO_RETRY` | Under a failed message, and the VoiceOver label of its status icon | | Sending… try again in a moment | `SEND_IN_FLIGHT` | Retry or Delete on a message being sent | | Available when online | `MEDIA_AVAILABLE_WHEN_ONLINE` | Media placeholder | | Jump to latest | `JUMP_TO_LATEST` | Message list pill | | Too many messages waiting to send | `OFFLINE_QUEUE_FULL` | Notice when the queue is full | | File too large to send offline | `OFFLINE_FILE_TOO_LARGE` | Notice when media doesn't fit the cache | -| 1 unsent message was removed | `UNSENT_MESSAGE_REMOVED` | Notice | -| 1 message wasn't sent / %d messages weren't sent | `MESSAGES_NOT_SENT_ONE` / `MESSAGES_NOT_SENT_OTHER` | Notice | -| 1 unsent message couldn't be recovered / %d unsent messages couldn't be recovered | `UNSENT_MESSAGES_LOST_ONE` / `UNSENT_MESSAGES_LOST_OTHER` | Notice after the SDK resets its cache | +| 1 unsent message was removed | `UNSENT_MESSAGE_REMOVED` | Notice when the SDK removes a queued message, for example when a full queue drops its oldest message | +| 1 message wasn't sent / %d messages weren't sent | `MESSAGES_NOT_SENT_ONE` / `MESSAGES_NOT_SENT_OTHER` | Message list notice when offline support turns off during a session while unsent messages are shown. They turn failed and can be retried | +| 1 unsent message couldn't be recovered / %d unsent messages couldn't be recovered | `UNSENT_MESSAGES_LOST_ONE` / `UNSENT_MESSAGES_LOST_OTHER` | Message list and conversations notice after the SDK resets its cache | | Some unsent messages may not have been sent | `UNSENT_MESSAGES_MAYBE_LOST` | Notice after a cache reset with an unknown count | ## Errors and callbacks @@ -243,7 +248,7 @@ The UI Kit's own senders (the composers, stickers and smart replies) handle this ### Offline events -`CometChatMessageEventListener` has two events for offline support. Both have empty default bodies, so you implement only the ones you need. Neither fires while offline support is off. +`CometChatMessageEventListener` has two events for offline support. Both have empty default bodies, so you implement only the ones you need. An app that never turns offline support on never receives them. | Event | Fires when | | --- | --- | @@ -290,8 +295,8 @@ For the SDK's own reasons and error codes, see the [Configuration & API Referenc | `retryTextColor` | `UIColor` | `CometChatTheme.errorColor` | "Not sent. Tap to retry" | | `retryTextFont` | `UIFont` | `CometChatTypography.Caption1.medium` | "Not sent. Tap to retry" | | `failedIconTint` | `UIColor?` | `nil` (the receipt style's error tint) | Failed status icon of an unsent message | -| `notSentYetTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Not sent yet", where shown as text | -| `notSentYetTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Not sent yet", where shown as text | +| `notSentYetTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Not sent yet" under a queued or sending message | +| `notSentYetTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Not sent yet" under a queued or sending message | | `mediaPlaceholderTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Available when online" media placeholder | | `mediaPlaceholderTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Available when online" media placeholder | | `footerTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Connect to load more" rows | @@ -346,16 +351,16 @@ Apps that don't turn on offline support keep today's behaviour, with these excep - **A failed reaction is rolled back correctly.** The reaction count, your own reaction and its position return to what they were. - **The failed-send event keeps your metadata.** `ccMessageSent` with `.error` now carries the message's `metaData` with `error: true` added, instead of replacing it. - **Paging after a jump skips unsent rows.** The older and newer requests use the oldest and newest message that has a server id. +- **Media links that name a file on the device are used only for your own messages.** A `file://` link or an absolute path in another user's message is no longer opened, shown or shared. Image and file bubbles now keep their downloads in `Documents/cc_media/`, so files saved earlier in the app's Documents folder are downloaded again. ## Limitations and known issues - If a send acknowledgement is lost, the server can end up with one duplicate of the message. -- After a quick reconnect, missed messages can take up to 15 seconds to appear. +- After a quick reconnect, missed messages can take up to about 10 seconds to appear, because the Chat SDK waits at least 10 seconds between two catch-up syncs. - After an app restart, the reason a message failed may be unknown. It's still offered Retry. - If a send gets no answer while connected, the chat can stop updating until the next reconnect. - Keyword search, message information, call logs and AI streamed replies need a connection. - Media downloaded for offline use is stored unencrypted on the device. The message cache itself can be encrypted. See [Encrypt the Cache](/sdk/ios/offline-encryption). -- Depending on the SDK build, a queue-full or file-too-large refusal can first show as pending. The UI Kit shows these messages as failed either way and shows the notice once. ## Next steps From a258495cb71453783474807e8c35d40fdd4c8d30 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:46:57 +0530 Subject: [PATCH 3/6] docs(ENG-57593): mention offline support across the iOS UI Kit pages Methods documents UIKitSettings.setOfflineConfig(_:) with an example, and what logout and the send methods do with offline on. Integration, events, localize, search, message list, conversations, both composers, the thread header and bubble styling get one line each with a link to the offline page. Search no longer says it has no onError. Co-Authored-By: Claude Opus 5.5 --- ui-kit/ios/compact-message-composer.mdx | 4 +++ ui-kit/ios/conversations.mdx | 12 +++++++ ui-kit/ios/events.mdx | 2 ++ ui-kit/ios/getting-started.mdx | 5 +++ ui-kit/ios/localize.mdx | 2 ++ ui-kit/ios/message-bubble-styling.mdx | 2 ++ ui-kit/ios/message-composer.mdx | 4 +++ ui-kit/ios/message-list.mdx | 18 +++++++++++ ui-kit/ios/methods.mdx | 42 +++++++++++++++++++++++++ ui-kit/ios/search.mdx | 13 ++++++-- ui-kit/ios/threaded-messages-header.mdx | 2 ++ 11 files changed, 104 insertions(+), 2 deletions(-) diff --git a/ui-kit/ios/compact-message-composer.mdx b/ui-kit/ios/compact-message-composer.mdx index 464bcb5d9..d234602f2 100644 --- a/ui-kit/ios/compact-message-composer.mdx +++ b/ui-kit/ios/compact-message-composer.mdx @@ -275,6 +275,10 @@ compactComposer.enableMultipleAttachments = false This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/ui-kit/ios/message-list)). +### Sending while offline + +With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. With `enableMultipleAttachments = false`, a picked file is sent as a single media message and is queued too. In edit mode, tapping Send leaves edit mode at once. If the edit then fails, the message keeps its old text, `onError` fires and a notice shows, and the next message you type is sent as a new message. + --- ## Rich Text Formatting diff --git a/ui-kit/ios/conversations.mdx b/ui-kit/ios/conversations.mdx index 91baf9b81..45904aec4 100644 --- a/ui-kit/ios/conversations.mdx +++ b/ui-kit/ios/conversations.mdx @@ -42,6 +42,7 @@ The `CometChatConversations` component displays a list of all conversations (one "hideSearch": { "type": "Bool", "default": false }, "hideReceipts": { "type": "Bool", "default": false }, "hideUserStatus": { "type": "Bool", "default": false }, + "hideOfflineNotices": { "type": "Bool", "default": false, "note": "Offline support only (v5.3.0+)" }, "hideGroupType": { "type": "Bool", "default": false }, "hideDeleteConversationOption": { "type": "Bool", "default": false }, "hideNavigationBar": { "type": "Bool", "default": false }, @@ -1135,6 +1136,17 @@ Hides the entire navigation bar. | Type | `Bool` | | Default | `false` | +### hideOfflineNotices + +*Available since v5.3.0* + +Hides the [offline support](/ui-kit/ios/offline-support#hide-offline-notices) notices about the whole cache, such as unsent messages that couldn't be recovered. With offline support on, the list shows saved conversations first, and **Connect to load chats** when nothing is saved and there is no connection. + +| | | +|---|---| +| Type | `Bool` | +| Default | `false` | + ### hideReceipts Hides read/delivered receipt indicators. diff --git a/ui-kit/ios/events.mdx b/ui-kit/ios/events.mdx index f7c01fd7d..d6479376c 100644 --- a/ui-kit/ios/events.mdx +++ b/ui-kit/ios/events.mdx @@ -580,6 +580,8 @@ CometChatMessageEvents.ccMessageSaved(message: savedMessage, status: .success) | `onVoiceCall` | Voice call initiated | | `onVideoCall` | Video call initiated | | `onMessageError` | Message operation failed | +| `ccMessageSendStateChanged` | An own message moved between sending, sent, failed and discarded. Only with [offline support](/ui-kit/ios/offline-support#offline-events) on | +| `ccOfflineCacheReset` | The Chat SDK reset its offline cache. Only with [offline support](/ui-kit/ios/offline-support#offline-events) on | ## Card Events diff --git a/ui-kit/ios/getting-started.mdx b/ui-kit/ios/getting-started.mdx index 5db0e5e1c..de3fbefbf 100644 --- a/ui-kit/ios/getting-started.mdx +++ b/ui-kit/ios/getting-started.mdx @@ -17,6 +17,7 @@ description: "Integrate CometChat iOS UI Kit with project setup, package install | Auth Key | Dev/testing only. Use Auth Token in production | | Calling | Optional. Add `CometChatCallsSDK` 5.0.4 (Up to Next Major Version) to enable | | Dependencies | `CometChatSDK` 4.1.10+ (resolved automatically by the UI Kit package) | +| Offline support | Optional, off by default. `UIKitSettings().setOfflineConfig(_:)` before `build()`. Needs UI Kit 5.3.0+ and `CometChatSDK` 4.2.1+. See [Offline Support](/ui-kit/ios/offline-support) | | AI Skills | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) | @@ -238,6 +239,10 @@ After running the app, you should see: For production, use [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-auth-token) instead of Auth Key. Generate tokens server-side via the REST API. + +To let users open saved chats and queue messages without a connection, add `.setOfflineConfig(OfflineConfig(enabled: true))` to `UIKitSettings` before `.build()`. Offline support is off by default and needs UI Kit 5.3.0 or later with Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support). + + Having issues? Check the [Troubleshooting Guide](/ui-kit/ios/troubleshooting) for common problems and solutions. diff --git a/ui-kit/ios/localize.mdx b/ui-kit/ios/localize.mdx index 9e6197848..c5687127c 100644 --- a/ui-kit/ios/localize.mdx +++ b/ui-kit/ios/localize.mdx @@ -115,6 +115,8 @@ All localization keys used by the SDK are available in our [GitHub repository](h - Provide custom translations for them in your app - Keep your localization files in sync with SDK updates +The texts that [offline support](/ui-kit/ios/offline-support) shows, such as "Connect to load chats", "Not sent yet" and "Available when online", are listed with their keys in [Offline states and texts](/ui-kit/ios/offline-support#offline-states-and-texts). Override them the same way. + By using the `CometChatLocalize` class, you can provide a user-friendly, localized experience to your users, enhancing the overall user experience within your application. --- diff --git a/ui-kit/ios/message-bubble-styling.mdx b/ui-kit/ios/message-bubble-styling.mdx index aee661bb9..6f2c393d5 100644 --- a/ui-kit/ios/message-bubble-styling.mdx +++ b/ui-kit/ios/message-bubble-styling.mdx @@ -28,6 +28,8 @@ There are two primary classes for styling message bubbles: Both classes provide properties for customizing background color, border, corner radius, and specific styles for individual message types. +With [offline support](/ui-kit/ios/offline-support#message-list-and-threads) on, an image, video, audio or file bubble with no copy on the device and no connection shows a placeholder with the file name, size and "Available when online". Style that text, and the "Not sent yet" and "Not sent. Tap to retry" lines under unsent messages, with [`CometChatMessageList.offlineStyle`](/ui-kit/ios/offline-support#offline-style). + --- ## Properties diff --git a/ui-kit/ios/message-composer.mdx b/ui-kit/ios/message-composer.mdx index ff2b2845a..e1336c87e 100644 --- a/ui-kit/ios/message-composer.mdx +++ b/ui-kit/ios/message-composer.mdx @@ -378,6 +378,10 @@ composer.enableMultipleAttachments = false This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/ui-kit/ios/message-list)). +### Sending while offline + +With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. With `enableMultipleAttachments = false`, a picked file is sent as a single media message and is queued too. An edit that fails keeps the edited text and the edit banner, calls `onError` and shows a notice. + --- ## Common Patterns diff --git a/ui-kit/ios/message-list.mdx b/ui-kit/ios/message-list.mdx index 45c34fb35..55a265f18 100644 --- a/ui-kit/ios/message-list.mdx +++ b/ui-kit/ios/message-list.mdx @@ -61,6 +61,7 @@ The `CometChatMessageList` component displays a scrollable list of messages in a "hideThreadSubscriptionOption": { "type": "Bool", "default": false }, "hideGroupActionMessages": { "type": "Bool", "default": false }, "hideNewMessageIndicator": { "type": "Bool", "default": false }, + "hideOfflineNotices": { "type": "Bool", "default": false, "note": "Offline support only (v5.3.0+)" }, "hideEmptyView": { "type": "Bool", "default": false }, "hideErrorView": { "type": "Bool", "default": false }, "hideLoadingView": { "type": "Bool", "default": false } @@ -262,6 +263,12 @@ Setting it to `false` renders every media message with the classic single-attach --- +## Offline Support + +With [offline support](/ui-kit/ios/offline-support#message-list-and-threads) on, the list (and a thread's replies) shows saved history at once, then updates it from the server. Own messages that aren't sent yet offer only **Retry** and **Delete**. At the end of the saved messages with no connection, the list shows **Connect to load more**. Use `hideOfflineNotices` to hide the offline notices, and the static `CometChatMessageList.offlineStyle` ([Offline style](/ui-kit/ios/offline-support#offline-style)) to style them. + +--- + ## Actions and Events ### Callback Props @@ -1734,6 +1741,17 @@ Hides the new message indicator. | Type | `Bool` | | Default | `false` | +### hideOfflineNotices + +*Available since v5.3.0* + +Hides the [offline support](/ui-kit/ios/offline-support#hide-offline-notices) notices (a removed unsent message, a full queue, unsent messages that couldn't be recovered), the "Connect to load more" rows and the "Jump to latest" pill. Has no effect while offline support is off. + +| | | +|---|---| +| Type | `Bool` | +| Default | `false` | + ### hidePinMessageOption *Available since v5.1.22* diff --git a/ui-kit/ios/methods.mdx b/ui-kit/ios/methods.mdx index cfc026465..d67ca0203 100644 --- a/ui-kit/ios/methods.mdx +++ b/ui-kit/ios/methods.mdx @@ -15,6 +15,7 @@ sidebar_label: "Methods" - **Logout:** `CometChatUIKit.logout(user:result:)` - **Create user:** `CometChatUIKit.createUser(user:onSuccess:onError:)` - **Send message:** `CometChatUIKit.sendTextMessage(message:onSuccess:onError:)`, `sendMediaMessage`, `sendCustomMessage` +- **Offline support:** `UIKitSettings().setOfflineConfig(_:)` before `build()`. Off by default. See [Offline Support](/ui-kit/ios/offline-support) - **Related:** [Getting Started](/ui-kit/ios/getting-started) · [Events](/ui-kit/ios/events) · [SDK Overview](/sdk/ios/overview) @@ -51,6 +52,7 @@ Replace **APP_ID**, **REGION**, and **AUTH_KEY** with your CometChat App ID, Reg | **setAutoEstablishSocketConnection** | `Boolean` | Configures if web socket connections will established automatically on app initialization or be done manually, set to true by default | | **setAIFeatures** | `List` | Sets the AI Features that need to be added in UI Kit | | **setExtensions** | `List` | Sets the list of extension that need to be added in UI Kit | +| **setOfflineConfig(_:)** | `OfflineConfig` | Turns on offline support by passing the Chat SDK's `OfflineConfig` to the SDK. Off unless the config has `enabled` set to `true`. Needs UI Kit 5.3.0 or later. See [Offline Support](/ui-kit/ios/offline-support) | #### Example @@ -76,6 +78,38 @@ CometChatUIKit.init(uiKitSettings: uikitSettings) { result in +#### Enable offline support + +Offline support is off by default. To turn it on, pass an `OfflineConfig` from the Chat SDK to `setOfflineConfig(_:)` before you call `build()` and `CometChatUIKit.init`. Saved chats then open without a connection, and messages sent offline are queued until the connection returns. + + + +```swift lines +import CometChatUIKitSwift +import CometChatSDK + +let uiKitSettings = UIKitSettings() + .set(appID: "your_appId") + .set(region: "your_region") + .set(authKey: "your_authKey") + .subscribePresenceForAllUsers() + .setOfflineConfig(OfflineConfig(enabled: true)) + .build() + +CometChatUIKit.init(uiKitSettings: uiKitSettings) { result in + switch result { + case .success: + print("Initialization success") + case .failure(let error): + print("CometChat exception: \(error)") + } +} +``` + + + +UI Kit 5.3.0 needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for the requirements, what each component does offline, and the other `OfflineConfig` options. + --- ### Login using Auth Key @@ -145,6 +179,10 @@ CometChatUIKit.logout(user: user) { (result) in + +With [offline support](/ui-kit/ios/offline-support) on, logout also ends the user's offline session. The Chat SDK deletes the user's offline cache, the UI Kit deletes the avatars it saved and clears the screens on display, and messages still waiting to be sent are discarded. A pending `sendFormMessage`, `sendCardMessage` or `sendSchedulerMessage` calls `onError` once with `ERROR_OFFLINE_MESSAGE_DISCARDED`. Logging in as a different user does the same for the previous user. + + --- ### Create User @@ -172,6 +210,10 @@ CometChatUIKit.create(user: user) { result in ### Base Message + +With [offline support](/ui-kit/ios/offline-support) on, the send methods below queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. + + #### Text Message To send a text message to a single user or a group, use the `sendTextMessage()` function. This function requires a `TextMessage` object containing the necessary information for delivering the message. diff --git a/ui-kit/ios/search.mdx b/ui-kit/ios/search.mdx index abad28b51..73e35ad8e 100644 --- a/ui-kit/ios/search.mdx +++ b/ui-kit/ios/search.mdx @@ -31,7 +31,8 @@ The `CometChatSearch` component is a powerful and customizable search interface "callbacks": { "onConversationClicked": "(Conversation, IndexPath) -> Void (assignable property)", "onMessageClicked": "(BaseMessage) -> Void (assignable property)", - "note": "No onBack / onError / onEmpty. Failures and empty results are VIEWS: set(errorView:), set(emptyView:), plus errorStateTitleText / errorStateSubTitleText." + "onError": "(CometChatException) -> Void (set(onError:); called only with offline support on)", + "note": "No onBack / onEmpty. Failures and empty results are VIEWS: set(errorView:), set(emptyView:), plus errorStateTitleText / errorStateSubTitleText. With offline support on, set(onError:) is also called once for a failed search." }, "visibility": { "hideUserStatus": { "type": "Bool", "default": false }, @@ -169,7 +170,7 @@ import CometChatUIKitSwift let search = CometChatSearch() -// CometChatSearch surfaces failures as an error STATE, not an onError callback. +// With offline support off, CometChatSearch surfaces failures as an error STATE, not an onError callback. // Supply your own view, or retitle the built-in one. search.set(errorView: myErrorView) @@ -179,6 +180,14 @@ search.errorStateSubTitleText = "Check your connection and try again" +With [offline support](/ui-kit/ios/offline-support#search) on, `set(onError:)` is also called, once per search that fails. A keyword search that can't connect and has no saved match shows **Connect to search** instead, without calling `onError`, and runs again once when the connection returns. + +```swift lines +search.set(onError: { error in + print("Search failed: \(error.errorDescription)") +}) +``` + --- #### 5. onEmpty diff --git a/ui-kit/ios/threaded-messages-header.mdx b/ui-kit/ios/threaded-messages-header.mdx index 7f3ab9520..592a88bea 100644 --- a/ui-kit/ios/threaded-messages-header.mdx +++ b/ui-kit/ios/threaded-messages-header.mdx @@ -194,6 +194,8 @@ Below is a list of customizations along with corresponding code snippets: | enableThreadSubscription | Shows the subscribe/unsubscribe bell on the reply-count bar. | `set(enableThreadSubscription: true)` | | hideThreadSubscriptionButton | Hides the bell while leaving the feature on, for a screen that draws its own control. | `set(hideThreadSubscriptionButton: true)` | +With [offline support](/ui-kit/ios/offline-support#message-list-and-threads) on, the reply count includes your own replies that haven't been sent yet, and takes back a reply that is discarded before it is sent. + ### Thread Subscription *Available since v5.1.22* From 525fef74441153276f01e98d205aff7139431909 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:53:34 +0530 Subject: [PATCH 4/6] docs(ENG-57593): stop promising queued media in the iOS offline docs Photos, videos, audio files and documents are to be sent while connected; the pages no longer say a picked file is queued. The methods note now covers sendTextMessage and sendCustomMessage only and links to the send-completions section for form, card and scheduler messages. The threaded-messages guide's offline row now matches the offline page: the composer stays enabled, text replies and voice notes queue, and edits, deletes and reactions need a connection. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/ios/compact-message-composer.mdx | 2 +- ui-kit/ios/core-features.mdx | 4 ++-- ui-kit/ios/getting-started.mdx | 2 +- ui-kit/ios/guide-threaded-messages.mdx | 2 +- ui-kit/ios/message-composer.mdx | 2 +- ui-kit/ios/methods.mdx | 4 ++-- ui-kit/ios/offline-support.mdx | 8 ++++---- 7 files changed, 12 insertions(+), 12 deletions(-) diff --git a/ui-kit/ios/compact-message-composer.mdx b/ui-kit/ios/compact-message-composer.mdx index d234602f2..55b748c0a 100644 --- a/ui-kit/ios/compact-message-composer.mdx +++ b/ui-kit/ios/compact-message-composer.mdx @@ -277,7 +277,7 @@ This is composer-side only: received multi-attachment messages still render with ### Sending while offline -With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. With `enableMultipleAttachments = false`, a picked file is sent as a single media message and is queued too. In edit mode, tapping Send leaves edit mode at once. If the edit then fails, the message keeps its old text, `onError` fires and a notice shows, and the next message you type is sent as a new message. +With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send photos, videos, audio files and documents while connected. In edit mode, tapping Send leaves edit mode at once. If the edit then fails, the message keeps its old text, `onError` fires and a notice shows, and the next message you type is sent as a new message. --- diff --git a/ui-kit/ios/core-features.mdx b/ui-kit/ios/core-features.mdx index fea661c45..08b795bb7 100644 --- a/ui-kit/ios/core-features.mdx +++ b/ui-kit/ios/core-features.mdx @@ -19,7 +19,7 @@ description: "Review CometChat iOS UI Kit core features for messaging, media sha {"name": "threadSubscription", "description": "Subscribe to or unsubscribe from a thread's replies", "component": "CometChatMessageList", "enabledByDefault": false}, {"name": "groupChat", "description": "Create and manage group conversations", "component": "CometChatGroups", "enabledByDefault": true}, {"name": "search", "description": "Search across conversations and messages", "component": "CometChatSearch", "enabledByDefault": true}, - {"name": "offlineSupport", "description": "Show saved chats without a connection and queue sends until reconnect; turn on with UIKitSettings.setOfflineConfig(_:)", "component": "CometChatMessageList", "enabledByDefault": false} + {"name": "offlineSupport", "description": "Show saved chats without a connection and queue text messages until reconnect; turn on with UIKitSettings.setOfflineConfig(_:)", "component": "CometChatMessageList", "enabledByDefault": false} ], "relatedComponents": ["CometChatMessageList", "CometChatConversations", "CometChatMessageList", "CometChatMessageComposer"] } @@ -832,7 +832,7 @@ class SearchViewController: UIViewController { *Available since v5.3.0* -Show chats the user has opened before without a connection, and queue messages sent offline until the connection returns. Files picked in the attachment tray still need a connection to upload. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. +Show chats the user has opened before without a connection, and queue text messages sent offline until the connection returns. Send photos, videos and files while connected: the attachment tray needs a connection to upload them. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. ```swift lines import CometChatUIKitSwift diff --git a/ui-kit/ios/getting-started.mdx b/ui-kit/ios/getting-started.mdx index de3fbefbf..639ea07b5 100644 --- a/ui-kit/ios/getting-started.mdx +++ b/ui-kit/ios/getting-started.mdx @@ -240,7 +240,7 @@ For production, use [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-aut -To let users open saved chats and queue messages without a connection, add `.setOfflineConfig(OfflineConfig(enabled: true))` to `UIKitSettings` before `.build()`. Offline support is off by default and needs UI Kit 5.3.0 or later with Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support). +To let users open saved chats and queue text messages without a connection, add `.setOfflineConfig(OfflineConfig(enabled: true))` to `UIKitSettings` before `.build()`. Offline support is off by default and needs UI Kit 5.3.0 or later with Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support). diff --git a/ui-kit/ios/guide-threaded-messages.mdx b/ui-kit/ios/guide-threaded-messages.mdx index 15198b5d0..1daf5fbb0 100644 --- a/ui-kit/ios/guide-threaded-messages.mdx +++ b/ui-kit/ios/guide-threaded-messages.mdx @@ -188,7 +188,7 @@ navigationItem.leftBarButtonItem = UIBarButtonItem( |----------|----------| | Parent message deleted | Display a fallback UI or disable the composer | | No replies | Show an empty state (e.g., "No replies yet") | -| Offline mode | Disable the composer and queue thread operations | +| Offline mode | With [offline support](/ui-kit/ios/offline-support) on, the composer stays enabled: text replies and voice notes are queued and sent when the connection returns. Editing, deleting and reacting need a connection. Send photos, videos and files while connected | ## Error Handling diff --git a/ui-kit/ios/message-composer.mdx b/ui-kit/ios/message-composer.mdx index e1336c87e..35c67eaba 100644 --- a/ui-kit/ios/message-composer.mdx +++ b/ui-kit/ios/message-composer.mdx @@ -380,7 +380,7 @@ This is composer-side only: received multi-attachment messages still render with ### Sending while offline -With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. With `enableMultipleAttachments = false`, a picked file is sent as a single media message and is queued too. An edit that fails keeps the edited text and the edit banner, calls `onError` and shows a notice. +With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send photos, videos, audio files and documents while connected. An edit that fails keeps the edited text and the edit banner, calls `onError` and shows a notice. --- diff --git a/ui-kit/ios/methods.mdx b/ui-kit/ios/methods.mdx index d67ca0203..254bbe3c0 100644 --- a/ui-kit/ios/methods.mdx +++ b/ui-kit/ios/methods.mdx @@ -80,7 +80,7 @@ CometChatUIKit.init(uiKitSettings: uikitSettings) { result in #### Enable offline support -Offline support is off by default. To turn it on, pass an `OfflineConfig` from the Chat SDK to `setOfflineConfig(_:)` before you call `build()` and `CometChatUIKit.init`. Saved chats then open without a connection, and messages sent offline are queued until the connection returns. +Offline support is off by default. To turn it on, pass an `OfflineConfig` from the Chat SDK to `setOfflineConfig(_:)` before you call `build()` and `CometChatUIKit.init`. Saved chats then open without a connection, and text messages sent offline are queued until the connection returns. @@ -211,7 +211,7 @@ CometChatUIKit.create(user: user) { result in ### Base Message -With [offline support](/ui-kit/ios/offline-support) on, the send methods below queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. +With [offline support](/ui-kit/ios/offline-support) on, `sendTextMessage` and `sendCustomMessage` queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. Send media messages while connected. For what form, card and scheduler messages report when a waiting send is discarded, see [Send completions](/ui-kit/ios/offline-support#send-completions). #### Text Message diff --git a/ui-kit/ios/offline-support.mdx b/ui-kit/ios/offline-support.mdx index ffd4d5c18..2f67d79e6 100644 --- a/ui-kit/ios/offline-support.mdx +++ b/ui-kit/ios/offline-support.mdx @@ -1,7 +1,7 @@ --- title: "Offline Support" sidebarTitle: "Offline Support" -description: "Turn on offline support in the CometChat iOS UI Kit so saved chats open without a connection, messages queue until reconnect, and every list shows clear offline states." +description: "Turn on offline support in the CometChat iOS UI Kit so saved chats open without a connection, text messages queue until reconnect, and every list shows clear offline states." --- @@ -20,7 +20,7 @@ description: "Turn on offline support in the CometChat iOS UI Kit so saved chats -With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Messages sent while offline wait in a queue and go out when the connection returns. Files picked in the attachment tray are the exception: they upload as soon as they're picked, so they need a connection. Every list shows a clear state when it has nothing saved and can't reach the server. +With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Text messages sent while offline wait in a queue and go out when the connection returns. Send photos, videos, audio files and documents while connected: the attachment tray uploads each file as soon as it's picked, which needs a connection. Every list shows a clear state when it has nothing saved and can't reach the server. The UI Kit builds on the Chat SDK's offline support. This page covers what the UI Kit adds on top. For cache settings, encryption, media caching and sync, see the [iOS SDK offline docs](/sdk/ios/offline-overview). @@ -29,7 +29,7 @@ The UI Kit builds on the Chat SDK's offline support. This page covers what the U **Works offline:** - Conversations, users, groups and group members you have loaded before show at once from the cache. - Saved message history, including threads, opens without a connection. -- New text messages, voice notes and messages sent with the `CometChatUIKit` send methods are queued and sent automatically on reconnect. A queued message shows a clock and **Not sent yet** until it is sent. +- New text messages and voice notes, and text and custom messages sent with the `CometChatUIKit` send methods, are queued and sent automatically on reconnect. A queued message shows a clock and **Not sent yet** until it is sent. - Images, video, audio and files that are on the device open from the saved copy. - Avatars the user has seen are kept on the device (up to 250 MB), so lists and headers show them offline. - After a reconnect, the SDK's catch-up brings in what changed while you were away, including a kick, ban or leave in a group. @@ -152,7 +152,7 @@ A **keyword** search with no saved match while offline shows **Connect to search ### Composer and unsent messages - A text message or voice note sent while offline appears at once with a clock and **Not sent yet** under the bubble (unless the bubble already has a bottom view). It goes out automatically on reconnect. -- Photos, videos, audio files and documents picked in the attachment tray are **not** queued. Each file starts uploading as soon as it's picked, and uploading needs a connection, so the message can't be sent until its files have uploaded. A tile whose upload failed shows a retry control: tap it to upload that file again once you're back online. With offline support on, the files staged in a chat's tray are kept on the device for that chat, so they come back when the chat is opened again. With `enableMultipleAttachments = false`, a picked file is sent as a single media message, and that message is queued like a text message. +- Photos, videos, audio files and documents picked in the attachment tray are **not** queued. Each file starts uploading as soon as it's picked, and uploading needs a connection, so the message can't be sent until its files have uploaded. A tile whose upload failed shows a retry control: tap it to upload that file again once you're back online. With offline support on, the files staged in a chat's tray are kept on the device for that chat, so they come back when the chat is opened again. Send photos, videos, audio files and documents while connected. - An unsent message (pending, sending or failed) offers only **Retry** and **Delete** in its long-press menu and its VoiceOver actions. It offers no Copy, Reply, React or Edit until it has been sent. - A failed message shows **Not sent. Tap to retry** under the bubble. Tapping that line or the status icon retries it, and VoiceOver reads the hint "Retry" on both. Every failed message can be retried, whatever the reason. Tapping the clock of a queued message retries it too; a message the SDK is sending at that moment keeps a plain clock. - **Retry** asks the SDK to retry the queued message, so it never creates a duplicate. A message the SDK never queued (for example, refused because the queue was full or the file was too large) is sent again as a new send. From 3c7a6be782c5909729f104fdd42d693bc81970bf Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:59:02 +0530 Subject: [PATCH 5/6] docs(ENG-57593): scope the Chat SDK minimum to UI Kit 5.3.0 and name every queuing send method The offline page, methods, core features and integration now say that UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later, so they no longer disagree with the 5.2.x numbers on the other pages. The integration quick reference marks its offline row as applying from 5.3.0. The offline page and methods now list sendFormMessage, sendCardMessage and sendSchedulerMessage beside sendTextMessage and sendCustomMessage as sends that queue offline. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/ios/core-features.mdx | 2 +- ui-kit/ios/getting-started.mdx | 4 ++-- ui-kit/ios/methods.mdx | 4 ++-- ui-kit/ios/offline-support.mdx | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/ui-kit/ios/core-features.mdx b/ui-kit/ios/core-features.mdx index 08b795bb7..7de7aaafb 100644 --- a/ui-kit/ios/core-features.mdx +++ b/ui-kit/ios/core-features.mdx @@ -850,7 +850,7 @@ CometChatUIKit.init(uiKitSettings: uikitSettings) { result in } ``` -Offline support needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for requirements, component behaviour, texts, styling and events. +UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for requirements, component behaviour, texts, styling and events. ## Moderation diff --git a/ui-kit/ios/getting-started.mdx b/ui-kit/ios/getting-started.mdx index 639ea07b5..6bc44a033 100644 --- a/ui-kit/ios/getting-started.mdx +++ b/ui-kit/ios/getting-started.mdx @@ -17,7 +17,7 @@ description: "Integrate CometChat iOS UI Kit with project setup, package install | Auth Key | Dev/testing only. Use Auth Token in production | | Calling | Optional. Add `CometChatCallsSDK` 5.0.4 (Up to Next Major Version) to enable | | Dependencies | `CometChatSDK` 4.1.10+ (resolved automatically by the UI Kit package) | -| Offline support | Optional, off by default. `UIKitSettings().setOfflineConfig(_:)` before `build()`. Needs UI Kit 5.3.0+ and `CometChatSDK` 4.2.1+. See [Offline Support](/ui-kit/ios/offline-support) | +| Offline support | Optional, off by default, from UI Kit 5.3.0. UI Kit 5.3.0 and later need `CometChatSDK` 4.2.1+ (the Dependencies row above is for the 5.2.x releases). `UIKitSettings().setOfflineConfig(_:)` before `build()`. See [Offline Support](/ui-kit/ios/offline-support) | | AI Skills | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) | @@ -240,7 +240,7 @@ For production, use [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-aut -To let users open saved chats and queue text messages without a connection, add `.setOfflineConfig(OfflineConfig(enabled: true))` to `UIKitSettings` before `.build()`. Offline support is off by default and needs UI Kit 5.3.0 or later with Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support). +To let users open saved chats and queue text messages without a connection, add `.setOfflineConfig(OfflineConfig(enabled: true))` to `UIKitSettings` before `.build()`. Offline support is off by default and is available from UI Kit 5.3.0. UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support). diff --git a/ui-kit/ios/methods.mdx b/ui-kit/ios/methods.mdx index 254bbe3c0..7a1b740d5 100644 --- a/ui-kit/ios/methods.mdx +++ b/ui-kit/ios/methods.mdx @@ -108,7 +108,7 @@ CometChatUIKit.init(uiKitSettings: uiKitSettings) { result in -UI Kit 5.3.0 needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for the requirements, what each component does offline, and the other `OfflineConfig` options. +UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for the requirements, what each component does offline, and the other `OfflineConfig` options. --- @@ -211,7 +211,7 @@ CometChatUIKit.create(user: user) { result in ### Base Message -With [offline support](/ui-kit/ios/offline-support) on, `sendTextMessage` and `sendCustomMessage` queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. Send media messages while connected. For what form, card and scheduler messages report when a waiting send is discarded, see [Send completions](/ui-kit/ios/offline-support#send-completions). +With [offline support](/ui-kit/ios/offline-support) on, `sendTextMessage`, `sendCustomMessage`, `sendFormMessage`, `sendCardMessage` and `sendSchedulerMessage` queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. Send media messages while connected. For what the form, card and scheduler completions report while a message is queued or discarded, see [Send completions](/ui-kit/ios/offline-support#send-completions). #### Text Message diff --git a/ui-kit/ios/offline-support.mdx b/ui-kit/ios/offline-support.mdx index 2f67d79e6..da04d2984 100644 --- a/ui-kit/ios/offline-support.mdx +++ b/ui-kit/ios/offline-support.mdx @@ -29,7 +29,7 @@ The UI Kit builds on the Chat SDK's offline support. This page covers what the U **Works offline:** - Conversations, users, groups and group members you have loaded before show at once from the cache. - Saved message history, including threads, opens without a connection. -- New text messages and voice notes, and text and custom messages sent with the `CometChatUIKit` send methods, are queued and sent automatically on reconnect. A queued message shows a clock and **Not sent yet** until it is sent. +- New text messages and voice notes are queued and sent automatically on reconnect. So are messages sent with `CometChatUIKit.sendTextMessage`, `sendCustomMessage`, `sendFormMessage`, `sendCardMessage` and `sendSchedulerMessage`. A queued message shows a clock and **Not sent yet** until it is sent. - Images, video, audio and files that are on the device open from the saved copy. - Avatars the user has seen are kept on the device (up to 250 MB), so lists and headers show them offline. - After a reconnect, the SDK's catch-up brings in what changed while you were away, including a kick, ban or leave in a group. @@ -51,7 +51,7 @@ The UI Kit builds on the Chat SDK's offline support. This page covers what the U | iOS | 15.1 or later | | Xcode | 16 or later | -The UI Kit links the Chat SDK directly, so the higher SDK minimum applies to every app on UI Kit 5.3.0, whether or not it turns offline on. The UI Kit calls `CometChat.initFromSettings(offlineConfig:onSuccess:onError:)`, which Chat SDK 4.2.0 doesn't have. UI Kit 5.3.0 therefore needs a later Chat SDK, even though the [SDK offline pages](/sdk/ios/offline-enable) list 4.2.0 for using the SDK on its own. +UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. The UI Kit links the Chat SDK directly, so this applies to every app on UI Kit 5.3.0 or later, whether or not it turns offline on: the UI Kit calls `CometChat.initFromSettings(offlineConfig:onSuccess:onError:)`, which Chat SDK 4.2.0 doesn't have. (Using the Chat SDK's offline support on its own, without the UI Kit, needs 4.2.0; see [Enable Offline Support](/sdk/ios/offline-enable).) Install or update the UI Kit with Swift Package Manager: From 140b048f0863c3ae3a6435cbdad24ae760212e48 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 20 Nov 2026 15:16:49 +0530 Subject: [PATCH 6/6] docs(ENG-57593): scope "media is not queued" to the attachment tray Checked against the iOS UI Kit at temp-release-offline-v5 d4d643870: - Only files picked in the attachment tray (enableMultipleAttachments, the default) need a connection. With enableMultipleAttachments = false a pick is sent through sendSingleMedia -> MessageComposerBuilder .mediaMessage -> OfflineSend.send and is queued like a voice note (MessageComposerBuilder.swift:50-53; same in the compact composer). - CometChatUIKit.sendMediaMessage also queues offline (CometChatUIKit .swift:579), so methods.mdx lists it and drops "send media while connected". - initFromSettings(offlineConfig:...) is used by the kit's own initFromSettings, not by every init: reworded. - "Saved rows show first" read as the Saved Messages component's rows: now "Rows cached on the device show first". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XbguTt1cqFxTDQyroF6wHx --- ui-kit/ios/compact-message-composer.mdx | 2 +- ui-kit/ios/core-features.mdx | 2 +- ui-kit/ios/guide-threaded-messages.mdx | 2 +- ui-kit/ios/message-composer.mdx | 2 +- ui-kit/ios/methods.mdx | 2 +- ui-kit/ios/offline-support.mdx | 8 ++++---- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/ui-kit/ios/compact-message-composer.mdx b/ui-kit/ios/compact-message-composer.mdx index 55b748c0a..e3fb69e0b 100644 --- a/ui-kit/ios/compact-message-composer.mdx +++ b/ui-kit/ios/compact-message-composer.mdx @@ -277,7 +277,7 @@ This is composer-side only: received multi-attachment messages still render with ### Sending while offline -With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send photos, videos, audio files and documents while connected. In edit mode, tapping Send leaves edit mode at once. If the edit then fails, the message keeps its old text, `onError` fires and a notice shows, and the next message you type is sent as a new message. +With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send files from the tray while connected. With `enableMultipleAttachments = false`, a picked photo, video, audio file or document is sent as a single media message instead, and is queued like a voice note. In edit mode, tapping Send leaves edit mode at once. If the edit then fails, the message keeps its old text, `onError` fires and a notice shows, and the next message you type is sent as a new message. --- diff --git a/ui-kit/ios/core-features.mdx b/ui-kit/ios/core-features.mdx index 7de7aaafb..4ce367bbb 100644 --- a/ui-kit/ios/core-features.mdx +++ b/ui-kit/ios/core-features.mdx @@ -832,7 +832,7 @@ class SearchViewController: UIViewController { *Available since v5.3.0* -Show chats the user has opened before without a connection, and queue text messages sent offline until the connection returns. Send photos, videos and files while connected: the attachment tray needs a connection to upload them. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. +Show chats the user has opened before without a connection, and queue text messages sent offline until the connection returns. Photos, videos and files picked in the attachment tray need a connection to upload. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default. ```swift lines import CometChatUIKitSwift diff --git a/ui-kit/ios/guide-threaded-messages.mdx b/ui-kit/ios/guide-threaded-messages.mdx index 1daf5fbb0..0aa476a45 100644 --- a/ui-kit/ios/guide-threaded-messages.mdx +++ b/ui-kit/ios/guide-threaded-messages.mdx @@ -188,7 +188,7 @@ navigationItem.leftBarButtonItem = UIBarButtonItem( |----------|----------| | Parent message deleted | Display a fallback UI or disable the composer | | No replies | Show an empty state (e.g., "No replies yet") | -| Offline mode | With [offline support](/ui-kit/ios/offline-support) on, the composer stays enabled: text replies and voice notes are queued and sent when the connection returns. Editing, deleting and reacting need a connection. Send photos, videos and files while connected | +| Offline mode | With [offline support](/ui-kit/ios/offline-support) on, the composer stays enabled: text replies and voice notes are queued and sent when the connection returns. Editing, deleting and reacting need a connection. Photos, videos and files picked in the attachment tray need a connection to upload | ## Error Handling diff --git a/ui-kit/ios/message-composer.mdx b/ui-kit/ios/message-composer.mdx index 35c67eaba..0dead27eb 100644 --- a/ui-kit/ios/message-composer.mdx +++ b/ui-kit/ios/message-composer.mdx @@ -380,7 +380,7 @@ This is composer-side only: received multi-attachment messages still render with ### Sending while offline -With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send photos, videos, audio files and documents while connected. An edit that fails keeps the edited text and the edit banner, calls `onError` and shows a notice. +With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send files from the tray while connected. With `enableMultipleAttachments = false`, a picked photo, video, audio file or document is sent as a single media message instead, and is queued like a voice note. An edit that fails keeps the edited text and the edit banner, calls `onError` and shows a notice. --- diff --git a/ui-kit/ios/methods.mdx b/ui-kit/ios/methods.mdx index 7a1b740d5..870829b3e 100644 --- a/ui-kit/ios/methods.mdx +++ b/ui-kit/ios/methods.mdx @@ -211,7 +211,7 @@ CometChatUIKit.create(user: user) { result in ### Base Message -With [offline support](/ui-kit/ios/offline-support) on, `sendTextMessage`, `sendCustomMessage`, `sendFormMessage`, `sendCardMessage` and `sendSchedulerMessage` queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. Send media messages while connected. For what the form, card and scheduler completions report while a message is queued or discarded, see [Send completions](/ui-kit/ios/offline-support#send-completions). +With [offline support](/ui-kit/ios/offline-support) on, `sendTextMessage`, `sendMediaMessage`, `sendCustomMessage`, `sendFormMessage`, `sendCardMessage` and `sendSchedulerMessage` queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. A media message's files are copied to the device when it is queued. For what the form, card and scheduler completions report while a message is queued or discarded, see [Send completions](/ui-kit/ios/offline-support#send-completions). #### Text Message diff --git a/ui-kit/ios/offline-support.mdx b/ui-kit/ios/offline-support.mdx index da04d2984..e32de5cbc 100644 --- a/ui-kit/ios/offline-support.mdx +++ b/ui-kit/ios/offline-support.mdx @@ -20,7 +20,7 @@ description: "Turn on offline support in the CometChat iOS UI Kit so saved chats -With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Text messages sent while offline wait in a queue and go out when the connection returns. Send photos, videos, audio files and documents while connected: the attachment tray uploads each file as soon as it's picked, which needs a connection. Every list shows a clear state when it has nothing saved and can't reach the server. +With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Text messages and voice notes sent while offline wait in a queue and go out when the connection returns. Photos, videos, audio files and documents picked in the attachment tray (the default) need a connection: the tray uploads each file as soon as it's picked. Every list shows a clear state when it has nothing saved and can't reach the server. The UI Kit builds on the Chat SDK's offline support. This page covers what the UI Kit adds on top. For cache settings, encryption, media caching and sync, see the [iOS SDK offline docs](/sdk/ios/offline-overview). @@ -51,7 +51,7 @@ The UI Kit builds on the Chat SDK's offline support. This page covers what the U | iOS | 15.1 or later | | Xcode | 16 or later | -UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. The UI Kit links the Chat SDK directly, so this applies to every app on UI Kit 5.3.0 or later, whether or not it turns offline on: the UI Kit calls `CometChat.initFromSettings(offlineConfig:onSuccess:onError:)`, which Chat SDK 4.2.0 doesn't have. (Using the Chat SDK's offline support on its own, without the UI Kit, needs 4.2.0; see [Enable Offline Support](/sdk/ios/offline-enable).) +UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. The UI Kit links the Chat SDK directly, so this applies to every app on UI Kit 5.3.0 or later, whether or not it turns offline on: the UI Kit is built against `CometChat.initFromSettings(offlineConfig:onSuccess:onError:)` (its own `initFromSettings` uses it), which Chat SDK 4.2.0 doesn't have. (Using the Chat SDK's offline support on its own, without the UI Kit, needs 4.2.0; see [Enable Offline Support](/sdk/ios/offline-enable).) Install or update the UI Kit with Swift Package Manager: @@ -152,7 +152,7 @@ A **keyword** search with no saved match while offline shows **Connect to search ### Composer and unsent messages - A text message or voice note sent while offline appears at once with a clock and **Not sent yet** under the bubble (unless the bubble already has a bottom view). It goes out automatically on reconnect. -- Photos, videos, audio files and documents picked in the attachment tray are **not** queued. Each file starts uploading as soon as it's picked, and uploading needs a connection, so the message can't be sent until its files have uploaded. A tile whose upload failed shows a retry control: tap it to upload that file again once you're back online. With offline support on, the files staged in a chat's tray are kept on the device for that chat, so they come back when the chat is opened again. Send photos, videos, audio files and documents while connected. +- Photos, videos, audio files and documents picked in the attachment tray are **not** queued. Each file starts uploading as soon as it's picked, and uploading needs a connection, so the message can't be sent until its files have uploaded. A tile whose upload failed shows a retry control: tap it to upload that file again once you're back online. With offline support on, the files staged in a chat's tray are kept on the device for that chat, so they come back when the chat is opened again. Send files from the tray while connected. With `enableMultipleAttachments = false`, a picked photo, video, audio file or document is sent as a single media message instead, and is queued like a voice note. - An unsent message (pending, sending or failed) offers only **Retry** and **Delete** in its long-press menu and its VoiceOver actions. It offers no Copy, Reply, React or Edit until it has been sent. - A failed message shows **Not sent. Tap to retry** under the bubble. Tapping that line or the status icon retries it, and VoiceOver reads the hint "Retry" on both. Every failed message can be retried, whatever the reason. Tapping the clock of a queued message retries it too; a message the SDK is sending at that moment keeps a plain clock. - **Retry** asks the SDK to retry the queued message, so it never creates a duplicate. A message the SDK never queued (for example, refused because the queue was full or the file was too large) is sent again as a new send. @@ -168,7 +168,7 @@ While the SDK isn't connected (including while it is still connecting), nobody s ### Pinned, Saved, Reactions and Notifications -`CometChatPinnedMessages`, `CometChatSavedMessages`, the reaction list and `CometChatNotificationFeed` follow the same rules as the other lists. Saved rows show first. With nothing saved and no connection, they show **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications**. The reaction list keeps its tabs visible and shows **Connect to load reactions** below them. +`CometChatPinnedMessages`, `CometChatSavedMessages`, the reaction list and `CometChatNotificationFeed` follow the same rules as the other lists. Rows cached on the device show first. With nothing saved and no connection, they show **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications**. The reaction list keeps its tabs visible and shows **Connect to load reactions** below them. ### Logout and user switch