# 实现 1v1 私密房 (/zh-CN/solutions/one-to-one-live/rtm/build/implement-core-features/start-one-to-one) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" /> 在陌生人社交场景中,用户可以根据头像、个人简介等筛选到感兴趣的用户进行 1v1 私密视频通话;也可以通过地理位置、标签随机匹配的方式进行 1v1 私密视频通话。1v1 私密通话中,默认通话双方都开启摄像头和麦克风,双向发送接收音视频流。 本文介绍如何使用 [`CallAPI`](https://github.com/AgoraIO-Community/CallAPI) 实现 1v1 私密房场景。 ## 示例项目 [#示例项目] 声网在 agora-ent-scenarios 仓库中提供 1v1 私密房的源代码供你参考。 ## 技术架构 [#技术架构] 声网 `CallAPI` 中包含如下模块: - `CallRtmManager`,基于声网 RTM SDK 开发,将 RTM 相关操作进行了封装,是对 RTM 服务的管理类。 - `CallApi`:对 1v1 呼叫中 RTC 相关实现的封装,以及状态和业务的管理。 - `CallRtmSignalClient`:基于声网 RTM SDK 开发的信令协议实现类,负责连接 `CallRtmManager` 和 `CallApi`;`CallApi` 通过该对象进行消息的收发。 其中,`CallRtmManager` 和 `CallRtmSignalClient` 是对信令服务的封装。如果你希望基于三方信令 SDK 实现信令相关功能,可以参考[三方信令方案](/zh-CN/solutions/one-to-one-live/custom-signaling)。 ## 业务流程 [#业务流程] 1v1 私密房常见的业务流程如下图所示,你可以参考该流程实现相关业务。 :::warning[注意] 下图仅体现使用声网 `CallAPI` 的流程。你还需要根据场景需求,自行添加业务相关流程,如加入、离开可通话列表等。 ::: ![one-to-one call diagram](https://web-cdn.agora.io/docs-portal/img/one-to-one-live/call-diagram.png) ## 前提条件 [#前提条件] 开始前,请确保满足如下前提条件: - [Git](https://git-scm.com/downloads)。 - [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html)。 - [Android Studio](https://developer.android.com/studio/) 4.1 及以上。 - 参考[开通一对一直播服务](/zh-CN/solutions/one-to-one-live/rtm/build/setup-and-access/enable-service)在控制台创建项目,获取 App ID 和 App 证书,并[开通项目的 RTM 服务权限](/zh-CN/solutions/one-to-one-live/rtm/build/setup-and-access/enable-service#开通-rtm-服务权限)。 - 参考[集成 CallAPI](/zh-CN/solutions/one-to-one-live/rtm/get-started/integrate-callapi) 将 `CallAPI` 集成进项目中。 ## 实现 1v1 私密房 [#实现-1v1-私密房] 本节介绍如何基于 [`CallAPI`](https://github.com/AgoraIO-Community/CallAPI) 来快速实现一个 1v1 私密房场景。 完整的 API 调用时序如下图所示。其中: - **用户 A** 和**用户 B** 指代集成了声网 RTC SDK 和 `CallAPI` 的客户端 App。 - `RtcEngine` 指代声网 RTC SDK 的 API。 - `CallAPI` 指代声网 1v1 场景化 API,实现了包含信令登录与管理、RTC 互动、呼叫等功能。 - **业务服务器**指代**你**的 App 业务后台,需要自行部署实现。 :::info[信息] 出于篇幅考虑,下图省略了用户 B 在**初始化**和**离开并释放资源**中的 API 调用时序。这部分时序可以直接参考用户 A。 ::: ![1v1 私密房 API 调用时序图](https://web-cdn.agora.io/docs-portal/img/one-to-one-live/1v1-scene.svg) ### 1. 初始化 RTC 引擎 [#1-初始化-rtc-引擎] 调用 RTC SDK 的 [`create`](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_initialize) 方法初始化 `RtcEngine`。 ```kotlin val config = RtcEngineConfig() config.mContext = this config.mAppId = <#AppId#> config.mEventHandler = object : IRtcEngineEventHandler() { // override callback methods } config.mChannelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING config.mAudioScenario = Constants.AUDIO_SCENARIO_GAME_STREAMING try { val rtcEngine = RtcEngine.create(config) as RtcEngineEx } catch (e: Exception) { e.printStackTrace() Log.e(TAG, "RtcEngine.create() called error: $e") } ``` ### 2. 初始化 CallRtmManager [#2-初始化-callrtmmanager] RTM 服务的登录、注销、Token 续期、网络状态变化通知等是通过声网基于 RTM SDK 封装的 `CallRtmManager` 类实现的。参考如下示例代码初始化一个 RTM 实例。 ```kotlin val rtmManager = CallRtmManager(appId = <#AppId#>, userId = <#UserId#>, client = null) ``` ### 3. 添加并监听 CallRtmManager 状态回调 [#3-添加并监听-callrtmmanager-状态回调] 通过 `ICallRtmManagerListener` 监听 RTM 相关的状态和事件回调。 ```kotlin // 监听 rtm manager 事件 rtmManager?.addListener(object : ICallRtmManagerListener { override fun onConnected() { // 网络连接上,可以正常收发信令 } override fun onDisconnected() { // 网络未连接,此时无法收发信令,业务层可以根据当前状态处理异常 } override fun onTokenPrivilegeWillExpire(channelName: String) { // Token 过期,需要重新更新 RTM Token } }) ``` ### 4. 初始化 CallRtmSignalClient [#4-初始化-callrtmsignalclient] 初始化 CallAPI 中的 `CallRtmSignalClient` 对象,该对象负责实现消息发送和接收。 ```kotlin val signalClient = createRtmSignalClient(rtmManager.getRtmClient()) ``` ### 5. 初始化 CallAPI [#5-初始化-callapi] 调用 `CallAPI` 的 [`initialize`](/zh-CN/api-reference/private-room) 方法初始化 `CallAPI`。你需要在该方法中设置 `appId`、`userId`、`rtcEngine` 和 `signalClient` 参数。 ```kotlin // 初始化配置 val api = CallApiImpl(this) val config = CallConfig( appId = <#AppId#>, userId = <#UserId#>, rtcEngine = rtcEngine, signalClient = signalClient ) api.initialize(config) ``` ### 6. 添加并监听 CallAPI 的回调 [#6-添加并监听-callapi-的回调] 调用 [`addListener`](/zh-CN/api-reference/private-room) 方法注册 `CallAPI` 回调事件。然后实现 `CallAPI` 的回调 `ICallApiListener`,并监听 [`onCallStateChanged`](/zh-CN/api-reference/private-room) 回调。`CallAPI` 在运行过程中,会通过该回调报告当前的通话状态。你需要根据报告的状态实现不同的后续处理逻辑。 ```kotlin api.addListener(this) override fun onCallStateChanged( state: CallStateType, stateReason: CallReason, eventReason: String, eventInfo: Map) { // ... } ``` ### 7. 处理 CallRtmManager 的登录 [#7-处理-callrtmmanager-的登录] 调用 `CallAPI` 进行呼叫等操作时,需要保证信令可用。因此在准备通话环境前,需要调用 `CallRtmManager` 的 `login` 方法登录信令服务。 ```kotlin rtmManager?.login(rtmToken = rtmToken) { if (it == null) { // 登录成功,可以开始准备通话环境 } } ``` ### 8. 准备通话环境 [#8-准备通话环境] 调用 [`prepareForCall`](/zh-CN/api-reference/private-room) 准备通话环境。 :::warning[注意] - 请确保将该方法中的 `rtcToken` 设置为通配频道名的 Token,即在生成 Token 时将 `channelName` 设为通配符或空字符串。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 - 请确保用于生成 `rtcToken` 的 `uid` 和调用 [`initialize`](/zh-CN/api-reference/private-room) 方法初始化 CallAPI 中传入的 `userId` 一致。 ::: ```kotlin // 准备通话环境 val prepareConfig = PrepareConfig() prepareConfig.rtcToken = <#万能 RTC Token#> prepareConfig.roomId = <#需要呼叫的频道 ID#> prepareConfig.localView = <#本地视频 ViewGroup#> prepareConfig.remoteView = <#远端视频 ViewGroup#> // 如果希望把扩展信息带到对端,可以通过该参数实现 prepareConfig.userExtension = null api.prepareForCall(prepareConfig: prepareConfig) { err -> // 成功即可以开始进行呼叫 } ``` ### 9. 主叫发起呼叫 [#9-主叫发起呼叫] 通过 `CallAPI` 的 `call` 方法,呼叫用户列表里的任意一个用户。 :::warning[注意] 为了保证通话安全性,建议每次呼叫前调用 [`prepareForCall`](/zh-CN/api-reference/private-room) 更新 `roomId`。详见 [14. 更新频道号](/zh-CN/solutions/one-to-one-live/rtm/build/implement-core-features/start-one-to-one)。 ::: 发起视频呼叫 发起音频呼叫 如下示例代码调用 [`call [1/2]`](/zh-CN/api-reference/private-room/android/rtm/api/call-api#call) 来发起视频呼叫。 ```kotlin private fun call(user: Pure1v1UserInfo) { // 需要检查是否已经可以拨打电话,如果完成 CallAPI 状态会是 prepared if (mCallState == CallStateType.Idle || mCallState == CallStateType.Failed) { // 通话环境没有准备完成或者异常了,需要重新准备通话环境 ... // 异常提示 ... return } api.call(user.showUserId.toInt()) { error -> if (error != null) { // 呼叫失败,取消呼叫,返回空闲状态 api.cancelCall { err -> } } } } ``` 如下示例代码调用 [`call [2/2]`](/zh-CN/api-reference/private-room/android/rtm/api/call-api#call2),将 `callType` 设置为 `audio`,可发起音频呼叫。 ```kotlin private fun call(user: Pure1v1UserInfo) { // 需要检查是否已经可以拨打电话,如果完成 CallAPI 状态会是 prepared if (mCallState == CallStateType.Idle || mCallState == CallStateType.Failed) { // 通话环境没有准备完成或者异常了,需要重新准备通话环境 ... // 异常提示 ... return } api.call(user.showUserId.toInt(), CallType.Audio, mapOf()) { error -> if (error != null) { // 呼叫失败,取消呼叫,返回空闲状态 api.cancelCall { err -> } } } } ``` :::warning[注意] 呼叫返回失败时,可以判断当前状态,如果仍然处于呼叫中(`mCallState == CallStateType.Calling`),此时发起取消呼叫 [`cancelCall`](/zh-CN/api-reference/private-room) 可避免呼叫等待过长。 ::: ### 10. 监听到呼叫事件并处理 [#10-监听到呼叫事件并处理] 主叫发起呼叫,主叫和被叫都需要监听呼叫状态,并根据当前的状态实现后续逻辑。具体实现步骤如下: 1. 通过 `CallAPI` 的回调 [`onCallStateChanged`](/zh-CN/api-reference/private-room/android#oncallstatechanged) 接收当前的呼叫状态。 2. 根据发起呼叫的用户 ID,判断当前用户是主叫还是被叫,然后引导用户选择接受、拒绝或取消呼叫操作。 :::warning[注意] 在收到 `Calling` 状态时,需要保证校验摄像头和麦克风权限成功才能调用 `accept`/`reject`,否则会出现呼叫异常。 ::: ```kotlin override fun onCallStateChanged( state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: Map ) { when (state) { CallStateType.Calling -> { val fromUserId = eventInfo[kFromUserId] as? Int ?: 0 val fromRoomId = eventInfo[kFromRoomId] as? String ?: "" val toUserId = eventInfo[kRemoteUserId] as? Int ?: 0 if (currentUid == toUserId.toString()) { // 当前用户为被叫 ... // 获取用户信息,供弹出框展示 val user = userList.firstOrNull { it.userId == fromUserId.toString() } val dialog = Pure1v1CalleeDialog.show(user) // 接受呼叫 dialog?.acceptClosure = { api.accept(fromUserId) { err -> if (err != null) { // 如果接受消息出错,则发起拒绝,回到初始状态 api.reject(fromUserId, err.msg) {} } } } // 拒绝呼叫 dialog?.rejectClosure = { api.reject(fromUserId, "reject by user") { err -> } } } else if (currentUid == fromUserId.toString()) { // 当前用户为主叫 ... // 获取用户信息,供弹出框展示 val user = userList.firstOrNull { it.userId == toUserId.toString() } val dialog = Pure1v1CallerDialog.show(user) // 取消呼叫 dialog?.cancelClosure = { api.cancelCall { err -> } } } } else -> { } } } ``` ### 11. 收到通话成功 [#11-收到通话成功] 被叫点击接受后,主叫和被叫都会收到状态变更回调,且状态为通话成功。你可以在该回调中展示通话页面。 ```kotlin override fun onCallStateChanged( state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: Map ) { when (state) { CallStateType.Connected -> { // 显示通话页面 ... } else -> { } } } ``` :::warning[注意] 接受返回失败时,可以发起拒绝请求,避免对端没收到接受请求导致的异常。 ::: ### 12. 主叫结束呼叫 [#12-主叫结束呼叫] 主叫通过调用 `CallAPI` 的 [`hangup`](/zh-CN/api-reference/private-room) 方法来结束和对端的通话。 ```kotlin private fun hangupAction() { val connectedUserId = connectedUserId ?: return api.hangup(connectedUserId, "hangup by user") {} } ``` ### 13. 收到挂断消息 [#13-收到挂断消息] 主叫结束呼叫后,`CallAPI` 会通过回调将当前的呼叫状态同步给主叫和被叫端。相应的步骤和实现逻辑如下: 1. 点击挂断后,主叫和被叫都会通过 `ICallApiListener` 的 `onCallStateChanged` 回调监听到状态变化。 2. 呼叫状态会变更为空闲 `(state: prepared)`,变更原因为本地挂断 `(stateReason: localHangup)` 或远端挂断 `(stateReason: remoteHangup)`。 3. 你可以根据接收到的状态移除对应的通话页面。 ```kotlin override fun onCallStateChanged( state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: Map ) { when (state) { CallStateType.Prepared -> { when (stateReason) { CallStateReason.LocalHangup, CallStateReason.RemoteHangup -> { // 移除通话页面 ... // 展示挂断信息 ... } else -> { } } } else -> { } } } ``` 如果由于网络等问题,通话一方(用户 A)发起挂断的信令消息未能成功发送到另一方(用户 B),会导致用户 B 的通话页面无法结束。为避免该问题,我们建议你采用客户端 + 服务端配合的方式,关注并处理通话异常情况。具体操作步骤如下: 1. **客户端**:如果用户 B 收到 `onCallEventChanged` 回调,且 `event` 为 `remoteLeave`,表示用户 A 已离开通话频道。此时你可以调整用户界面,例如使用缺省的图像填充用户 A 的视图,并给出用户 A 暂时离开的提示。 2. **服务端**:通过 RTC 频道事件回调 [`103`](/zh-CN/api-reference/rtc/restful/webhook/events#103-broadcaster-join-channel) 和 [`104`](/zh-CN/api-reference/rtc/restful/webhook/events#104-broadcaster-leave-channel) 识别待观察用户。 - 收到用户 A 离开频道事件 `104` 后,记录事件中的 `uid`、`channelName` 及离开的时间戳 `ts` 到缓存中,并将该用户列为待观察用户。设置用户的超时离开时间,如 30 秒,然后每 5 秒或 10 秒检索待观察用户列表。如果用户 A 离开的时间超过 30 秒,则调用[封禁用户权限 RESTful API](/zh-CN/api-reference/api-ref/rtc/create-ban-rule) 将用户 A 从频道中踢出。 - 收到用户 A 加入频道事件 `103` 后,识别事件中的 `channelName` 和 `uid`。如果缓存中该 `uid` 在当前频道中有记录,且未申请下麦,则将该 `uid` 从待观察用户列表中移除。 3. **客户端**:如果用户 B 收到 `onCallError` 回调,且 `errorEvent` 为 `rtcOccurError`,`errorType` 为 `rtc`,`errorCode` 为 `123`,表示用户 A 被踢出 RTC 频道。此时用户 B 可以调用 `CallAPI` 的 `hangup` 方法结束当前通话并离开通话页面。 ### 14. 更新频道号 [#14-更新频道号] 调用 [`prepareForCall`](/zh-CN/api-reference/private-room) 更新频道号。 主叫发起呼叫后,被叫会获取到主叫在准备通话环境中设置的 `roomId`,从而加入对应的 RTC 频道进行通话。通话结束后,如果主叫不更新 `roomId` 就发起新的呼叫,可能会有一定的安全风险。 以用户 A、B、C 为例,主叫 A 向用户 B 发起呼叫后,B 就获取了 A 的 RTC 频道名(`roomId`)。呼叫结束后,如果 A 不更新 `roomId` 就向用户 C 发起呼叫,用户 B 可以通过技术手段使用之前的 `roomId` 和通配 Token 加入用户 A 的频道进行盗流。 因此为确保通话安全,你需要在每次发起呼叫前,都调用 `prepareForCall` 方法更新 `roomId`,以保证每次通话使用不同的 RTC 频道,进而确保通话的私密性。 :::warning[注意] 由于 `PrepareConfig` 为全量更新,因此调用 `prepareForCall` 更新频道号时,请确保 `PrepareConfig` 中的其他属性均已设值,否则会调用失败。你可以将之前的 `PrepareConfig` 中的设置保存起来,修改 `roomId` 后进行传参。 ::: ```kotlin // 准备通话环境 val prepareConfig = PrepareConfig() // highlight-start // 设置新的频道号 prepareConfig.roomId = <#需要呼叫的频道 ID#> // 此处省略其他属性的设置。请确保同步设置其他属性 // highlight-end api.prepareForCall(prepareConfig: prepareConfig) { err -> // 成功即可以开始进行呼叫 } ``` ### 15. 离开并释放资源 [#15-离开并释放资源] 如果要离开业务场景,还需要清理通话环境,释放相关资源。 ```kotlin // 清除 CallAPI 缓存 callApi.deinitialize { // 销毁 RTC 实例 RtcEngineEx.destroy() // 登出 RTM 服务 rtmManager.logout() // 其他业务逻辑 } ``` ## 开发注意事项 [#开发注意事项] 为确保通话安全,你需要在每次发起呼叫前,都调用 `prepareForCall` 方法更新 `roomId`,以保证每次通话使用不同的 RTC 频道,进而确保通话的私密性。详见 [14. 更新频道号](/zh-CN/solutions/one-to-one-live/rtm/build/implement-core-features/start-one-to-one)。 ## 参考文档 [#参考文档] 在开发过程中,你可以参考如下文档,获取更多 API 调用详情: - [CallAPI 参考](/zh-CN/api-reference/private-room) - [RTC API 参考](/zh-CN/api-reference/rtc/android/rtc-api-overview) 如果希望在项目中实现更高阶的功能,可以参考[优化 RTM 信令方案集成逻辑](/zh-CN/solutions/one-to-one-live/rtm/build/customize-and-extend/integration-guideline)。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" /> 在陌生人社交场景中,用户可以根据头像、个人简介等筛选到感兴趣的用户进行 1v1 私密视频通话;也可以通过地理位置、标签随机匹配的方式进行 1v1 私密视频通话。1v1 私密通话中,默认通话双方都开启摄像头和麦克风,双向发送接收音视频流。 本文介绍如何使用 [`CallAPI`](https://github.com/AgoraIO-Community/CallAPI) 实现 1v1 私密房场景。 ## 示例项目 [#示例项目-1] 声网在 `agora-ent-scenarios` 仓库中提供秀场转 1v1 的源代码供参考。 ## 技术架构 [#技术架构-1] 声网 `CallAPI` 中包含如下模块: - `CallRtmManager`,基于声网 RTM SDK 开发,将 RTM 相关操作进行了封装,是对 RTM 服务的管理类。 - `CallApi`:对 1v1 呼叫中 RTC 相关实现的封装,以及状态和业务的管理。 - `CallRtmSignalClient`:基于声网 RTM SDK 开发的信令协议实现类,负责连接 `CallRtmManager` 和 `CallApi`;`CallApi` 通过该对象进行消息的收发。 其中,`CallRtmManager` 和 `CallRtmSignalClient` 是对信令服务的封装。如果你希望基于三方信令 SDK 实现信令相关功能,可以参考[三方信令方案](/zh-CN/solutions/one-to-one-live/custom-signaling)。 ## 业务流程 [#业务流程-1] 1v1 私密房常见的业务流程如下图所示,你可以参考该流程实现相关业务。 :::warning[注意] 下图仅体现使用声网 `CallAPI` 的流程。你还需要根据场景需求,自行添加业务相关流程,如加入、离开可通话列表等。 ::: ![one-to-one call diagram](https://web-cdn.agora.io/docs-portal/img/one-to-one-live/call-diagram.png) ## 前提条件 [#前提条件-1] 开始前,请确保满足如下前提条件: - [Git](https://git-scm.com/downloads)。 - [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started)。 - [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 12.0 及以上。 - 有效的苹果开发者账号。 - 参考[开通一对一直播服务](/zh-CN/solutions/one-to-one-live/rtm/build/setup-and-access/enable-service)在控制台创建项目,获取 App ID 和 App 证书,并[开通项目的 RTM 服务权限](/zh-CN/solutions/one-to-one-live/rtm/build/setup-and-access/enable-service#开通-rtm-服务权限)。 - 参考[集成 CallAPI](/zh-CN/solutions/one-to-one-live/rtm/get-started/integrate-callapi) 将 `CallAPI` 集成进项目中。 ## 实现 1v1 私密房 [#实现-1v1-私密房-1] 本节介绍如何基于 [`CallAPI`](https://github.com/AgoraIO-Community/CallAPI) 来快速实现一个 1v1 私密房场景。 完整的 API 调用时序如下图所示。其中: - **用户 A** 和**用户 B** 指代集成了声网 RTC SDK 和 `CallAPI` 的客户端 App。 - `RtcEngine` 指代声网 RTC SDK 的 API。 - `CallAPI` 指代声网 1v1 场景化 API,实现了包含信令登录与管理、RTC 互动、呼叫等功能。 - **业务服务器**指代**你**的 App 业务后台,需要自行部署实现。 :::warning[注意] 出于篇幅考虑,下图省略了用户 B 在**初始化**和**离开并释放资源**中的 API 调用时序。这部分时序可以直接参考用户 A。 ::: ![1v1 私密房 API 调用时序图](https://web-cdn.agora.io/docs-portal/img/one-to-one-live/1v1-scene.svg) ### 1. 初始化 RTC 引擎 [#1-初始化-rtc-引擎-1] 调用 RTC SDK 的 [`sharedEngineWithConfig`](/zh-CN/api-reference/rtc/ios/initialize#api_irtcengine_initialize) 方法初始化 `RtcEngine`。 ```swift let config = AgoraRtcEngineConfig() config.appId = <#AppId#> config.channelProfile = .liveBroadcasting config.audioScenario = .gameStreaming config.areaCode = .global let rtcEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: nil) ``` ### 2. 初始化 CallRtmManager [#2-初始化-callrtmmanager-1] RTM 服务的登录、注销、Token 续期、网络状态变化通知等是通过声网基于 RTM SDK 封装的 `CallRtmManager` 类实现的。参考如下示例代码初始化一个 RTM 实例。 ```swift let rtmManager = CallRtmManager(appId: <#AppId#>, userId: <#UserId#>, rtmClient: nil) ``` ### 3. 添加并监听 CallRtmManager 状态回调 [#3-添加并监听-callrtmmanager-状态回调-1] 通过 `ICallRtmManagerListener` 监听 RTM 相关的状态和事件回调。 ```swift rtmManager.delegate = self extension Pure1v1UserListViewController: ICallRtmManagerListener { func onConnected() { // 网络连接上,可以正常收发信令 } func onDisconnected() { // 网络未连接,此时无法收发信令,业务层可以根据当前状态处理异常 } func onTokenPrivilegeWillExpire(channelName: String) { // Token 过期,需要重新更新 RTM Token } } ``` ### 4. 初始化 CallRtmSignalClient [#4-初始化-callrtmsignalclient-1] 初始化 CallAPI 中的 `CallRtmSignalClient` 对象,该对象负责实现消息发送和接收。 ```swift let signalClient = CallRtmSignalClient(rtmClient: rtmManager.getRtmClient()) ``` ### 5. 初始化 CallAPI [#5-初始化-callapi-1] 调用 `CallAPI` 的 [`initialize`](/zh-CN/api-reference/private-room) 方法初始化 `CallAPI`。你需要在该方法中设置 `appId`、`userId`、`rtcEngine` 和 `signalClient` 参数。 ```swift // 初始化配置 let config = CallConfig() config.appId = <#AppId#> config.userId = <#UserId#> config.rtcEngine = rtcEngine config.signalClient = signalClient callApi.initialize(config: config) ``` ### 6. 添加并监听 CallAPI 的回调 [#6-添加并监听-callapi-的回调-1] 调用 [`addListener`](/zh-CN/api-reference/private-room) 方法注册 `CallAPI` 回调事件。然后实现 `CallAPI` 的回调 `CallApiListenerProtocol`,并监听 [`onCallStateChanged`](/zh-CN/api-reference/private-room) 回调。`CallAPI` 在运行过程中,会通过该回调报告当前的通话状态。你需要跟踪报告的状态实现不同的后续处理逻辑。 ```swift callApi.addListener(listener: self) extension Pure1v1UserListViewController: CallApiListenerProtocol { func onCallStateChanged(with state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: [String : Any]) { // 省略其他逻辑 } } ``` ### 7. 处理 CallRtmManager 的登录 [#7-处理-callrtmmanager-的登录-1] 调用 `CallAPI` 进行呼叫等操作时,需要保证信令可用。因此在准备通话环境前,需要调用 `CallRtmManager` 的 `login` 方法登录信令服务。 ```swift rtmManager?.login(rtmToken: rtmToken, completion: { err in if let _ = err { return } // 登录成功,可以开始准备通话环境 }) ``` ### 8. 准备通话环境 [#8-准备通话环境-1] 调用 [`prepareForCall`](/zh-CN/api-reference/private-room) 准备通话环境。 :::warning[注意] - 请确保将该方法中的 `rtcToken` 设置为通配频道名的 Token,即在生成 Token 时将 `channelName` 设为通配符或空字符串。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 - 请确保用于生成 `rtcToken` 的 `uid` 和调用 [`initialize`](/zh-CN/api-reference/private-room) 方法初始化 CallAPI 中传入的 `userId` 一致。 ::: ```swift // 准备通话环境 let prepareConfig = PrepareConfig() prepareConfig.rtcToken = <#万能 RTC Token#> prepareConfig.roomId = <#需要呼叫的频道 ID#> prepareConfig.localView = callVC.localCanvasView.canvasView prepareConfig.remoteView = callVC.remoteCanvasView.canvasView // 如果期望把扩展信息带到对端,可以通过该参数实现 prepareConfig.userExtension = nil callApi.prepareForCall(prepareConfig: prepareConfig) { err in // 成功即可以开始进行呼叫 } ``` ### 9. 主叫发起呼叫 [#9-主叫发起呼叫-1] 通过 `CallAPI` 的 `call` 方法,呼叫用户列表里的任意一个用户。 :::warning[注意] 为了保证通话安全性,建议每次呼叫前调用 [`prepareForCall`](/zh-CN/api-reference/private-room) 更新 `roomId`。详见 [14. 更新频道号](/zh-CN/solutions/one-to-one-live/rtm/build/implement-core-features/start-one-to-one)。 ::: 发起视频呼叫 发起音频呼叫 如下示例代码调用 [`call [1/2]`](/zh-CN/api-reference/private-room/ios/rtm/api/call-api#call) 来发起视频呼叫。 ```swift private func _call(user: Pure1v1UserInfo) { // 需要检查是否已经可以拨打电话,如果完成 CallAPI 状态会是 prepared if callState == .idle || callState == .failed { // 通话环境没有准备完成或者异常了,需要重新准备通话环境 // 异常提示 return } let remoteUserId = UInt(user.userId)! callApi.call(remoteUserId: remoteUserId) {[weak self] err in guard let err = err, self?.callState == .calling else {return} // 呼叫失败,取消呼叫,返回空闲状态 self?.callApi.cancelCall(completion: { err in }) } } ``` 如下示例代码调用 [`call [2/2]`](/zh-CN/api-reference/private-room/ios/rtm/api/call-api#call2),将 `callType` 设置为 `audio`,可发起音频呼叫。 ```swift private func _call(user: Pure1v1UserInfo) { // 需要检查是否已经可以拨打电话,如果完成 CallAPI 状态会是 prepared if callState == .idle || callState == .failed { // 通话环境没有准备完成或者异常了,需要重新准备通话环境 // 异常提示 return } let remoteUserId = UInt(user.userId)! callApi.call(remoteUserId: remoteUserId, callType: .audio, callExtension: [:]) {[weak self] err in guard let err = err, self?.callState == .calling else {return} // 呼叫失败,取消呼叫,返回空闲状态 self?.callApi.cancelCall(completion: { err in }) } } ``` :::warning[注意] 呼叫返回失败时,可以判断当前状态,如果仍然处于呼叫中(`callState == .calling`),此时发起取消呼叫 [`cancelCall`](/zh-CN/api-reference/private-room) 可避免呼叫等待过长。 ::: ### 10. 监听到呼叫事件并处理 [#10-监听到呼叫事件并处理-1] 主叫发起呼叫,主叫和被叫都需要监听呼叫状态,并根据当前的状态实现后续逻辑。具体实现步骤如下: 1. 通过 `CallAPI` 的回调 `onCallStateChanged` 接收当前的呼叫状态。 2. 根据发起呼叫的用户 ID,判断当前用户是主叫还是被叫,然后引导用户选择接受、拒绝或取消呼叫操作。 ```swift func onCallStateChanged(with state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: [String : Any]) { switch state { case .calling: let fromUserId = eventInfo[kFromUserId] as? UInt ?? 0 let fromRoomId = eventInfo[kFromRoomId] as? String ?? "" let toUserId = eventInfo[kRemoteUserId] as? UInt ?? 0 if currentUid == "\(toUserId)" { // 当前用户为被叫 // 获取用户信息,供弹出框展示 let user = userList.first {$0.userId == "\(fromUserId)"} let dialog = Pure1v1CalleeDialog.show(user: user) // 接受呼叫 dialog?.acceptClosure = { [weak self] in guard let self = self else {return} self.callApi.accept(remoteUserId: fromUserId) {[weak self] err in guard let err = err else { return } // 如果接受消息出错,则发起拒绝,回到初始状态 self?.api.reject(remoteUserId: fromUserId, reason: err.localizedDescription, completion: { err in }) } } // 拒绝呼叫 dialog?.rejectClosure = { [weak self] in self?.callApi.reject(remoteUserId: fromUserId, reason: "reject by user") {err in } } } else if currentUid == "\(fromUserId)" { // 当前用户为主叫 // 获取用户信息,供弹出框展示 let user = userList.first {$0.userId == "\(toUserId)"} let dialog = Pure1v1CallerDialog.show(user: user) // 取消呼叫 dialog?.cancelClosure = {[weak self] in self?.callApi.cancelCall(completion: { err in }) } } default: break } } ``` :::warning[注意] 接受返回失败时,可以发起拒绝请求,避免对端没收到接受请求导致的异常。 ::: ### 11. 收到通话成功 [#11-收到通话成功-1] 被叫点击接受后,主叫和被叫都会收到状态变更回调,且状态为通话成功。你可以在该回调中展示通话页面。 ```swift func onCallStateChanged(with state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: [String : Any]) { switch state { case .connected: // 显示通话页面 present(callVC, animated: false) break default: break } } ``` ### 12. 主叫结束呼叫 [#12-主叫结束呼叫-1] 主叫通过调用 `CallAPI` 的 [`hangup`](/zh-CN/api-reference/private-room) 方法来结束和对端的通话。 ```swift func _hangupAction() { callApi?.hangup(remoteUserId: UInt(targetUser?.userId ?? "") ?? 0, reason: nil, completion: { err in }) ... } ``` ### 13. 收到挂断消息 [#13-收到挂断消息-1] 主叫结束呼叫后,`CallAPI` 会通过回调将当前的呼叫状态同步给主叫和被叫端。相应的步骤和实现逻辑如下: 1. 点击挂断后,主叫和被叫都会通过 `CallApiListenerProtocol` 的 `onCallStateChanged` 回调监听到状态变化。 2. 呼叫状态会变更为空闲 `(state: prepared)`,变更原因为本地挂断 `(stateReason: localHangup)` 或远端挂断 `(stateReason: remoteHangup)`。 3. 你可以根据接收到的状态移除对应的通话页面。 ```swift func onCallStateChanged(with state: CallStateType, stateReason: CallStateReason, eventReason: String, eventInfo: [String : Any]) { let currentUid = userInfo?.userId ?? "" switch state { case .prepared: switch stateReason { case .localHangup, .remoteHangup: // 移除通话页面 callVC.dismiss(animated: false) // 展示拒绝信息 default: break } default: break } } ``` 如果由于网络等问题,通话一方(用户 A)发起挂断的信令消息未能成功发送到另一方(用户 B),会导致用户 B 的通话页面无法结束。为避免该问题,我们建议你采用客户端 + 服务端配合的方式,关注并处理通话异常情况。具体操作步骤如下: 1. **客户端**:如果用户 B 收到 `onCallEventChanged` 回调,且 `event` 为 `remoteLeave`,表示用户 A 已离开通话频道。此时你可以调整用户界面,例如使用缺省的图像填充用户 A 的视图,并给出用户 A 暂时离开的提示。 2. **服务端**:通过 RTC 频道事件回调 [`103`](/zh-CN/api-reference/rtc/restful/webhook/events#103-broadcaster-join-channel) 和 [`104`](/zh-CN/api-reference/rtc/restful/webhook/events#104-broadcaster-leave-channel) 识别待观察用户。 - 收到用户 A 离开频道事件 `104` 后,记录事件中的 `uid`、`channelName` 及离开的时间戳 `ts` 到缓存中,并将该用户列为待观察用户。设置用户的超时离开时间,如 30 秒,然后每 5 秒或 10 秒检索待观察用户列表。如果用户 A 离开的时间超过 30 秒,则调用[封禁用户权限 RESTful API](/zh-CN/api-reference/api-ref/rtc/create-ban-rule) 将用户 A 从频道中踢出。 - 收到用户 A 加入频道事件 `103` 后,识别事件中的 `channelName` 和 `uid`。如果缓存中该 `uid` 在当前频道中有记录,且未申请下麦,则将该 `uid` 从待观察用户列表中移除。 3. **客户端**:如果用户 B 收到 `onCallError` 回调,且 `errorEvent` 为 `rtcOccurError`,`errorType` 为 `rtc`,`errorCode` 为 `123`,表示用户 A 被踢出 RTC 频道。此时用户 B 可以调用 `CallAPI` 的 `hangup` 方法结束当前通话并离开通话页面。 ### 14. 更新频道号 [#14-更新频道号-1] 调用 [`prepareForCall`](/zh-CN/api-reference/private-room) 更新频道号。 主叫发起呼叫后,被叫会获取到主叫在准备通话环境中设置的 `roomId`,从而加入对应的 RTC 频道进行通话。通话结束后,如果主叫不更新 `roomId` 就发起新的呼叫,可能会有一定的安全风险。 以用户 A、B、C 为例,主叫 A 向用户 B 发起呼叫后,B 就获取了 A 的 RTC 频道名(`roomId`)。呼叫结束后,如果 A 不更新 `roomId` 就向用户 C 发起呼叫,用户 B 可以通过技术手段使用之前的 `roomId` 和通配 Token 加入用户 A 的频道进行盗流。 因此为确保通话安全,你需要在每次发起呼叫前,都调用 `prepareForCall` 方法更新 `roomId`,以保证每次通话使用不同的 RTC 频道,进而确保通话的私密性。 :::warning[注意] 由于 `PrepareConfig` 为全量更新,因此调用 `prepareForCall` 更新频道号时,请确保 `PrepareConfig` 中的其他属性均已设值,否则会调用失败。你可以将之前的 `PrepareConfig` 中的设置保存起来,修改 `roomId` 后进行传参。 ::: ```swift // 准备通话环境 let prepareConfig = PrepareConfig() // highlight-start // 设置新的频道号 prepareConfig.roomId = <#需要呼叫的频道 ID#> // 此处省略其他属性的设置。请确保同步设置其他属性 // highlight-end callApi.prepareForCall(prepareConfig: prepareConfig) { err in // 成功即可以开始进行呼叫 } ``` ### 15. 离开并释放资源 [#15-离开并释放资源-1] 如果要离开业务场景,还需要清理通话环境,释放相关资源。 ```swift // 清除 CallAPI 缓存 callApi.deinitialize { // 销毁 RTC 实例 AgoraRtcEngineKit.destroy() // 登出 RTM 服务 self.rtmManager.logout() // 其他业务逻辑 } ``` ## 开发注意事项 [#开发注意事项-1] 为确保通话安全,你需要在每次发起呼叫前,都调用 `prepareForCall` 方法更新 `roomId`,以保证每次通话使用不同的 RTC 频道,进而确保通话的私密性。详见 [14. 更新频道号](/zh-CN/solutions/one-to-one-live/rtm/build/implement-core-features/start-one-to-one)。 ## 参考文档 [#参考文档-1] 在开发过程中,你可以参考如下文档,获取更多 API 调用详情: - [CallAPI 参考](/zh-CN/api-reference/private-room) - [RTC API 参考](/zh-CN/api-reference/rtc/ios/rtc-api-overview) 如果希望在项目中实现更高阶的功能,可以参考[优化 RTM 信令方案集成逻辑](/zh-CN/solutions/one-to-one-live/rtm/build/customize-and-extend/integration-guideline)。 <_PlatformProcessedMarker close="true" />