跳到主要内容

快速上手（Swift）

本教程旨在帮助开发者快速了解和掌握 IMKit SDK (融云即时通讯 UI 库) 的基础集成流程与核心能力。通过本教程，您将完成 IMKit SDK swfit 方式下的导入、初始化、建立连接、展示会话列表与会话页面、测试收发消息等全流程操作。

环境要求​

  • Xcode 需要使用 Xcode 11 及以上的版本。
  • 苹果设备的系统需要使用 iOS 9.0 及以上的版本。
  • Swift 版本需要 5.0 及以上的版本
  • 如果您打算通过 CocoaPods 集成 SDK，需要使用 CocoaPods 1.10.0 及以上的版本。这是因为 IMLib SDK 5.1.1 版本后变更为 XCFramework，而 CocoaPods 是从 1.10.0 版本后才完整支持 XCFramework 的集成方式，具体请参见知识库文档。

如需安装 CocoaPods 环境，请参照 安装 CocoaPods。

准备工作​

  1. 访问融云控制台，注册您的开发者账号。注册成功后，控制台自动在开发环境中为您创建一个应用。

  2. 在控制台的基本信息页，获取您的应用在开发环境的 AppKey。您可在基本信息页查看应用的信息，如 App Key、App Secret、所属数据中心（默认为北京）。 alt text 如您想自己创建应用，参考如何创建应用，并获取对应环境 App Key 和 App Secret。

    提示

    每个应用均拥有两个不同的 App Key，分别对应开发环境与生产环境，且两个环境之间数据相互隔离。在您的应用正式上线前，建议切换到生产环境的 App Key，以便完成上线前全流程测试和最终发布。

导入 SDK​

融云支持通过 CocoaPods 添加远程依赖和将 IMKit 的相关 XCFramework 本地库导入应用工程两种集成方式。下文以通过 CocoaPods 添加远程依赖为示例。

提示

从 5.16.1 版本开始，IMKit SDK 也支持通过 Swift Package Manager 的方式导入。

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

  1. 如果您的项目中没有 Podfile 文件，您需要打开终端并进入到项目的根目录，在终端中运行 pod init 命令，之后系统会自动创建一个默认的 Podfile 文件，在项目中的 Podfile 文件中添加如下内容：

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

    其中 x.y.z 代表 IMLib 具体的版本号，您可以在融云官网 SDK 下载页面或在终端中通过先执行 pod repo update，再执行 pod search RongCloudIM 命令在 CocoaPods 仓库查询 IMLib 最新的版本。

  2. 打开终端并进入到 Podfile 文件所在的目录，在终端中运行以下命令：

    shell
    pod install
    提示

    如果终端中出现类似 CocoaPods could not find compatible versions for 等找不到相关版本的报错，可先在终端中执行 pod repo update 命令，再执行 pod install 命令。

  3. 通过 XCode 打开项目目录下的 xcworkspace 文件加载工程。

初始化 SDK​

IMKit SDK 相关接口的调用都需要导入 SDK 的头文件：

swift
import RongIMKit

为确保您可以正常连接融云服务器和使用融云即时通讯服务（IM 服务），您须调用 init 方法初始化 IMKit SDK。初始化前，您须在融云控制台中获取 App Key，并设置好 RCInitOption（初始化配置）。 RCInitOption 中封装了 areaCode （数据中心的区域码），naviServer（导航服务地址）、fileServer（文件服务地址）、statisticServer（数据统计服务地址）和 crashMonitorEnable（崩溃监控开关）。详见初始化。

如果您使用北京数据中心，则不需设置 RCInitOption，IMLib SDK 默认连接北京数据中心。

swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let appKey: String = "Your_AppKey" // example: bos9p5rlcm2ba
    let option: RCInitOption? = nil
    RCIM.shared().initWithAppKey(appKey, option: option)

    return true
}

如果您使用海外数据中心，则须传入海外数据中心对应的 AreaCode。

swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let appKey: String = "Your_AppKey" // example: bos9p5rlcm2ba
    let option: RCInitOption? = RCInitOption.init();
    option?.areaCode = .SG;
    RCIM.shared().initWithAppKey(appKey, option: option)
    return true
}
提示

如果您使用的开发版 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 字符串。

  1. 为模拟用户通过融云 IM 服务器收发消息，您需要首先注册一个用户。在实际业务中，应用客户端通过应用服务端调用融云 IM Server API 获取 token。详见 Server API 文档注册用户。在本教程中，为了快速体验融云服务，您可在控制台「北极星」的 API 调试页面调用获取 Token 接口，获取到 userId 为 1 的用户的 Token。调用返回如下：
HTTP
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"}
  1. 设置连接监听器来实时获取连接状态。您可以将连接状态通过 UI 反馈给用户（例如提示 “网络连接中断” 或 “已重新连接”），提高用户体验。建议在应用生命周期内，初始化 SDK 之后，连接 IM 之前设置 IM 连接状态监听器，并在不需要的时候移除监听器。详见[连接状态监听]。
swift
import UIKit
import RongIMKit

class ViewController: UIViewController {

override func viewDidLoad() {
    super.viewDidLoad()
    connectRongcloud()
    }

func connectRongcloud() {
/*
请在初始化之后，连接之前设置连接监听代理委托。
*/
RCIM.shared().addConnectionStatusDelegate(self)
}
/*
    IMKit连接状态的监听器

    @param status SDK与融云服务器的连接状态

    @discussion 在您设置IMKit连接监听之后，当IMKit与融云服务器的连接状态发生变化时，会回调此方法。
    */
extension ViewController: RCIMConnectionStatusDelegate {
func onRCIMConnectionStatusChanged(_ status: RCConnectionStatus) {

    }
}
}
  1. 调用 connectWithToken 方法，将 userId 为 1 的用户连接融云 IM 服务。 注：IMKit SDK 有重连机制，因此一个应用生命周期内调用一次 connect即可，详见连接。
swift
RCIM.shared().connect(withToken: "后台获取的 token") { dbErrorCode in
        // 消息数据库打开，可以进入到主页面

} success: { (userId: String?) in
        /* 连接成功,可跳转至会话列表页 */
        DispatchQueue.main.async { [weak self] in
        /* `openRongcloudConversationList`方法可在**Step 5**中寻找 */
        self?.openRongcloudConversationList()
        }

} error: { (connectStatus: RCConnectErrorCode) in
    if connectStatus == .RC_CONN_TOKEN_INCORRECT {
        /* 从 APP 服务获取新 token，并重连 */
    } else {
        /* 无法连接到 IM 服务器，请根据相应的错误码作出对应处理 */
    }
}

RCConnectErrorCode 定义了连接时可能返回的连接异常状态码。以下的状态码需要 APP 进行处理。

错误码值说明处理方案
RC_CONN_TOKEN_INCORRECT31004Token 错误。常见于客户端 SDK 与 App 服务器所使用的 App Key 不一致的错误情况。融云的每个应用都提供用于隔离生产和开发环境的两套独立 App Key / Secret。由测试环境切换到生产环境时，很容易发生应用客户端与应用服务端 App Key 不一致的问题。检查 SDK 与 App 服务器使用的 App Key 是否一致。
RC_CONN_TOKEN_EXPIRE31020Token 已过期。常见于控制台设置了 Token 过期时间。Token 过期之后需要由您的 App 服务器请求融云服务端重新获取 Token，并再次用新的 Token 建立连接客户端需要请求 App 服务端，向融云获取新的 token。客户端收到新的 Token 后，使用新 Token 发起连接。
RC_CONNECT_TIMEOUT34006自动重连超时。常见于无网络的环境，且仅发生在调用连接接口并设置了有效超时时间的情况。超时后 SDK 会放弃重连。开发者需要自行给用户提示，可提示用户等待网络恢复时再重新连接。重新调用连接手动重连
RC_CONN_APP_BLOCKED_OR_DELETED31008Appkey 被封禁请检查您使用的 AppKey 是否被封禁或已删除
RC_DISCONN_KICK31010用户连接成功后被踢下线退回到登录页面，给用户提示被踢掉线
RC_CONN_OTHER_DEVICE_LOGIN31023用户连接过程中又在其它设备上登录，导致当前设备被踢退回到登录页面，给用户提示其他设备登录了当前账号
RC_CONN_USER_BLOCKED31009用户被封禁退回到登录页面，给用户提示被封禁
RC_CLIENT_NOT_INIT33001SDK 没有初始化在使用 SDK 任何功能之前，必须先 Init
RC_INVALID_PARAMETER33003开发者接口调用时传入的参数错误请检查接口调用时传入的参数类型和值
DATABASE_ERROR33002数据库错误检查用户 userId 是否包含特殊字符，SDK userId 支持大小写英文字母、数字的组合方式，最大长度 64 字节

RCConnectionStatus 定义了连接状态监听的可能返回的状态。以下的状态码需要 APP 进行处理。

错误码值说明
ConnectionStatus_KICKED_OFFLINE_BY_OTHER_CLIENT6当前用户在其他设备上登录，此设备被踢下线
ConnectionStatus_Timeout14自动连接超时，SDK 将不会继续连接，用户需要做超时处理，再自行调用 connectWithToken 接口进行连接
ConnectionStatus_TOKEN_INCORRECT15Token 无效。
  • Token 错误：常见于客户端 SDK 与 App 服务器所使用的 App Key 不一致的错误情况。融云的每个应用都提供用于隔离生产和开发环境的两套独立 App Key / Secret。由测试环境切换到生产环境时，很容易发生应用客户端与应用服务端 App Key 不一致的问题。
  • Token 已过期：常见于控制台设置了 Token 过期时间。Token 过期之后需要由您的 App 服务器请求融云服务端重新获取 Token，并再次用新的 Token 建立连接
ConnectionStatus_DISCONN_EXCEPTION16与服务器的连接已断开，用户被封禁

展示会话列表​

IMKit SDK 已默认提供会话列表页面 RCConversationListViewController，会话列表页面上可查看当前所有的聊天会话。

在 IM 连接成功后可跳转至 SDK 会话列表页。您可以直接初始化 SDK 内置会话列表页面 RCConversationListViewController，或通过继承创建一个子类来构建会话列表页面。用户首次连接时一般没有会话，因此会显示一个空会话列表。客户端接收到消息后，会自动在会话列表页面展示新会话。

以下示例中创建了页面导航器。如果您已经在使用导航控制器，也可以使用 pushViewController 功能。

swift
private func openRongcloudConversationList() {
    let displayConversationTypeArray = [
        RCConversationType.ConversationType_PRIVATE.rawValue,
        RCConversationType.ConversationType_GROUP.rawValue,
    ]
    let collectionConversationType = [
        RCConversationType.ConversationType_SYSTEM.rawValue
    ]
    guard let conversationList = RCConversationListViewController(displayConversationTypes: displayConversationTypeArray,
                                                                  collectionConversationType: collectionConversationType) else { return }
    let naviVC = UINavigationController(rootViewController: conversationList)
    naviVC.modalPresentationStyle = .fullScreen
    present(naviVC, animated: false)
}
提示

推荐继承 IMKit 的 RCConversationListViewController 创建子类会话话列表页面，例如 RCDChatListViewController，方便应用程序在其中进行一些自定义操作。

swift
//
//  RCDChatListViewController.swift
//  RongcloudApplication
//

import Foundation
import RongIMKit

class RCDChatListViewController: RCConversationListViewController {

}

详细使用方法，参见会话列表页面、会话页面。

测试收发消息​

对融云来说，只要提供对方的 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)

    提示

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

后续步骤​

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

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