跳到主要内容

连接流程

前置条件

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