实现音视频通话
本教程旨在帮助开发者快速了解和掌握 CallLib SDK(融云音视频呼叫能力库)的基础集成流程与核心通话功能。CallLib 是在 RTCLib 基础上封装的音视频呼叫功能 SDK,支持单人、多人音视频通话的各种场景。通过本教程,您将完成服务开通、SDK 初始化、事件监听、连接服务、发起呼叫、接听通话和挂断等全流程操作。
考虑移动设备的带宽(主要是在多路视频情况下),建议单次通话或房间内,视频不超过 16 人,纯音频不超过 32 人。超过此上限可能影响通话效果。
环境要求
- Xcode 需要使用 Xcode 11 及以上的版本。
- 苹果设备的系统需要使用 iOS 9.0 及以上的版本。
- 需要真机设备运行测试相关音视频通话功能。
- 如果您打算通过 CocoaPods 集成 SDK,需要使用 CocoaPods 1.10.0 及以上的版本。这是因为 CallLib SDK 5.1.1 版本后变更为 XCFramework,而 CocoaPods 是从 1.10.0 版本后才完整支持 XCFramework 的集成方式,具体请参见知识库文档。
如需安装 CocoaPods 环境,请参照 安装 CocoaPods。
准备工作
-
访问融云控制台,注册您的开发者账号。注册成功后,控制台自动在开发环境中为您创建一个应用。
-
在控制台的基本信息页,获取您的应用在开发环境的 AppKey。您可在基本信息页查看应用的信息,如 App Key、App Secret、所属数据中心(默认为北京)。
如您想自己创建应用,参考如何创建应用,并获取对应环境 App Key 和 App Secret。
提示每个应用均拥有两个不同的 App Key,分别对应开发环境与生产环境,且两个环境之间数据相互隔离。在您的应用正式上线前,建议切换到生产环境的 App Key,以便完成上线前全流程测试和最终发布。
服务开通
您在融云创建的应用默认不会启用音视频服务。在使用融云提供的任何音视频服务前,您需要前往控制台 ,为应用开通音视频服务。
具体步骤请参阅控制台文档开通音视频服务。
- 服务开通、关闭等设置完成后 15 分钟后生效。
- 客户端配置文件更新最长 2 小时,您可以在服务生效后卸载重装来立刻获取最新配置。
导入 SDK
融云支持通过 CocoaPods 添加远程依赖和将 CallLib 的相关 XCFramework 本地库导入应用工程两种集成方式。下文以通过 CocoaPods 添加远程依赖为示例。
-
如果您的项目中没有
Podfile
文件,您需要打开终端并进入到项目的根目录,在终端中运行pod init
命令,之后系统会自动创建一个默认的Podfile
文件,在项目中的Podfile
文件中添加如下内容:rubypod 'RongCloudRTC/RongCallLib', '~> x.y.z'
提示- CallLib 会自动依赖下载对应版本的 IMLib 库,一般不需要手动指定。注意,从 5.2.0 版本至 5.4.4(不含),CallLib 必须与其依赖的 IMKit/IMLib SDK 保持版本一致(前三位必须保持一致)。从 5.4.4 开始,CallLib 与其依赖的 IMKit/IMLib SDK 版本号前两位保持一致。CallLib 5.4.4 不可匹配小 于 5.4.4 的 IMKit/IMLib SDK。
x.y.z
代表 CallLib 具体的版本号,您可以在融云官网 SDK 下载页面或在终端中通过先执行pod repo update
,再执行pod search RongCloudRTC
命令在 CocoaPods 仓库查询 CallLib 最新的版本。
-
打开终端并进入到
Podfile
文件所在的目录,在终端中运行以下命令:shellpod install
提示如果终端中出现类似
CocoaPods could not find compatible versions for
等找不到相关版本的报错,可先在终端中执行pod repo update
命令,再执行pod install
命令。 -
通过 Xcode 打开项目目录下的
xcworkspace
文件加载工程。
初始化 SDK
CallLib 是基于 IMLibCore 作为信令通道的,您须调用 init 方法初始化 IMLib SDK。初始化前,您须在融云控制台中获取 App Key,并设置好 RCInitOption(初始化配置)。
IMLib SDK 相关接口的调用都需要导入 SDK 的头文件:
#import <RongIMLibCore/RongIMLibCore.h>
RCInitOption 中封装了 areaCode (数据中心的区域码),naviServer(导航服务地址)、fileServer(文件服务地址)、statisticServer(数据统计服务地址)和 crashMonitorEnable(崩溃监控开关)。详见初始化。
如果您使用北京数据中心,则不需设置 RCInitOption,IMLib SDK 默认连接北京数据中心。
NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = nil;
[[RCCoreClient sharedCoreClient] initWithAppKey:appKey option:initOption];
如果您使用海外数据中心,则须传入海外数据中心对应的 AreaCode。
NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = [[RCInitOption alloc] init];
initOption.areaCode = RCAreaCodeSG;// 新加坡数据中心
[[RCCoreClient sharedCoreClient] initWithAppKey:appKey option:initOption];
如果您使用的开发版 CallLib SDK 版本号小于 5.4.2,或者稳定版 CallLib SDK 版本号小于等于 5.3.8,则您须调用 RCCoreClient 的 initWithAppKey 方法,并传入 App Key 来进行初始化。详见初始化。
通话事件处理
通过设置通话事件相关监听器,用户可接收其他用户的通话申请以及监听通话状态的变化。
为确保接收离线通话,请在初始化 SDK 后,连接 IM 融云服务器 之前设置监听器。
监听通话呼入
-
通过
RCCallClient
单例对象设置 RCCallReceiveDelegate 代理。Objective C[[RCCallClient sharedRCCallClient] setDelegate:"RCCallReceiveDelegate 的实现类"];
-
在代理对象中实现 RCCallReceiveDelegate 的通话呼入的方法即可收到来电。
Objective C- (void)didReceiveCall:(RCCallSession *)callSession;
监听通话状态变化
RCCallSession
中定义了 RCCallSessionDelegate,支持监听通话状态的变化。获取 RCCallSession
对象后,可以通过 RCCallSession 的如下方法添加与移除代理。
/*!
添加通话状态的监听器, 支持多代理
@param delegate 通话状态变化的监听器
@discussion
添加通话状态的监听器, 支持多代理
@remarks 通话设置
*/
- (void)addDelegate:(id<RCCallSessionDelegate>)delegate;
/**
删除通话状态的监听器
@param delegate 通话状态的监听器
@discussion
删除通话状态的监听器
@remarks 通话设置
*/
- (void)removeDelegate:(id<RCCallSessionDelegate>)delegate;
通话计时
CallLib SDK 无法直接获取通话时长。您可以在 RCCallSessionDelegate 的音频或视频首帧回调中,使用当前时间减去通话开始时间,计算通话时长。
代理方法:
- (void)receiveRemoteUserVideoFirstKeyFrame:(NSString *)userId {
// 视频通话在此处开启一个定时器
}
- (void)receiveRemoteUserVideoFirstAudioFrame:(NSString *)userId {
// 音频通话在此处开启一个定时器
}
您可以在定时器中使用以下方法,获取当前通话的秒数:
long sec = ([[NSDate date] timeIntervalSince1970] * 1000 - [RCCallClient sharedRCCallClient].currentCallSession.connectedTime) / 1000;
如需在应用程序的服务端进行通话计时,建议使用融云提供的服务端回调音视频房间状态同步。通过实时回调事件 event 11(成员加入音视频房间)和 event 12(成员离开音视频房间)记录计费的开始和结束时间。
连接融云 IM 服务器
用户 Token 是与用户 ID 对应的身份验证令牌,是应用程序的用户在融云的唯一身份标识。音视频用户之间的信令传输依赖于融云的即时通信(IM)服务,与融云建立 IM 连接,连接时必须传入 Token。
在实际业务运行过程中,应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。
在本教程中,为了快速体验和测试 SDK,我们将使用控制台「北极星」开发者工具箱,从 API 调试页面调用 获取 Token 接口,获取到 userId 为 1 的用户的 Token。提交后,可在返回正文中取得 Token 字符串。
- 为模拟用户通过融云 IM 服务器进行通话,您需要首先注册一个用户。在实际业务中,应用客户端通过应用服务端调用融云 IM Server API 获取 token。详见 Server API 文档注册用户。在本教程中,为了快速体验融云服务,您可在控制台「北极星」的 API 调试页面调用获取 Token 接口,获取到 userId 为 1 的用户的 Token。调用返回如下:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"code":200,"userId":"1","token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"}
- 设置连接监听器来实时获取连接状态。您可以将连接状态通过 UI 反馈给用户(例如提示 “网络连接中断” 或 “已重新连接”),提高用户体验。建议在应用生命周期内,初始化 SDK 之后,连接 IM 之前设置 IM 连接状态监听器,并在不需要的时候移除监听器。详见设置连接状态监听。
@protocol RCConnectionStatusChangeDelegate <NSObject>
// 添加代理委托
[[RCCoreClient sharedCoreClient] addConnectionStatusChangeDelegate:self];
/*!
IMLib连接状态的监听器
@param status SDK与融云服务器的连接状态
@discussion 如果您设置了IMLib 连接监听之后,当SDK与融云服务器的连接状态发生变化时,会回调此方法。
*/
- (void)onConnectionStatusChanged:(RCConnectionStatus)status {
}
@end
- 调用 connectWithToken 方法,将 userId 为 1 的用户连接融云 IM 服务。 注:IMLib SDK 有重连机制,因此一个应用生命周期内调用一次 connect 即可,详见连接。
[[RCCoreClient sharedCoreClient] connectWithToken:@"融云 token" dbOpened:^(RCDBErrorCode code) {
//消息数据库打开,可以进入到主页面
} success:^(NSString *userId) {
//连接成功
} error:^(RCConnectErrorCode errorCode) {
if (status == RC_CONN_TOKEN_INCORRECT) {
//从 APP 服务获取新 token,并重连
} else {
//无法连接到 IM 服务器,请根据相应的错误码作出对应处理
}
}];
发起呼叫
使用 RCCallClient
的 startCall:targetId:to:mediaType:sessionDelegate:extra:
方法对指定对象发起呼叫请求。
self.callSession = [[RCCallClient sharedRCCallClient] startCall:conversationType
targetId:targetId
to:userIdList
mediaType:mediaType
sessionDelegate:self
extra:nil];
呼叫接听
当需要接听通话时,利用来电代理返回的 callSession 对象调用接听方法。
- (void)didReceiveCall:(RCCallSession *)callSession {
[callSession accept:callSession.mediaType];
}
挂断
当需要挂断通话时,利用发起呼叫返回的 callSession 或来电代理返回的 callSession 对象调用挂断方法。
[self.callSession hangup];