跳到主要内容

快速上手(Swift)

前置条件

  • 注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 App Key,使用国内数据中心。

  • 获取开发环境的应用 App Key。如不使用默认应用,请参考 如何创建应用,并获取对应环境 App Key 和 App Secret

    提示

    每个应用具有两个不同的 App Key,分别对应开发环境与生产环境,两个环境之间数据隔离。在您的应用正式上线前,可切换到使用生产环境的 App Key,以便上线前进行测试和最终发布。

环境要求

名称版本
Xcode11 +
iOS9.0 +
Swift5.0 +
CocoaPods1.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)。

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

步骤 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 连接与连接状态监听

  1. 监听 IM 连接状态的变化。建议代理对象设置为 AppDelegate 之类的单例对象,保证 APP 整个生命周期都可以监听到代理方法。详见连接状态监听
  2. 在自定义登录页面,使用上一步获取的 token 与融云建立 IM 连接,即模拟 userId 为 1 的用户连接到融云服务器。
  3. 在需要与 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_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与服务器的连接已断开,用户被封禁

步骤 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 等接收消息。

  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 构建群聊体验
  • 会话列表页面:如何构建会话列表页面以及定制化
  • 会话页面:如何构建会话页面以及定制化