快速上手(OC)
本教程旨在帮助开发者快速了解和掌握 IMKit SDK (融云即时通讯 UI 库) 的基础集成流程与核心能力。通过本教程,您将完成 IMKit SDK 导入、初始化、建立连接、展示会话列表与会话页面、测试收发消息等全流程操作。
环境要求
- Xcode 需要使用 Xcode 11 及以上的版本。
- 苹果设备的系统需要使用 iOS 9.0 及以上的版本。
- 如果您打算通过 CocoaPods 集成 SDK,需要使用 CocoaPods 1.10.0 及以上的版本。这是因为 IMLib 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,以便完成上线前全流程测试和最终发布。
导入 SDK
融云支持通过 CocoaPods 添加远程依赖和将 IMKit 的相关 XCFramework 本地库导入应用工程两种集成方式。从 5.16.1 版本开始,IMKit SDK 也支持通过 Swift Package Manager 的方式导入。下文以通过 CocoaPods 添加远程依赖为示例。
以下介绍如何使用 CocoaPods 导入 IMKit 的 Framework。
-
如果您的项目中没有
Podfile
文件,您需要打开终端并进入到项目的根目录,在终端中运行pod init
命令,之后系统会自动创建一个默认的Podfile
文件,在项目中的Podfile
文件中添加如下内容:rubypod 'RongCloudIM/IMKit', '~> x.y.z'
提示其中
x.y.z
代表 IMLib 具体的版本号,您可以在融云官网 SDK 下载页面或在终端中通过先执行pod repo update
,再执行pod search RongCloudIM
命令在 CocoaPods 仓库查询 IMLib 最新的版本。 -
打开终端并进入到
Podfile
文件所在的目录,在终端中运行以下命令:shellpod install
提示如果终端中出现类似
CocoaPods could not find compatible versions for
等找不到相关版本的报错,可先在终端中执行pod repo update
命令,再执行pod install
命令。 -
通过 XCode 打开项目目录下的
xcworkspace
文件加载工程。
初始化 SDK
IMKit SDK 相关接口的调用都需要导入 SDK 的头文件:
#import <RongIMKit/RongIMKit.h>
为确保您可以正常连接融云服务器和使用融云即时通讯服务(IM 服务),您须调用 init 方法初始化 IMKit SDK。初始化前,您须在融云控制台中获取 App Key,并设置好 RCInitOption(初始化配置)。
RCInitOption 中封装了 areaCode (数据中心的区域码),naviServer(导航服务地址)、fileServer(文件服务地址)、statisticServer(数据统计服务地址)和 crashMonitorEnable(崩溃监控开关)。详见初始化。
如果您使用北京数据中心,则不需设置 RCInitOption,IMKit SDK 默认连接北京数据中心。
NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = nil;
[[RCIM sharedRCIM] initWithAppKey:appKey option:initOption];
如果您使用海外数据中心,则须传入海外数据中心对应的 AreaCode。
NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = [[RCInitOption alloc] init];
initOption.areaCode = RCAreaCodeSG;// 新加坡数据中心
[[RCIM sharedRCIM] initWithAppKey:appKey option:initOption];
如果您使用的开发版 IMKit SDK 版本号小于 5.4.2,或者稳定版 IMKit SDK 版本号小于等于 5.3.8,则您须调用 RCIM 的 initWithAppKey 方法,并传入 App Key 来进行初始化。详见初始化。
连接融云 IM 服务器
用户 Token 是与用户 ID 对应的身份验证令牌,是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 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 连接状态监听器,并在不需要的时候移除监听器。详见连接状态监听。
Objective C/// 添加代理委托
[[RCIM sharedRCIM] addConnectionStatusDelegate:self]; -
调用 connectWithToken 方法,将 userId 为 1 的用户连接融云 IM 服务。 IMKit SDK 有重连机制,因此一个应用生命周期内调用一次 connect即可,详见连接。
Objective C[[RCIM sharedRCIM] connectWithToken:@"后台获取的 token"
dbOpened:^(RCDBErrorCode code) {
//消息数据库打开,可以进入到主页面
}success:^(NSString *userId) {
//连接成功,可跳转至会话列表页
}error:^(RCConnectErrorCode status) {
if (status ==RC_CONN_TOKEN_INCORRECT) {
//从 APP 服务获取新 token,并重连
} else {
//无法连接到 IM 服务器,请根据相应的错误码作出对应处理
}
}];
展示会话列表
IMKit SDK 已默认提供会话列表页面 RCConversationListViewController
,会话列表页面上可查看当前所有的聊天会话。
在 IM 连接成功后可跳转至 SDK 会话列表页。您可以直接初始化 SDK 内置会话列表页面 RCConversationListViewController
,或通过继承创建一个子类来构建会话列表页面。用户首次连接时一般没有会话,因此会显示一个空会话列表。客户端接收到消息后,会自动在会话列表页面展示新会话。
推荐应用程序继承 SDK 内置的 RCConversationListViewController
,例如 RCDChatListViewController
类:
@interface RCDChatListViewController : RCConversationListViewController
@end
初始化自定义的会话列表页面 RCDChatListViewController
,以下代码示例中会话列表进展示单聊会话(ConversationType_PRIVATE
),页面导航器请自行创建。
NSArray *displayConversationTypeArray = @[@(ConversationType_PRIVATE)];
RCDChatListViewController *conversationListVC = [[RCDChatListViewController alloc] initWithDisplayConversationTypes:displayConversationTypeArray
collectionConversationType:nil];
[self.navigationController pushViewController:conversationListVC animated:YES];
详细使用方法,参见会话列表页面。
展示会话页面
IMKit SDK 已默认提供会话页面 RCConversationViewController
,您可以在会话页面可进行消息编辑、查看、发送等活动。
您可以在会话列表页面重写点击会话 Cell 的方法,跳转到 SDK 默认内置的会话页面 RCConversationViewController
。
- (void)onSelectedTableRow:(RCConversationModelType)conversationModelType
conversationModel:(RCConversationModel *)model
atIndexPath:(NSIndexPath *)indexPath {
RCConversationViewController *conversationVC = [[RCConversationViewController alloc] initWithConversationType:model.conversationType
targetId:model.targetId];
conversationVC.title = @"想显示的会话标题";
[self.navigationController pushViewController:conversationVC animated:YES];
}
详细使用方法,参见会话页面。
测试收发消息
对融云来说,只要提供对方的 userId
,融云就可支持跟对方发起聊天。例如,A 需要 发送消息给 B,只需要将 B 的 userId 告知融云服务即可发送消息。
在本教程中,为了快速体验和测试 SDK,我们从控制台「北极星」开发者工具箱 IM Server API 调试页面向当前登录的用户发送一条文本消息,模拟单聊会话。在实际业务运行过程中,应用客户端可以通过用户 userId、群聊会话 targetId、或聊天室 targetId 等接收消息。
-
访问控制台北极星开发者工具箱的 IM Server API 调试页面。
-
在消息标签下,找到 消息服务 > 发送单聊消息 接口。
以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。
-
客户端接收到消息后,会自动在会话列表页面展示新的单聊会话。点击会话,即可进入消息列表页面,发送消息。
后续步骤
以上步骤即 IMKit SDK 的快速集成与新手体验流程,您体验了基础 IM 通信能力和 UI 界面,更多详细介绍请参考后续各章节详细说明。