跳到主要内容

连接流程

前置条件​

  • 通过服务端 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。

整体连接流程概述​

  1. 登录，APP 向 APPServer 请求登录
  2. 获取 IMToken：APPServer 向 IMServer 获取 IMToken
    • IMToken 可以设置有效时间
      • 如果设置了有效期，那么当 APP 遇到 Token 过期问题时，需要 APP 向 APPServer 请求新 IMToken
      • 如果设置了 IMToken 永久有效，那么 APPServer 可以做 IMToken 缓存，优化登录逻辑的耗时
  3. 返回 IMToken：IMServer 返回 Token
  4. 返回登录信息(IMToken)：APPServer 给 APP 返回登录信息，可能会有用户 id，名称，手机号等用户信息；IMToken
  5. 连接 IM：APP 调用 IMSDK 连接 IM
  6. 连接：IMSDK 向 IMServer 请求连接
  7. 连接结果：IMServer 返回连接结果给 IMSDK
  8. 连接结果：IMSDK 返回连接结果给 APP

连接聊天服务器​

请根据应用的业务需求与设计，自行决定合适的时机（登录、注册、或其他时机以免无法进入应用主页），向融云聊天服务器发起连接请求。

请注意以下几点：

  • 必须在 SDK 初始化之后，调用 connect 方法进行连接。否则会报错：SDK 未初始化。
  • SDK 本身有重连机制，在一个应用生命周期内不要多次调用 connect 。否则可能触发多个回调，触发导致回调被清除。
  • 在应用主进程内调用一次即可。

进行连接​

客户端用户首次连接聊天服务器时，建议设置有效的连接超时时间。在网络较差等导致连接超时的情况下，您可以利用接口的超时错误回调，并在 UI 上提醒用户，例如建议客户端用户等待网络正常的时候再次连接。

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

接口原型​

// 详细见 IMEngine.ts
public connect(token: string, timeout: number): Promise<IConnectResult>

参数说明​

参数类型说明
tokenstring从服务端获取的 Token。
timeoutnumber超时时间（秒）。超时后不再重连。取值 ≦ 0 则将一直连接，直到连接成功或者发生无法连接的业务错误。

  • timeout 参数详细说明：

    • timeout ≦ 0，IM 将一直连接，直到连接成功或者发生无法连接的业务错误（如 token 非法）。
    • timeout > 0，IM 将最多连接 timeout 秒。如果在 timeout 秒内无法连接成功则不再进行重连，报连接超时的错误，您需要再自行调用 connect 接口。

示例代码​

let token = "IMToken";
let timeout = 5;

hilog.info(0x0000, 'IM-App', 'connect token:%{public}s', token);
IMEngine.getInstance().connect(token, timeout)
  .then(result => {
    if (EngineError.Success === result.code) {
      // 连接成功
      let userId = result.userId;
      return;
    }

    if (EngineError.ConnectTokenExpired === result.code) {
      // Token 过期，从 APP 服务请求新 token，获取到新 token 后重新 connect()
    } else if (EngineError.ConnectionTimeout === result.code) {
      // 连接超时，弹出提示，可以引导用户等待网络正常的时候再次点击进行连接
    } else {
      //其它业务错误码，请根据相应的错误码作出对应处理。
    }
  });

连接接口的错误处理​

调用连接接口时，遇到下面的错误需要 APP 进行处理。

错误码取值错误原因处理方法
ClientNotInit33001SDK 没有初始化调用 init 接口来初始化 SDK。
ConnectionTimeout34006连接超时需要调用 connect 接口重新进行连接
ConnectTokenIncorrect31004Token 无法解析请检查客户端 appkey 和 token 是否为同一个环境
ConnectUserBlocked31009无法连接请自行检查融云管理后台该用户 ID 的状态
ConnectOneTimePasswordUsed31027一次性 token 已经被使用过需要重新请求 Token
ConnectPlatformError31028Token 绑定的平台与登录平台不符需要重新请求 Token
ConnectUserDeleteAccount31029用户账号已销户给用户提示，告知账号已注销
DisconnectUserKicked31010cmp 服务连接成功后，通知 SDK 用户被同账号其他端踢下线给用户提示，告知已被提掉线
DisconnectUserBlocked31011cmp 服务连接成功后，通知 SDK 用户被封禁给用户提示，告知已被封禁
ConnectTokenExpired31020Token 过期需要重新请求 Token
编辑此页
最后由 Gordon Zhu 于 更新