用途
本技能用于在 Android 应用中从零(from scratch)集成 CometChat Calls SDK v5,实现语音与视频通话,采用无界面(headless)方式,不依赖 UI Kit。它面向选择“自建通话界面 / 独立通话”路径的开发者;如果希望使用预置通话 UI,则应改用 cometchat-android-v6-core 与 cometchat-android-v6-calls。
主要能力
- 会议式(session room):仅使用 Calls SDK,通过 generateToken(sessionId) 生成令牌,再调用 joinSession 加入会话;同一 sessionId 的参与者共享同一通话,无响铃流程。
- 1:1 响铃通话:由 Chat SDK(com.cometchat:chat-sdk-android:5.0.5)负责信令,Calls SDK 承载媒体;流程为 initiateCall → 对端 onIncomingCallReceived → acceptCall/rejectCall → 双方 joinSession(call.sessionId) → 挂断时 leaveSession 并 CometChat.endCall。
- 生命周期方法:initFromSettings、init、isInitialized、login(uid, authKey) / login(authToken)、logout、getLoggedInUser、getUserAuthToken。
- 会话相关:generateToken、joinSession(支持 token 或 sessionId 重载)、SessionSettingsBuilder(setSessionType、setLayout、setAudioMode 等)。
- 活动通话:CallSession.getInstance() 提供 isSessionActive、leaveSession、生命周期绑定的监听器(addSessionStatusListener 等)与 clearAllListeners。
- 其他:通话内自定义控件、通话记录(CallLogRequest)、转写与隐藏字幕(v5.0.4+,受套餐限制)、后台通话(CometChatOngoingCallService)、常量与枚举(SessionType/LayoutType/AudioMode 等)。
使用方式
依赖与仓库配置:
// settings.gradle(.kts) → dependencyResolutionManagement.repositories
maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
// app/build.gradle.kts
implementation("com.cometchat:calls-sdk-android:5.0.4")
implementation("com.cometchat:chat-sdk-android:5.0.5") // 1:1 响铃需要
implementation("com.facebook.react:react-android:0.77.2")
implementation("com.facebook.soloader:soloader:0.12.1")
gradle.properties 要求:
android.useAndroidX=true
android.enableJetifier=true
org.gradle.jvmargs=-Xmx4096m
AndroidManifest.xml 中必须声明服务:
<service android:name="com.cometchat.calls.services.CometChatOngoingCallService"
android:exported="false"
android:foregroundServiceType="camera|microphone|mediaPlayback" />
构建门槛:minSdk 26(calls-sdk-android:5.0.4 引入 react-native-svg 的 minSdkVersion 26);必须声明上述 service,否则 CometChatOngoingCallService.launch(activity) 会静默失败;1:1 响铃路径需要 Jetifier;Gradle 堆内存必须设为 -Xmx4096m,否则首次构建会 OOM。
SoLoader 初始化(5.0.x 必需):
import com.cometchat.calls.core.CometChatCalls
import com.facebook.react.soloader.OpenSourceMergedSoMapping
import com.facebook.soloader.SoLoader
SoLoader.init(this, OpenSourceMergedSoMapping) // Application.onCreate(),在 CometChatCalls.initFromSettings 之前
初始化与登录顺序:CometChatCalls.initFromSettings(context, listener) 成功后,再调用 login(开发环境用 uid + authKey,生产环境用 authToken),之后才能 generateToken / joinSession / 注册监听器。初始化与登录未完成前,任何通话都会失败并返回 ERROR_COMETCHAT_CALLS_SDK_INIT。凭据存放在 app/src/main/assets/cometchat-settings.json(appId、region、可选 callsSDK hosts),生产环境应在服务端签发 auth token,切勿在客户端分发 Auth Key。
运行时权限:API 23+ 需自行请求 CAMERA 与 RECORD_AUDIO(视频)或 RECORD_AUDIO(语音),被拒绝时应告知用户,不要静默以静音状态加入。
会话加入示例(会议式,Kotlin Activity):
val sessionSettings = CometChatCalls.SessionSettingsBuilder()
.setSessionType(SessionType.VIDEO)
.setLayout(LayoutType.TILE)
.setDisplayName("Me")
.setIdleTimeoutPeriod(120)
.build()
CometChatCalls.generateToken(sessionId, object : CometChatCalls.CallbackListener<GenerateToken>() {
override fun onSuccess(token: GenerateToken) {
CometChatCalls.joinSession(token, sessionSettings, callContainer, object : CometChatCalls.CallbackListener<CallSession>() {
override fun onSuccess(callSession: CallSession) {
callSession.addSessionStatusListener(this@MeetCallActivity, object : SessionStatusListener() {
override fun onSessionLeft() { finish() }
override fun onSessionTimedOut() { finish() }
override fun onConnectionClosed() { finish() }
})
}
override fun onError(e: CometChatException) { /* 显示 e.code + e.message,然后 finish() */ }
})
}
override fun onError(e: CometChatException) { /* ERROR_AUTH_TOKEN ⇒ 未登录 */ }
})
监听器生命周期:每个 CallSession 监听器都绑定 LifecycleOwner,随其移除;应在 joinSession 的 onSuccess 中以 Activity/Fragment 作为 owner 注册。仍需手动处理:销毁时调用 CallSession.getInstance().leaveSession();响铃场景调用 CometChat.removeCallListener(ID)。
适用场景
- 需要自建通话界面、不使用预置 UI Kit 的 Android 应用。
- 独立语音/视频通话功能。
- 按 session id 加入的会议式房间。
- 一对一响铃通话(前台应用内)。
限制
- 1:1 响铃仅限前台:自动 socket 模式下应用进入后台会断开 WebSocket,后台被叫收不到 onIncomingCallReceived,后台主叫收不到 onOutgoingCallAccepted,返回前台也不会重放。后台或被杀应用响铃需走 VoIP push 路径(/calls/android/voip-calling),本技能不承诺该能力。
- 文档与 AAR 存在差异,以 AAR 为准,例如 setType 应为 setSessionType、unMuteAudio 应为 unmuteAudio、unPinParticipant 应为 unpinParticipant、pinParticipant(uid) 应为 (uid, pid)、MediaEventsListener.onScreenShareStarted/Stopped 实际位于 ParticipantEventListener。
- joinSession 会渲染完整通话 UI(静音、摄像头、切换、音频模式、布局、参与者、举手、录制、邀请、计时、红色离开按钮),不要重复实现内置控件;如需替换控件,应先调用 hideControlPanel(true)。
- 转写与隐藏字幕为 v5.0.4+ 且受套餐限制。
- 具体收费、价格与平台支持范围暂未提供。