连接
连接
应用客户端成功连接到环信服务器后,才能使用环信即时通讯 SDK 的收发消息等功能。
你调用 login 方法登录后,客户端 SDK 会自动连接环信服务器。关于登录详情,请参见登录文档。
查询连接状态
自 SDK 4.26.0 起,你可以通过 [EMClient sharedClient].connectionState 查询 SDK 当前连接到聊天服务器的状态,便于展示连接进度或根据当前状态处理业务。
connectionState 为只读属性,返回 EMConnectionState,包含以下状态:
| 枚举值 | 说明 |
|---|---|
EMConnectionDisconnected | 未连接到聊天服务器。SDK 尚未初始化时也返回此状态。 |
EMConnectionConnecting | 正在连接聊天服务器。 |
EMConnectionConnected | 已连接到聊天服务器。 |
EMConnectionState state = [EMClient sharedClient].connectionState;
switch (state) {
case EMConnectionDisconnected:
// 展示未连接状态。
break;
case EMConnectionConnecting:
// 展示正在连接状态。
break;
case EMConnectionConnected:
// 展示已连接状态。
break;
}
isConnected 属性自 SDK 4.26.0 起标记为废弃,现有调用仍可使用。建议改用 connectionState,以区分未连接、连接中和已连接三种状态。
监听连接状态
你可以通过注册连接监听接收已连接或断开连接的通知。需要了解连接中的状态时,请查询 connectionState 属性。断开连接回调的触发时机还受到 断线通知宽限期 的影响。
override func viewDidLoad() {
...
// 注册连接状态监听,在 SDK 初始化之后调用。
EMClient.shared().add(self, delegateQueue: nil)
...
}
extension ViewController: EMClientDelegate {
// 连接成功,开始从服务器拉取离线消息时触发。
// 注意:如果本次登录服务器没有离线消息,不会触发该回调。
func onOfflineMessageSyncStart() {
}
// 离线用户上线后从服务器拉取离线消息结束时触发。
// 注意:如果再拉取离线过程中因网络或其他原因导致连接断开,不会触发该回调。
func onOfflineMessageSyncFinish() {
}
// 连接状态变更时触发该回调
func connectionStateDidChange(_ aConnectionState: EMConnectionState) {
}
// 自 4.15.0 版本,SDK 会在 Token 有效期达到 80% 时回调即将过期通知。
func tokenWillExpire(_ aErrorCode: EMErrorCode) {
// 通过 App Server 获取新的 token,然后调用 sdk 的 renewToken 方法更新 token
EMClient.shared().renewToken("newToken") { e in
}
}
// token 已过期
func tokenDidExpire(_ aErrorCode: EMErrorCode) {
}
}
配置断线通知宽限期
SDK 4.26.0 新增 EMOptions.disconnectNotifyThreshold 属性,用于设置或查询断线通知时间阈值,单位为秒,默认值为 10。
提示
在 iOS SDK 4.26.0 中,发生网络中断等情况时,SDK 会通过 connectionStateDidChange: 通知应用连接已断开。设置 disconnectNotifyThreshold 不会延迟该通知,也不会因短暂断线后快速重连成功而取消断开通知。
该属性不影响实际连接状态、自动重连行为或 APNs 的发送时间。需要判断当前连接状态时,请查询 connectionState。token 过期、账号被踢下线等情况,SDK 仍通过对应的回调通知应用。
自动重连
登录后,如果由于网络信号弱、切换网络等引起的连接中断,SDK 会自动尝试重连。你可以结合 connectionState 查询和 connectionStateDidChange 回调了解连接情况。SDK 4.26.0 的 iOS 普通断线回调不会因设置 disconnectNotifyThreshold 而延迟;重连成功后,SDK 会通知已连接状态。
不过,SDK 在以下情况下会停止自动重连。你需要调用 login 方法登录。
- 用户调用了 SDK 的登出方法
logout主动退出登录。 - 登录时鉴权错误,例如, token 无效(错误码 104)或已过期(错误码 108)。
- 用户在其他的设备上更改了密码,导致此设备上自动登录失败,提示错误码 216。
- 用户的账号被从服务器端删除,提示错误码 207。
- 用户在另一设备登录,将当前设备上登录的用户踢出,提示错误码 206。
- 用户登录设备数量超过限制,提示错误码 214。
- 应用程序的日活跃用户数量(DAU)或月活跃用户数量(MAU)达到上限,提示错误码 8。
- 开启多设备服务后,用户在其他设备上通过调用 API 或者环信控制台将当前设备登录的 ID 强制退出登录(错误码 217)。
