跳到主要内容

快速上手（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 构建群聊体验
  • 会话列表页面：如何构建会话列表页面以及定制化
  • 会话页面：如何构建会话页面以及定制化
最后于 更新