连接流程
前置条件
- 通过服务端 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。
整体连接流程概述
- 登录,APP 向 APPServer 请求登录
- 获取 IMToken:APPServer 向 IMServer 获取 IMToken
- IMToken 可以设置有效时间
- 如果设置了有效期,那么当 APP 遇到 Token 过期问题时,需要 APP 向 APPServer 请求新 IMToken
- 如果设置了 IMToken 永久有效,那么 APPServer 可以做 IMToken 缓存,优化登录逻辑的耗时
- IMToken 可以设置有效时间
- 返回 IMToken:IMServer 返回 Token
- 返回登录信息(IMToken):APPServer 给 APP 返回登录信息,可能会有用户 id,名称,手机号等用户信息;IMToken
- 连接 IM:APP 调用 IMSDK 连接 IM
- 连接:IMSDK 向 IMServer 请求连接
- 连接结果:IMServer 返回连接结果给 IMSDK
- 连接结果:IMSDK 返回连接结果给 APP
连接聊天服务器
请根据应用的业务需求与设计,自行决定合适的时机(登录、注册、或其他时机以免无法进入应用主页),向融云聊天服务器发起连接请求。
请注意以下几点:
- 必须在 SDK 初始化之后,调用 connect 方法进行连接。否则会报错:SDK 未初始化。
- SDK 本身有重连机制,在一个应用生命周期内不要多次调用 connect 。否则可能触发多个回调,触发导致回调被清除。
- 在应用主进程内调用一次即可。
进行连接
客户端用户首次连接聊天服务器时,建议设置有效的连接超时时间。在网络较差等导致连接超时的情况下,您可以利用接口的超时错误回调,并在 UI 上提醒用户,例如建议客户端用户等待网络正常的时候再次连接。
一旦连接成功,SDK 的重连机制将立即开始生效,并接管所有的重连处理。当因为网络原因断线时,SDK 会不停重连直到连接成功为止,不需要您做额外的连接操作。应用主动断开连接,将退出重连机制,详见断开连接。其他情况请参见重连机制与重连互踢。
接口原型
// 详细见 IMEngine.ts
public connect(token: string, timeout: number): Promise<IConnectResult>
参数说明
参数 | 类型 | 说明 |
---|---|---|
token | string | 从服务端获取的 Token。 |
timeout | number | 超时时间(秒)。超时后不再重连。取值 ≦ 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 进行处理。
错误码 | 取值 | 错误原因 | 处理方法 |
---|---|---|---|
ClientNotInit | 33001 | SDK 没有初始化 | 调用 init 接口来初始化 SDK。 |
ConnectionTimeout | 34006 | 连接超时 | 需要调用 connect 接口重新进行连接 |
ConnectTokenIncorrect | 31004 | Token 无法解析 | 请检查客户端 appkey 和 token 是否为同一个环境 |
ConnectUserBlocked | 31009 | 无法连接 | 请自行检查融云管理后台该用户 ID 的状态 |
ConnectOneTimePasswordUsed | 31027 | 一次性 token 已经被使用过 | 需要重新请求 Token |
ConnectPlatformError | 31028 | Token 绑定的平台与登录平台不符 | 需要重新请求 Token |
ConnectUserDeleteAccount | 31029 | 用户账号已销户 | 给用户提示,告知账号已注销 |
DisconnectUserKicked | 31010 | cmp 服务连接成功后,通知 SDK 用户被同账号其他端踢下线 | 给用户提示,告知已被提掉线 |
DisconnectUserBlocked | 31011 | cmp 服务连接成功后,通知 SDK 用户被封禁 | 给用户提示,告知已被封禁 |
ConnectTokenExpired | 31020 | Token 过期 | 需要重新请求 Token |