连接
应用客户端成功连接到融云服务器后,才能使用融云即时通讯 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 本身有重连机制,在一个应用生命周期内不要多次调用
connect
,否则可能触发多个回调,导致回调被清除。 - 在应用主进程内调用一次即可。
接口(可设置超时)
客户端用户首次连接聊天服务器时,建议您调用带连接超时时间(timeLimit
)的接口,并设置超时秒数。在网络较差等导致连接超时的情况下,您可以利用接口的超时错误回调,并在 UI 上提醒用户,例如建议客户端用户等待网络正常的时候再次连接。
一旦连接成功,SDK 的重连机制将立即开始生效,并接管所有的重连处理。当因为网络原因断线时,SDK 会不停重连直到连接成功为止,您不需要做额外的连接操作。如果应用主动断开连接,将退出重连机制,详见断开连接。其他情况请参见重连机制与重连互踢。
如果后续离线登录,建议将 timeLimit
参数设置为 0
,可以在回调数据库打开(onDatabaseOpened
)后就进行页面跳转,优先展示本地历史数据。连接逻辑则完全托管给 SDK。
接口
RongIMClient.connect(token, timeLimit, connectCallback);
参数说明
参数 | 类型 | 说明 |
---|---|---|
token | String | 从服务端获取的 Token。 |
timeLimit | Int | 超时时间(单位:秒)。超时后不再重连。取值 ≦ 0 则将一直连接,直到连接成功或者发生业务错误。 |
connectCallback | ConnectCallback | 连接回调。详见连接回调方法说明。 |
-
timeLimit
参数详细说明:timeLimit
≦ 0,IM 将一直连接,直到连接成功或者发生业务错误(如 Token 非法)。timeLimit
> 0,IM 将最多连接timeLimit
秒。如果在timeLimit
秒内无法连接成功则不再进行重连,通过回调onError
告知连接超时,您需要再自行调用connect
接口。
示例代码
public connectIM(String token) {
boolean isCachedLogin == getLoginStatusFromSP(context); // 伪代码,从 sharedpreference 里读取该用户是否为免密登录
int timeLimit = 0;
if(!isCachedLogin) {
timeLimit = 5;
}
RongIMClient.connect("用户Token", timeLimit, new RongIMClient.ConnectCallback() {
@Override
public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus code) {
if (RongIMClient.DatabaseOpenStatus.DATABASE_OPEN_SUCCESS.equals(code)) {
// 本地数据库打开,跳转到会话列表页面
} else {
// 数据库打开失败,可以弹出 toast 提示。
}
}
@Override
public void onSuccess(String s) {
// 连接成功,如果 onDatabaseOpened() 时没有页面跳转,也可在此时进行跳转。
}
@Override
public void onError(RongIMClient.ConnectionErrorCode errorCode) {
if (errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONN_TOKEN_EXPIRE)) {
// 从 APP 服务请求新 token,获取到新 token 后重新 connect()
} else if (errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONNECT_TIMEOUT)) {
// 连接超时,弹出提示,可以引导用户等待网络正常的时候再次点击进行连接
} else {
// 其它业务错误码,请根据相应的错误码作出对应处理。
}
}
});
}
接口(带用户 ID)
此接口从开发版 5.20.0 或稳定版 5.7.5 开始支持。
较上面的连接接口增加用户 ID 参数,可在发生连接异常时通过用户 ID 进行问题排查,后续还将支持通过用户 ID 进行导航缓存,相比其他连接接口完成耗时更短,推荐使用此接口。
接口
RongCoreClient.connect(final String token,
final int timeLimit,
final String userId,
final IRongCoreCallback.ConnectCallback connectCallback);
开发者须确保此用户 ID 匹配 Token 对应的用户 ID,否则可能造成问题排查干扰。
接口(无超时设置)
如果客户端用户已成功登录过您的应用,且连接过融云聊天服务器,后续离线登录时建议使用此接口。
此时因用户已有历史数据,并不需要强依赖于连接成功。可以在回调数据库打开(onDatabaseOpened
)后就进行页面跳转,优先展示本地历史数据。连接逻辑完全托管给 SDK 即可。
当网络较差时,有可能长时间不会回调。
调用此接口后,SDK 的重连机制将立即开始生效,并接管所有的重连处理。SDK 会不停重连直到连接成功为止,您不需要做额外的连接操作。如果应用主动断开连接,将退出重连机制,详见断开连接。其他情况请参见重连机制与重连互踢。
接口
RongIMClient.connect(token, connectCallback);
参数说明
参数 | 类型 | 说明 |
---|---|---|
token | String | 从服务端获取的用户身份令牌(Token)。 |
connectCallback | ConnectCallback | 连接回调。详见下文 |