跳到主要内容

快速上手(OC)

本教程是为了让新手快速了解融云即时通讯界面库(IMKit)。在本教程中,您可以体验集成 IMKit SDK 的基本流程和 IMKit 提供的 UI 界面。

前置条件

  • 注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。

  • 获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret

    提示

    每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。

环境要求

名称版本
Xcode11 +
iOS9.0 +
CocoaPods1.10.0 +

SDK 5.1.1 及其以后要求使用 CocoaPods 1.10.0 +,具体请参见知识库文档

开始集成

IMKit 支持通过 CocoaPods 或手动导入的方式集成。请提前在融云官网 SDK 下载页面或 CocoaPods 仓库查询最新版本。安装 IMKit 将同时集成即时通讯能力库 IMLib。其他插件可按需集成。

导入 SDK

以下介绍如何使用 CocoaPods 导入 IMKit 的 Framework。

  1. podfile 中添加如下内容:

    pod 'RongCloudIM/IMKit', '~> x.y.z'
    提示

    x.y.z 代表具体版本,请在融云官网 SDK 下载页面或 CocoaPods 仓库查询最新版本。

  2. 请在终端中运行以下命令:

    pod install
    提示

    如果出现找不到相关版本的问题,可先执行 pod repo update,再执行 pod install

  3. 上一步完成后,CocoaPods 会在您的工程根目录下生成一个 xcworkspace 文件,只需通过 XCode 打开该文件即可加载工程。

使用 App key 初始化

融云即时通讯客户端 SDK 核心类为 RCIM。在初始化 SDK 时,需要传入生产开发环境的 App Key。

导入 IMKit SDK 头文件。

#import <RongIMKit/RongIMKit.h>

如果 SDK 版本 ≧ 5.4.2,请使用以下初始化方法。

NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = nil;

[[RCIM sharedRCIM] initWithAppKey:appKey option:initOption];

初始化配置(RCInitOption)中封装了区域码(RCAreaCode),导航服务地址(naviServer)、文件服务地址(fileServer)、数据统计服务地址(statisticServer)配置。不作设置表示全部使用默认配置。SDK 默认连接北京数据中心。

如果 App Key 不属于中国(北京)数据中心,则必须传入有效的初始化配置。初始化详细说明参见初始化

获取用户 Token

用户 Token 是与用户 ID 对应的身份验证令牌,是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接,连接时必须传入 Token。

在实际业务运行过程中,应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户

在本教程中,为了快速体验和测试 SDK,我们将使用控制台「北极星」开发者工具箱,从 API 调试页面调用 获取 Token 接口,获取到 userId 为 1 的用户的 Token。提交后,可在返回正文中取得 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"}

建立 IM 连接

  1. 监听 IM 连接状态的变化。建议代理对象设置为 AppDelegate 之类的单例对象,保证 APP 整个生命周期都可以监听到代理方法。详见连接状态监听

    /// 添加代理委托
    [[RCIM sharedRCIM] addConnectionStatusDelegate:self];
  2. 在自定义登录页面,使用用户 John Joe 的 token 融云建立 IM 连接。

    [[RCIM sharedRCIM] connectWithToken:@"后台获取的 token"
    dbOpened:^(RCDBErrorCode code) {
    //消息数据库打开,可以进入到主页面
    }success:^(NSString *userId) {
    //连接成功,可跳转至会话列表页
    }error:^(RCConnectErrorCode status) {
    if (status == RC_CONN_TOKEN_INCORRECT) {
    //从 APP 服务获取新 token,并重连
    } else {
    //无法连接到 IM 服务器,请根据相应的错误码作出对应处理
    }
    }];

SDK 已实现自动重连机制,请参见连接

展示会话列表

IMKit SDK 已默认提供会话列表页面 RCConversationListViewController 和会话页面 RCConversationViewController。会话列表页面上可查看当前所有的聊天会话,在会话页面可进行消息编辑、查看、发送等活动。

在 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];
提示

下图为融云 SealTalk 应用截图。IMKit SDK 默认提供的会话列表页面实现仅包含会话列表,不含搜索、不含底部 Tab Bar 等。如需显示会话列表的昵称和头像,您需要为 IMKit 设置一个用户信息提供者,详见用户概述

alt(width=250) alt(width=250)

详细使用方法,参见会话列表页面

展示会话页面

重写会话列表页面点击会话 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 调试页面向当前登录的用户发送一条文本消息,模拟单聊会话。在实际业务运行过程中,应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。

  1. 访问控制台「北极星」开发者工具箱的 IM Server API 调试页面。

  2. 消息标签下,找到 消息服务 > 发送单聊消息 接口。

    以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。

    message sent from console

  3. 客户端接收到消息后,自动在会话列表页面展示新的单聊会话。点击会话,即可进入消息列表页面,发送消息。

    alt(width=250) alt(width=250)

后续步骤

以上步骤即 IMKit SDK 的快速集成与新手体验流程,您体验了基础 IM 通信能力和 UI 界面,更多详细介绍请参考后续各章节详细说明。

  • 用户概述:了解 IMKit 与用户相关的服务,以及 IMKit 如何展示头像、昵称、群组成员等
  • 群组概述:了解如何使用 IMKit 构建群聊体验
  • 会话列表页面:如何构建会话列表页面以及定制化
  • 会话页面:如何构建会话页面以及定制化