登录登出
更新时间: 2023/08/15 02:22:00
信令SDK依赖 IM 账号体系,在使用 SDK 之前,需要对云信的体系流程有基本的认知,推荐开发者首先阅读这里 。
手动登录
objc@protocol NIMLoginManager <NSObject>
/**
* 登录
*
* @param account 账号
* @param token 令牌 (在后台绑定的登录token)
* @param completion 完成回调
*/
- (void)login:(NSString *)account
token:(NSString *)token
completion:(NIMLoginHandler)completion;
@end
示例
objcNSString *account = @"your account";
NSString *token = @"your token";
[[[NIMSDK sharedSDK] loginManager] login:account
token:token
completion:^(NSError *error) {}];
error 为登录错误信息,成功则为 nil。
在手动登录之前, APP 的本地数据为关闭状态,登录成功后即可调用查询本地数据方法,如本地好友,群组等。
SDK 不支持直接添加云信用户,请参考这里,在您的应用服务器上使用 Http 接口进行添加。
自动登录
APP 启动时,如果已保存用户名和密码可以选择调用自动登录接口,并立刻打开主界面。此时 APP 可以在无网络,未登录成功的状态下直接访问用户本地数据。此类登录需要调用如下接口:
原型
objc@protocol NIMLoginManager <NSObject>
/**
* 自动登录
*
* @param loginData 自动登录参数
* @discussion 启动APP如果已经保存了用户账号和令牌,建议使用这个登录方式,使用这种方式可以在无网络时直接打开会话窗口
*/
- (void)autoLogin:(NIMAutoLoginData *)loginData;
@end
NIMAutoLoginData 参数列表
参数 | 类型 | 说明 |
---|---|---|
account | NSString | 账号 |
token | NSString | 令牌(在后台绑定的登录token) |
forcedMode | BOOL | 强制模式开关 |
NIMAutoLoginData
中的 forcedMode
为强制模式开关。非强制模式下的自动登录,服务器将检查当前登录设备是否为上一次登录设备,如果不是,服务器将拒绝这次自动登录(返回 error code 为 417 的错误);强制模式下的自动登录,服务器将不检查当前登录设备是否为上一次登录设备,安全性较低,但较为便捷。
示例
objcNIMAutoLoginData *loginData = [[NIMAutoLoginData alloc] init];
loginData.account = account;
loginData.token = token;
[[[NIMSDK sharedSDK] loginManager] autoLogin:loginData];
和手动登录不同,自动登录在失败后会自动重试登录,并通过委托通知登录状态。 APP 需要实现如下回调 (手动登录也会收到同样的委托回调)
objc@protocol NIMLoginManagerDelegate <NSObject>
/**
* 登录回调
*
* @param step 登录步骤
* @discussion 这个回调主要用于客户端UI的刷新
*/
- (void)onLogin:(NIMLoginStep)step
@end
NIMLoginStep 枚举列表
值 | 说明 |
---|---|
NIMLoginStepLinking | 连接服务器 |
NIMLoginStepLinkOK | 连接服务器成功 |
NIMLoginStepLinkFailed | 连接服务器失败 |
NIMLoginStepLogining | 登录 |
NIMLoginStepLoginOK | 登录成功 |
NIMLoginStepLoginFailed | 登录失败 |
NIMLoginStepSyncing | 开始同步数据 |
NIMLoginStepSyncOK | 同步数据完成 |
NIMLoginStepLoseConnection | 连接断开 |
NIMLoginStepNetChanged | 网络切换 |
一次完整的登录的基本步骤为
-
NIMLoginStepLinking
-
NIMLoginStepLinkOK
-
NIMLoginStepLogining
-
NIMLoginStepLoginOK
-
NIMLoginStepSyncing
-
NIMLoginStepSyncOK
-
自动登录失败的回调
objc- (void)onAutoLoginFailed:(NSError *)error
自动登录除了会触发相应步骤变化回调外,在发生错误时也会触发如上回调。在碰到一些 SDK 无法自动解决的错误时,开发者需要在此回调里做出相应的处理。
举例来说,当前网络状态较差时,容易导致自动登录发生网络超时错误,此时上层无需处理,SDK 会持续有策略地重连。重连详情请参考这里。
而一旦发生用户名密码不匹配的错误时,则需要上层做出相应处理:登出并提示用户手动登录或是从自己的应用服务器刷新相应的用户名密码。一些特殊的登录错误将在下文列出,建议在集成时能尽可能考虑相应应对逻辑。
自动重连机制
SDK 提供了自动重连机制(重新建立与网易云通信服务器的连接并重新登录),所有重连和登录状态都会在上述的 - (void)onLogin:(NIMLoginStep)step
方法中回调。
SDK 在两种场景下会自动进行重连:
- 用户在 APP 启动之后调用过云信自动登录方法。
- 用户在 APP 启动之后调用过手动登录方法,并登录成功。
满足上述中一个条件,当用户遇到普通网络问题如连接超时,后台返回到前台等,会自动进行重连登录,不需要上层开发者去做额外的重登逻辑。
一些严重错误,如账号被踢出、账号被封禁,SDK 不会进行自动重连;重试次数超过预定上限时, SDK 也不会继续重连。
重试次数在 NIMSDKConfig
中定义,默认为 0 ,为无次数限制重试。
原型
objc@interface NIMSDKConfig : NSObject
/**
* 自动登录重试次数
* @discusssion 默认为 0。即默认情况下,自动登录将无限重试。设置成大于 0 的值后,在没有登录成功前,自动登录将重试最多 maxAutoLoginRetryTimes 次,如果失败,则抛出错误 (NIMLocalErrorCodeAutoLoginRetryLimit)。
*/
@property (nonatomic,assign) NSInteger maxAutoLoginRetryTimes;
@end
上层会收到 - (void)onAutoLoginFailed:(NSError *)error
回调, 这个回调只有当自动重连发生严重错误,无法进行重试,或者超过重试次数时,才会抛出。 开发者应该返回至登录界面让用户重新手动登录。
账号信息获取
在手动登录成功后或是使用自动登录后,我们都可以通过如下接口获取用户云信 id:
objcNSString *userID = [NIMSDK sharedSDK].loginManager.currentAccount;
在 userID
不为空的情况下,意味着当前 SDK 已经正确打开对应用户资料,后续可以使用其他管理类获取相应的缓存信息,如最近联系人,消息列表等。
特殊错误码介绍
在登录过程中,开发者需要重点关心以下几个错误码 (NIMRemoteErrorDomain):
-
302
302 错误码一般为用户的账号或 token 无效导致, token 错误或者账号不存在都会导致 302 错误码。这种情况一般发生于用户在其他设备上修改了密码。
-
408
408 为请求超时错误,在某个时间内网络请求没有响应将会上抛此错误码,手动登录需要再次调用接口。自动登录则无需关心此错误,SDK 会自动去做重连。
-
416
416 为请求过频错误,为了防止开发者错误的调用导致服务器压力过大, SDK 做了频控限制,并有一分钟的惩罚时间,过了惩罚时间后接口可以再次正常调用。
-
417
417 错误码一般由一端登录导致自动登录失败导致。这种情况发生于非强制登录模式下已有一端在线而当前设备进行自动登录(设置为只允许一端同时登录时),出于安全方面的考虑,云信服务器判定当前端需要重新手动输入用户密码进行登录,故拒绝登录。
一旦发生如上情况,APP 同样需要进行注销并切换到登录界面。
登出
应用层登出/注销自己的账号时需要调用 SDK 的登出操作,该操作会通知云信服务器进行 APNs 推送信息的解绑操作,避免用户已登出但推送依然发送到当前设备的情况发生。
objc@protocol NIMLoginManager <NSObject>
- (void)logout:(nullable NIMLoginHandler)completion;
@end
考虑到用户体验,登出的超时时间会比其他请求短一些。上层应用不管登出请求是否成功,UI 表现上都应该做出登出行为。
示例:
objc[[[NIMSDK sharedSDK] loginManager] logout:^(NSError *error) {
//jump to login page
}];
- 登出失败
如果遇到登出失败,开发者仍然应该跳转到登录界面,登出失败只是云信服务器进行 APNs 推送信息的解绑失败,本地信息仍然是清理成功的,不会影响到正常业务逻辑与消息收发。
多端登录和互踢
当用户在某个客户端登录时,其他没有被踢掉的端会触发回调:
objc- (void)onMultiLoginClientsChanged;
同时,可以查询当前时间登录的设备列表:
objc- (NSArray<NIMLoginClient *> *)currentLoginClients;
云信内置踢人策略为:移动端(Android,iOS)互踢,桌面端(PC,Web)互踢,移动端和桌面端共存。
如果当前的互踢策略无法满足业务需求的话,可以联系我们取消内置互踢,根据多端登录的回调和当前的设备列表,判断本设备是否需要被踢出。如果需要踢出,直接调用登出接口并在界面上给出相关提示即可。
被踢的回调
objc-(void)onKick:(NIMKickReason)code
clientType:(NIMLoginClientType)clientType
APP收到被踢回调后需要进行注销并切换到登录界面。
登录与用户信息同步
NIM SDK 的登录一共有大约十个步骤,包括正在连接,连接成功,正在登录等。详见 NIMLoginStep 枚举。其中重要的两个步骤为:登录成功 (NIMLoginStepLoginOK) 和 同步成功 (NIMLoginStepSyncOK)。
- 登录成功 SDK 已成功登录,获取到基本信息,并开始同步数据
- 同步成功 SDK 已同步完成所有 IM 信息
NIM SDK 在登录后会同步群信息,离线消息,漫游消息,系统通知等数据。