快速上手（Swift）
前置条件
-
注册开发者账号。注册成功后，控制台会默认自动创建您的首个应用，默认生成开发环境下的 App Key，使用国内数据中心。
-
获取开发环境的应用 App Key。如不使用默认应用，请参考 如何创建应用，并获取对应环境 App Key 和 App Secret。
提示每个应用具有两个不同的 App Key，分别对应开发环境与生产环境，两个环境之间数据隔离。在您的应用正式上线前，可切换到使用生产环境的 App Key，以便上线前进行测试和最终发布。
环境要求
| 名称 | 版本 |
|---|---|
| Xcode | 11 + |
| iOS | 9.0 + |
| Swift | 5.0 + |
| CocoaPods | 1.10.0 + |
SDK 5.1.1 及其以后要求使用 CocoaPods 1.10.0 +，具体请参见知识库文档。
开始集成
IMKit 支持通过 CocoaPods 或手动导入的方式集成。请提前在融云官网 SDK 下载页面或 CocoaPods 仓库查询最新版本。安装 IMKit 将同时集成即时通讯能力库 IMLib。其他插件可按需集成。
要求使用 5.4.2 或更高版本。
步骤 1 创建一个项目
打开 Xcode 并创建一个新项目。RongCloudIM/IMKit 支持 swift。
步骤 2 安装 IMKit
您可以通过 CocoaPods 来安装 iOS 版本的 IMKit (含 UI SDK)。
-
在
podfile中添加如下内容：pod 'RongCloudIM/IMKit', '~> x.y.z'提示x.y.z代表具体版本，请在融云官网 SDK 下载页面或 CocoaPods 仓库查询最新版本。 -
请在终端中运行以下命令：
pod install提示如果出现找不到相关版本的问题，可先执行
pod repo update，再执行pod install。 -
上一步完成后，CocoaPods 会在您的工程根目录下生成一个
xcworkspace文件，只需通过 XCode 打开该文件即可加载工程。
步骤 3 用 App Key 初始化
要在您的应用中集成和运行 Rongcloud IMKit (含 UI SDK)，您需要首先引入 RongIMKit 然后通过 AppDelegate 初始化 RCIM。
import RongIMKit
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
}
即使您不使用 AppDelegate，您仍然应该在启动聊天服务之前初始化 RCIM。
步骤 4 获取用户 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"}
步骤 5 连接与连接状态监听
- 监听 IM 连接状态的变化。建议代理对象设置为 AppDelegate 之类的单例对象，保证 APP 整个生命周期都可以监听到代理方法。详见连接状态监听。
- 在自定义登录页面，使用上一步获取的
token与融云建立 IM 连接，即模拟userId为 1 的用户连接到融云服务器。 - 在需要与
RongcloudIM建立连接的页面或者模块中调用connectRongcloud方法。
import UIKit
import RongIMKit
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
connectRongcloud()
}
func connectRongcloud() {
/*
请在初始化之后，连接之前设置连接监听代理委托。
*/
RCIM.shared().addConnectionStatusDelegate(self)
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 服务器，请根据相应的错误码作出对应处理 */
}
}
}
}
/*
IMKit连接状态的监听器
@param status SDK与融云服务器的连接状态
@discussion 在您设置IMKit连接监听之后，当IMKit与融云服务器的连接状态发生变化时，会回调此方法。
*/
extension ViewController: RCIMConnectionStatusDelegate {
func onRCIMConnectionStatusChanged(_ status: RCConnectionStatus) {
}
}
RCConnectErrorCode 定义了连接时可能返回的连接异常状态码。以下的状态码需要 APP 进行处理。
| 错误码 | 值 | 说明 | 处理方案 |
|---|---|---|---|
| RC_CONN_TOKEN_INCORRECT | 31004 | Token 错误。常见于客户端 SDK 与 App 服务器所使用的 App Key 不一致的 错误情况。融云的每个应用都提供用于隔离生产和开发环境的两套独立 App Key / Secret。由测试环境切换到生产环境时，很容易发生应用客户端与应用服务端 App Key 不一致的问题。 | 检查 SDK 与 App 服务器使用的 App Key 是否一致。 |
| RC_CONN_TOKEN_EXPIRE | 31020 | Token 已过期。常见于控制台设置了 Token 过期时间。Token 过期之后需要由您的 App 服务器请求融云服务端重新获取 Token，并再次用新的 Token 建立连接 | 客户端需要请求 App 服务端，向融云获取新的 token。客户端收到新的 Token 后，使用新 Token 发起连接。 |
| RC_CONNECT_TIMEOUT | 34006 | 自动重连超时。常见于无网络的环境，且仅发生在调用连接接口并设置了有效超时时间的情况。超时后 SDK 会放弃重连。开发者需要自行给用户提示，可提示用户等待网络恢复时再重新连接。 | 重新调用连接手动重连 |
| RC_CONN_APP_BLOCKED_OR_DELETED | 31008 | Appkey 被封禁 | 请检查您使用的 AppKey 是否被封禁或已删除 |
| RC_DISCONN_KICK | 31010 | 用户连接成功后被踢下线 | 退回到登录页面，给用户提示被踢掉线 |
| RC_CONN_OTHER_DEVICE_LOGIN | 31023 | 用户连接过程中又在其它设备上登录，导致当前设备被踢 | 退回到登录页面，给用户提示其 他设备登录了当前账号 |
| RC_CONN_USER_BLOCKED | 31009 | 用户被封禁 | 退回到登录页面，给用户提示被封禁 |
| RC_CLIENT_NOT_INIT | 33001 | SDK 没有初始化 | 在使用 SDK 任何功能之前，必须先 Init |
| RC_INVALID_PARAMETER | 33003 | 开发者接口调用时传入的参数错误 | 请检查接口调用时传入的参数类型和值 |
| DATABASE_ERROR | 33002 | 数据库错误 | 检查用户 userId 是否包含特殊字符，SDK userId 支持大小写英文字母、数字的组合方式，最大长度 64 字节 |
RCConnectionStatus 定义了连接状态监听的可能返回的状态。以下的状态码需要 APP 进行处理。
| 错误码 | 值 | 说明 |
|---|---|---|
| ConnectionStatus_KICKED_OFFLINE_BY_OTHER_CLIENT | 6 | 当前用户在其他设备上登录，此设备被踢下线 |
| ConnectionStatus_Timeout | 14 | 自动连接超时，SDK 将不会继续连接，用户需要做超时处理，再自行调用 connectWithToken 接口进行连接 |
| ConnectionStatus_TOKEN_INCORRECT | 15 | Token 无效。
|
| ConnectionStatus_DISCONN_EXCEPTION | 16 | 与服务器的连接已断开，用户被封禁 |
步骤 6 展示会话列表
IMKit SDK 已默认提供会话列表页面 RCConversationListViewController 和会话页面 RCConversationViewController。会话列表页面上可查看当前所有的聊天会话，在会话页面可进行消息编辑、查看、发送等活动。
在 RCIM 连接成功后可跳转至 SDK 会话列表页。您可以直接初始化 SDK 内置会话列表页面 RCConversationListViewController，或通过继承创建一个子类来构建会话列表页面。首次连接时一般没有会话，因此会显示一个空会话列表。客户端接收到消息后，会自动在会话列表页面展示新会话。
以下示例中创建了页面导航器。如果您已经在使用导航控制器，也可以使用 pushViewController 功能。
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，方便应用程序在其中进行一些自定义操作。
//
// RCDChatListViewController.swift
// RongcloudApplication
//
import Foundation
import RongIMKit
class RCDChatListViewController: RCConversationListViewController {
}
步骤 7 测试收发消息
对融云来说，只要提供对方的 userId，融云就可支持跟对方发起聊天。例如，A 需要 发送消息给 B，只需要将 B 的 userId 告知融云服务即可发送消息。
在本教程中，为了快速体验和测试 SDK，我们从控制台「北极星」开发者工具箱 IM Server API 调试页面向当前登录的用户发送一条文本消息，模拟单聊会话。在实际业务运行过程中，应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。
-
访问控制台「北极星」开发者工具箱的 IM Server API 调试页面。
-
在消息标签下，找到 消息服务 > 发送单聊消息 接口。
以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。
-
客户端接收到消息后，自动在会话列表页面展示新的单聊会话。点击会话，即可进入消息列表页面，发送消息。
提示上图为融云 SealTalk 应用截图。IMKit SDK 默认提供的会话列表页面实现仅包含会话列表，不含搜索、不含底部 Tab Bar 等。如需显示会话列表的昵称和头像，您需要为 IMKit 设置一个用户信息提供者，详见用户概述。
后续步骤
以上步骤即 IMKit SDK 的快速集成与新手体验流程，您体验了基础 IM 通信能力和 UI 界面，更多详细介绍请参考后续各章节详细说明。