跳到主要内容

建立连接

应用客户端成功连接到融云服务器后，才能使用融云即时通讯 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。

接口原型​

Objective C
- (void)connectWithToken:(NSString *)token
               timeLimit:(int)timeLimit
                dbOpened:(nullable void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(nullable void (^)(NSString *userId))successBlock
                   error:(nullable void (^)(RCConnectErrorCode errorCode))errorBlock;

参数说明​

参数类型说明
tokenNSString首次连接时必须由 App 服务端调用融云服务端 API 获取。参见服务端 API 文档 注册用户
timeLimitintSDK 连接超时时间，单位：秒
dbOpenedBlockBlock本地消息数据库打开的回调
successBlockBlock连接建立成功的回调
errorBlockBlock连接建立失败的回调

  • timeLimit 参数说明：

    参数取值范围说明
    timeLimit≦ 0SDK 会一直连接，直到连接成功或者出现 SDK 无法处理的错误（如 token 非法），等效于上面的连接接口。
    timeLimit> 0SDK 最多连接 timeLimit 秒，超时则返回 RC_CONNECT_TIMEOUT 错误，并不再重连。

  • dbOpenedBlock 说明：

    回调参数回调类型说明
    codeRCDBErrorCode数据库是否已打开

  • successBlock 说明：

    回调参数回调类型说明
    userIdNSString当前连接成功的用户 ID

  • errorBlock 说明：

    回调参数回调类型说明
    statusRCConnectErrorCode连接失败的错误码。详见下文连接状态码。

示例代码​

Objective C
[[RCCoreClient sharedCoreClient] connectWithToken:@"开发者的 server 通过请求 server api 获取到的 token 值"
    timeLimit:30
    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 服务器，请根据相应的错误码作出对应处理
        }
    }]

接口（无超时设置）​

如果客户端用户已成功登录过您的应用，且连接过融云聊天服务器，后续离线登录时建议使用此接口。

此时因用户已有历史数据，并不需要强依赖于连接成功。可以在回调数据库打开（dbOpenedBlock）后就进行页面跳转，优先展示本地历史数据。连接逻辑完全托管给 SDK 即可。

提示

SDK 从 5.20.0 版本开始提供该接口。

调用此接口后，SDK 的重连机制将立即开始生效，并接管所有的重连处理。SDK 会不停重连直到连接成功为止，不需要您做额外的连接操作。应用主动断开连接，将退出重连机制，详见断开连接。其他情况请参见重连机制与重连互踢。

接口原型​

Objective C
- (void)connectWithToken:(NSString *)token
                dbOpened:(nullable void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(nullable void (^)(NSString *userId))successBlock
                   error:(nullable void (^)(RCConnectErrorCode errorCode))errorBlock;

参数说明​

参数类型说明
tokenNSString需要您的 Server 访问融云服务获取 Token
dbOpenedBlockBlock本地消息数据库打开的回调
successBlockBlock连接建立成功的回调
errorBlockBlock连接建立失败的回调

  • dbOpenedBlock 说明：

    回调参数回调类型说明
    codeRCDBErrorCode数据库是否已打开

  • successBlock 说明：

    回调参数回调类型说明
    userIdNSString当前连接成功的用户 ID

  • errorBlock 说明：

    回调参数回调类型说明
    statusRCConnectErrorCode连接失败的错误码。详见下文连接状态码。

示例代码​

Objective C
[[RCCoreClient sharedCoreClient] connectWithToken:@"开发者的 server 通过请求 server api 获取到的 token 值"
        dbOpened:^(RCDBErrorCode code) {
            //消息数据库打开，可以进入到主页面
        }
        success:^(NSString *userId) {
            //连接成功
        }
        error:^(RCConnectErrorCode status) {
            if (status == RC_CONN_TOKEN_INCORRECT) {
                //从 APP 服务获取新 token，并重连
            } else {
                //无法连接到 IM 服务器，请根据相应的错误码作出对应处理
            }
        }]

连接状态码​

具体可以参考下表 RCConnectErrorCode 具体错误码的说明和处理方案建议

提示

关于 RC_CONN_TOKEN_INCORRECT 的说明：

  1. 在 RC_CONN_TOKEN_INCORRECT 的情况下，您需要请求您的服务器重新获取 Token 并建立连接，但是注意避免无限循环，以免影响 App 用户体验。
  2. 此方法的回调线程并非为原调用线程，需要进行 UI 操作时请注意切换到主线程。
错误码值说明处理方案
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_DISCONN_KICK31010用户连接成功后被踢下线退回到登录页面，给用户提示被踢掉线
RC_CONN_OTHER_DEVICE_LOGIN31023用户连接过程中又在其它设备上登录，导致当前设备被踢退回到登录页面，给用户提示其他设备登录了当前账号
RC_CONN_USER_BLOCKED31009用户在线时被封禁导致连接断开。退回到登录页面，给用户提示被封禁
RC_CONNECT_TIMEOUT34006自动重连超时。常见于无网络的环境，且仅发生在调用连接接口并设置了有效超时时间的情况。超时后 SDK 会放弃重连。开发者需要自行给用户提示，可提示用户等待网络恢复时再重新连接。重新调用连接手动重连
RC_CONN_APP_BLOCKED_OR_DELETED31008Appkey 被封禁请检查您使用的 AppKey 是否被封禁或已删除
RC_CONN_PROXY_UNAVAILABLE31028代理服务不可访问
RC_CLIENT_NOT_INIT33001SDK 没有初始化在使用 SDK 任何功能之前，必须先 Init
RC_INVALID_PARAMETER33003开发者接口调用时传入的参数错误请检查接口调用时传入的参数类型和值
DATABASE_ERROR33002数据库错误检查用户 userId 是否包含特殊字符，SDK userId 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 64 字节
最后于 更新