跳到主要内容

快速上手

本教程是为了让新手快速了解融云即时通讯能力库（IMLib）。在本教程中，你可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。

前置条件​

  • 注册开发者账号。注册成功后，控制台会默认自动创建您的首个应用，默认生成开发环境下的 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 +，具体请参见知识库文档。

导入 SDK​

  1. 在 podfile 中添加如下内容：

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

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

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

    pod install
    提示

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

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

初始化 SDK​

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

导入 SDK 头文件。

#import <RongIMLib/RongIMLib.h>

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

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

[[RCCoreClient sharedCoreClient] 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 连接​

使用以上步骤中获取的 Token，模拟 userId 为 1 的用户连接到融云服务器。

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

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

调用完连接后，你可以设置连接状态监听来实时监听 IM 连接状态，以便 UI 上给用户以提示，提高体验。

监听消息​

设置消息接收监听器，用于接收所有类型的实时或者离线消息。实现此功能需要开发者遵守 RCIMClientReceiveMessageDelegate 协议。

  1. 在初始化之后，连接之前设置监听器的代理委托。

    [[RCCoreClient sharedCoreClient] setReceiveMessageDelegate:self object:nil];

  2. 实现代理方法

    当 SDK 在接收到消息时，开发者可通过下面方法进行处理。 SDK 会通过此方法接收包含单聊、群聊、聊天室、系统类型的所有消息，开发者只需全局设置一次即可，多次设置会导致其他代理失效。

    - (void)onReceived:(RCMessage *)message left:(int)nLeft object:(id)object {

    }

发送消息​

向 userId 为 2 的用户发送一条文本消息。下面示例中先构造了文本消息内容 *messageContent，随后构造了 RCMessage 消息实例，消息实例中指定了收件人的用户 ID 为 2，以及当前的会话类型为私聊 ConversationType_PRIVATE。

RCTextMessage *messageContent = [RCTextMessage messageWithContent:@"测试文本消息"];

RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                            targetId:@"2"
                                           direction:MessageDirection_SEND
                                             content:messageContent];

[[RCCoreClient sharedCoreClient] sendMessage:message
                                 pushContent:nil
                                    pushData:nil
                                    attached:^(RCMessage *message) {
                                            // 消息已存入本地数据库
                                        }
                                successBlock:^(RCMessage *successMessage) {
                                            //成功
                                        }
                                  errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
                                            //失败
                                        }];
最后于 更新