用途
CometChat Android Chat SDK v5 是一个无界面(headless)的 Android 聊天 SDK,用于在开发者自有的 UI 与设计系统中构建聊天功能。它不依赖 UI Kit,适合需要自定义聊天界面、非聊天场景或后端式用法的项目。如果用户希望直接使用现成聊天 UI,资料建议改用 UI Kit(cometchat-android-v6-core)。
主要能力
SDK 提供以下能力(均为资料中列出的方法映射):
- 会话与认证:initFromSettings、init(旧版)、login、logout、getLoggedInUser、getUserAuthToken、登录监听器。
- 消息:TextMessage、MediaMessage、CustomMessage、InteractiveMessage,以及 sendMessage、sendMediaMessage、sendCustomMessage、sendInteractiveMessage、editMessage、deleteMessage、flagMessage/getFlagReasons、sendTransientMessage、getMessageDetails、附件与上传文件请求。
- 拉取(均通过请求构建器 + 分页):MessagesRequest、ConversationsRequest、UsersRequest、GroupsRequest、GroupMembersRequest、BannedGroupMembersRequest、BlockedUsersRequest、ReactionsRequest、NotificationFeedRequest。
- 实时监听器:消息、用户、群组、通话、连接、AI 助手、通知流。
- 回执与输入状态:startTyping/endTyping、markAsDelivered/markAsRead/markAsUnread/markConversationAsRead、MessageReceipt、未读数统计。
- 反应:addReaction/removeReaction、Reaction、ReactionCount。
- 用户与群组:getUser、createUser/updateUser、blockUsers/unblockUsers;createGroup、joinGroup/leaveGroup、成员管理、权限与群主转移等。
- 会话:getConversation、deleteConversation、tagConversation。
- 通话:initiateCall/acceptCall/rejectCall/endCall、getActiveCall/clearActiveCall。
- AI:getSmartReplies、getConversationStarter、getConversationSummary、askBot、isAIFeatureEnabled。
- 推送与通知流:registerTokenForPushNotification、CometChatNotifications、NotificationFeedItem。
- 连接:getConnectionStatus、connect/disconnect/ping。
使用方式
安装
在 settings.gradle(.kts) 的 dependencyResolutionManagement.repositories 中添加:
maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
在 app/build.gradle.kts 中添加:
implementation("com.cometchat:chat-sdk-android:5.0.5") // + calls-sdk-android:5.0.4 for calling
在 gradle.properties 中必须启用:
android.useAndroidX=true
android.enableJetifier=true
资料强调 Jetifier 不可省略:chat-sdk-android 5.0.5 仍会拉取 android.arch.lifecycle:extensions:1.1.1 → com.android.support:support-compat:26.1.0,缺少 android.enableJetifier=true 会导致 AndroidX 应用在 checkDebugDuplicateClasses 失败。通话功能(calls-sdk-android:5.0.4)额外需要 minSdk 26、SoLoader 初始化与 manifest 中的 service。
Manifest 需要 android.permission.INTERNET。凭据放在被 gitignore 的 app/src/main/assets/cometchat-settings.json(appId、region、credentials.authKey 仅开发用)。
初始化与登录顺序(不变量)
CometChat.initFromSettings(...) 成功 → login(...) 成功 → 其他一切。任何在 init 之前的 SDK 调用都会失败;在 init 之前 login 会静默失败。
import com.cometchat.chat.core.CometChat
import com.cometchat.chat.exceptions.CometChatException
import com.cometchat.chat.models.User
CometChat.initFromSettings(context, object : CometChat.CallbackListener<String>() {
override fun onSuccess(p: String) {
if (CometChat.getLoggedInUser() == null) {
CometChat.login(uid, authKey, object : CometChat.CallbackListener<User>() {
override fun onSuccess(user: User) { /* unlock the app */ }
override fun onError(e: CometChatException) { /* surface e.code + e.message */ }
})
} else { /* session already live */ }
}
override fun onError(e: CometChatException?) { /* surface — do NOT proceed */ }
})
资料特别指出两个 login 重载不可互换:开发用 login(uid, authKey, listener)(3 参数,uid 必需);生产用 login(authToken, listener)(2 参数,无 uid,token 携带身份)。把 token 传入 3 参数形式会被当作 apiKey 而认证失败。生产环境应在服务端为每个用户签发 auth token;Auth Key 仅限开发。切换用户需先 logout。
存在状态(presence)
实时存在状态需在 settings 资源中显式开启 chatSDK.presenceSubscription,否则 onUserListener 事件永不触发。可选值:ALL_USERS、FRIENDS、ROLES(需同级 roles 列表)、NONE。示例:
{ "appId": "…", "region": "…", "credentials": { "authKey": "…" },
"chatSDK": { "presenceSubscription": "ALL_USERS" } }
getUser(uid).status 或 UsersRequest 列表中的 status 字段是一次性快照,无需订阅即可工作;实时 onUserOnline/onUserOffline 才需要上述订阅。
监听器生命周期
每个 addListener(UNIQUE_ID, …) 都必须在销毁时配对 removeListener(UNIQUE_ID):Activity/Fragment 的 onDestroy、Compose 的 DisposableEffect onDispose、或 ViewModel 的 onCleared。使用稳定且唯一的 id;重复注册同一 id 会静默替换,不注销会泄漏回调并在旋转后重复处理。实时消息通过监听器到达,不要轮询。
DisposableEffect(Unit) {
CometChat.addMessageListener(LISTENER_ID, object : CometChat.MessageListener() {
override fun onTextMessageReceived(message: TextMessage) { /* append to state */ }
})
onDispose { CometChat.removeMessageListener(LISTENER_ID) }
}
适用场景
资料列出适用场景:直接使用 CometChat SDK、用自有 UI/设计系统构建聊天、不想用 UI Kit、以编程方式收发消息、在 Compose 中构建由 CometChat 支撑的自定义聊天界面。
限制与注意事项
- SDK 不提供 UI,需自行实现完整生产级界面(会话/用户/群组列表、搜索、分页、消息收发、编辑/删除/反应/举报、实时监听、详情页、乐观更新、加载/空/错误状态、尺寸与 IME 处理等)。
- 文档漂移:/sdk/android/v5/connection-status.md 中的 onError 无法编译,实际成员为 onConnectionError(e: CometChatException?),且 ConnectionListener 是接口,写法为 object : CometChat.ConnectionListener(无括号)。
- 常见陷阱:参数顺序颠倒(updateGroupMemberScope(UID, GUID, …) 与 transferGroupOwnership(GUID, UID, …));GroupsRequestBuilder.setSearchKeyWord 的 W 为大写,而 UsersRequestBuilder/ConversationsRequestBuilder 的 setSearchKeyword 为小写;会话搜索受套餐限制(需 "Conversation & Advanced Search" 功能,否则静默返回未过滤列表),用户/群组搜索不受限;CometChatConstants.RECEIVER_TYPE_USER 而非 CometChat.RECEIVER_TYPE_USER;Call 在 chat.core 而非 chat.models;init 前调用 SDK;init 前 login 静默失败;发布版携带 Auth Key;监听器不注销;轮询代替监听;无分页的无界拉取;空的 onError 块;主线程阻塞等待回调;未 logout 就重新登录;使用未版本化的 v4 文档。
- 验证方式:运行 ./gradlew :app:assembleDebug;设备上验证 init→login、列表加载与分页、发送即时显示并回执、他人消息实时到达、编辑/删除/反应就地更新、旋转不重复消息、强制错误(飞行模式)显示可读错误状态。资料说明该系列尚无自动化实时后端往返冒烟测试,需手动验证。
分类
该技能用于在 Android 上以自有 UI 构建聊天功能,属于编程与开发范畴。