跳到主要内容

快速上手

本教程是为了让新手快速了解融云即时通讯能力库（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​

方式一： CocoaPods

  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 打开该文件即可加载工程。

方式二： Swift Package Manager

提示

通过 Swift Package Manager 导入的方式，从 IMLib 5.12.2 开始支持。

  1. 打开 Xcode 工程。

  2. 进入 File > Add Package Dependency。

  3. 弹出框右上角，粘贴入下面的 URL 地址之一:

  4. Xcode 将会弹出产品选择，IMLibCore 提供核心 IM 能力， 其余组件可根据业务类型自行选择。

组件介绍

融云 IM SDK 提供了如下几种组件供开发者选择使用，以下组件可组合使用，能力介绍如下：

Swift Package动态库描述
IMLibCoreRongIMLibCore.xcframeworkIM 核心功能.
ChatRoomRongChatRoom.xcframework聊天室功能（包含 IMLibCore）
CustomerServiceRongCustomerService.xcframework客服功能（包含 IMLibCore）
DiscussionRongDiscussion.xcframework讨论组功能（包含 IMLibCore）
PublicServiceRongPublicService.xcframework公众号功能（包含 IMLibCore）

初始化 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) {
    //失败
}];
最后于 更新