连接
应用客户端成功连接到融云服务器后,才能使用融云即时通讯 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。
连接 IM 服务器
请根据应用的业务需求与设计,自行决定合适的时机(登陆、注册、或其他时机以免无法进入应用主页),向融云聊天服务器发起连接请求。
方法
Future<int> connect(String token, int timeout, {RCIMIWConnectCallback? callback});
参数说明
参数名 | 参数类型 | 描述 |
---|---|---|
token | String | 调用 server api 获取到的 token |
timeout | int | 连接超时时间,单位:秒。 |
callback | RCIMIWConnectCallback | 链接事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回 调方式。如果传入了 callback 参数,仅触发 callback 回调。 |
返回值
返回值 | 描述 |
---|---|
Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考错误码 |
代码示例
RCIMIWConnectCallback? callback = RCIMIWConnectCallback(onDatabaseOpened: (int? code) {
//...
}, onConnected: (int? code, String? userId) {
//...
});
int? ret = await engine?.connect(token, timeout, callback:callback);
回调方法
- onDatabaseOpened
数据库打开的回调
Function(int? code)? onDatabaseOpened;
参数说明
参数名 | 参数类型 | 描述 |
---|---|---|
code | int | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
代码示例
engine?.onDatabaseOpened = (int? code) {
//...
};
- onConnected
收到连接状态的回调
Function(int? code, String? userId)? onConnected;
参数说明
参数名 | 参数类型 | 描述 |
---|---|---|
code | int | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
userId | String | 链接成功的用户 ID |
代码示例
engine?.onConnected = (int? code, String? userId) {
//...
};
提示
- SDK 本身有重连机制,在一个应用生命周期内不须多次调用
connect()
。否则可能触发多个回调,触发导致回调被清除。 - 在
code
为 31004 的情况下,您需要请求您的服务器重新获取 Token 并建立连接,但是注意避免无限循环,以免影响 App 用户体验。
token 无效(31004)排查方案
原因 | 排查方案 |
---|---|
token 错误 | 检查客户端初始化使用的 AppKey 和您服务器获取 Token 使用的 AppKey 是否一致 |
token 过期 | 检查开发者是否在 控制台 设置了 Token 过期时间,过期之后需要请求您的服务器重新获取 Token 并再次用新的 Token 建立连接 |
错误码
连接错误码参见原生平台错误码定义 Android 错误码 和 iOS 错误码