建立连接
应用客户端成功连接到融云服务器后,才能使用融云即时通讯 SDK 的收发消息功能。
融云服务端在收到客户端发起的连接请求后,会根据连接请求里携带的用户身份验证令牌(Token 参数),判断是否允许用户连接。
前置条件
- 通过服务端 API 注册用户(获取 Token)。融云客户端 SDK 不提供获取 Token 方法。应用程序可以调用自身服务端,从融云服务端获取 Token。
- 取得 Token 后,客户端可以按需保存 Token,供后续连接时使用。具体保存位置取决于应用程序客户端设计。如果 Token 未失效,就不必再向融云请求 Token。
- Token 有效期可在控制台进行配置,默认为永久有效。即使重新生成了一个新 Token,未过期的旧 Token 仍然有效。Token 失效后,需要重新获取 Token。如有需要,可以主动调用服务端 API 作废 Token。
- 建议应用程序在连接之前设置连接状态监听。
- SDK 已完成初始化。
请不要在客户端直接调用服务端 API 获取 Token。获取 Token 需要提供应用的 App Key 和 App Secret。客户端如果保存这些凭证,一旦被反编译,会导致应用的 App Key 和 App Secret 泄露。所以,请务必确保在应用服务端获取 Token。
连接聊天服务器
请根据应用的业务需求与设计,自行决定合适的时机(登陆、注册、或其他时机以免无法进入应用主页),向融云聊天服务器发起连接请求。
请注意以下几点:
- 必须在 SDK 初始化之后,调用
connect
方法进行连接。否则可能没有回调。 - SDK 内部实现了重连机制,在网络异常导致 IM 连接断开时,会自动重连,直到应用主动断开连接(见断开连接)。
接口(可设置超时)
客户端用户首次连接聊天服务器时,建议调用带连接超时时间(timeLimit
)的接口,并设置超时秒数。在网络较差等导致连接超时的情况下,你可以利用接口的超时错误回调,并在 UI 上提醒用户,例如建议客户端用户等待网络正常的时候再次连接。
一旦连接成功,SDK 的重连机制将立即开始生效,并接管所有的重连处理。当因为网络原因断线时,SDK 会不停重连直到连接成功为止,不需要您做额外的连接操作。应用主动断开连接,将退出重连机制,详见断开连接。其他情况请参见下面重连机制详解。
如果免密登录,建议将 timeLimit
参数设置为 0,可以在 dbOpenedBlock
回调中进行页面跳转,优先展示本地历史数据。连接逻辑则完全托管给 SDK。
调用示例
[[RCIMClient sharedRCIMClient] connectWithToken:@"开发者的 server 通过请求 server api 获取到的 token 值"
timeLimit:5
dbOpened:^(RCDBErrorCode code) {
//消息数据库打开,可以进入到主页面
} success:^(NSString *userId) {
//连接成功
} error:^(RCConnectErrorCode status) {
if (status == RC_CONN_TOKEN_INCORRECT) {
//Token 错误,可检查客户端 SDK 初始化与 App 服务端获取 Token 时所使用的 App Key 是否一致
} else if(status == RC_CONNECT_TIMEOUT) {
//连接超时,弹出提示,可以引导用户等待网络正常的时候再次点击进行连接
} else {
//无法连接 IM 服务器,请根据相应的错误码作出对应处理
}
}]
输入参数说明
参数 | 类型 | 说明 |
---|---|---|
token | NSString | 首次连接时必须由 App 服务端调用融云服务端 API 获取。参见服务端 API 文档 注册用户 |
timeLimit | int | SDK 连接超时时间,单位:秒 |
dbOpenedBlock | Block | 本地消息数据库打开的回调 |
successBlock | Block | 连接建立成功的回调 |
errorBlock | Block | 连接建立失败的回调 |
-
timeLimit
参数说明:参数 取值范围 说明 timeLimit ≦ 0 SDK 会一直连接,直到连接成功或者出现 SDK 无法处理的错误(如 token 非法),等效于上面的连接接口。 timeLimit > 0 SDK 最多连接 timeLimit 秒,超时则返回 RC_CONNECT_TIMEOUT 错误,并不再重连。
返回参数说明
-
dbOpenedBlock
说明:回调参数 回调类型 说明 code RCDBErrorCode 数据库是否已打开 -
successBlock
说明:回调参数 回调类型 说明 userId NSString 当前连接成功的用户 ID -
errorBlock
说明:回调参数 回调类型 说明 status RCConnectErrorCode 连接失败的错误码。详见下文连接状态码。
接口(无超时设置)
如果客户端用户已成功登录过你的应用,且连接过融云聊天服务器,后续离线登录时建议使用此接口。
此时因用户已有历史数据,并不需要强依赖于连接成功。可以在 dbOpenedBlock
回调中进行页面跳转,优先展示本地历史数据。连接逻辑完全托管给 SDK 即可。
当网络较差时,有可能长时间不会回调。
调用此接口后,SDK 的重连机制将立即开始生效,并接管所有的重连处理。SDK 会不停重连直到连接成功为止,不需要您做额外的连接操作。应用主动断开连接,将退出重连机制,详见断开连接。其他情况请参见下面重连机制详解。
调用示例
[[RCIMClient sharedRCIMClient] connectWithToken:@"开发者的 server 通过请求 server api 获取到的 token 值"
dbOpened:^(RCDBErrorCode code) {
//消息数据库打开,可以进入到主页面
}
success:^(NSString *userId) {
//连接成功
}
error:^(RCConnectErrorCode status) {
if (status == RC_CONN_TOKEN_INCORRECT) {
//从 APP 服务获取新 token,并重连
} else {
//无法连接到 IM 服务器,请根据相应的错误码作出对应处理
}
}]
输入参数说明
参数 | 类型 | 说明 |
---|---|---|
token | NSString | 需要您的 Server 访问融云服务获取 Token |
dbOpenedBlock | Block | 本地消息数据库打开的回调 |
successBlock | Block | 连接建立成功的回调 |
errorBlock | Block | 连接建立失败的回调 |
返回参数说明
-
dbOpenedBlock
说明:回调参数 回调类型 说明 code RCDBErrorCode 数据库是否已打开 -
successBlock
说明:回调参数 回调类型 说明 userId NSString 当前连接成功的用户 ID -
errorBlock
说明:回调参数 回调类型 说明 status RCConnectErrorCode 连接失败的错误码。详见下文连接状态码。
连接状态码
具体可以参考下表 RCConnectErrorCode
具体错误码的说明和处理方案建议
关于 RC_CONN_TOKEN_INCORRECT
的说明:
- 在
RC_CONN_TOKEN_INCORRECT
的情况下,您需要请求您的服务器重新获取 Token 并建立连接,但是注意避免无限循环,以免影响 App 用户体验。 - 此方法的回调线程并非为原调用线程,需要进行 UI 操作时请注意切换到主线程。
错误码 | 值 | 说明 | 处理方案 |
---|---|---|---|
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_DISCONN_KICK | 31010 | 用户连接成功后被踢下线 | 退回到登录页面,给用户提示被踢掉线 |
RC_CONN_OTHER_DEVICE_LOGIN | 31023 | 用户连接过程中又在其它设备上登录,导致当前设备被踢 | 退回到登录页面,给用户提示其他设备登录了当前账号 |
RC_CONN_USER_BLOCKED | 31009 | 用户在线时被封禁导致连接断开。 | 退回到登录页面,给用户提示被封禁 |
RC_CONNECT_TIMEOUT | 34006 | 自动重连超时。常见于无网络的环境,且仅发生在调用连接接口并设置了有效超时时间的情况。超时后 SDK 会放弃重连。开发者需要自行给用户提示,可提示用户等待网络恢复时再重新连接。 | 重新调用连接手动重连 |
RC_CONN_APP_BLOCKED_OR_DELETED | 31008 | Appkey 被封禁 | 请检查您使用的 AppKey 是否被封禁或已删除 |
RC_CONN_PROXY_UNAVAILABLE | 31028 | 代理服务不可访问 | |
RC_CLIENT_NOT_INIT | 33001 | SDK 没有初始化 | 在使用 SDK 任何功能之前,必须先 Init |
RC_INVALID_PARAMETER | 33003 | 开发者接口调用时传入的参数错误 | 请检查接口调用时传入的参数类型和值 |
DATABASE_ERROR | 33002 | 数据库错误 | 检查用户 userId 是否包含特殊字符,SDK userId 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 64 字节 |