登录


在使用 SDK 之前,需要对云信的体系流程有基本的认知,推荐开发者首先阅读这里

手动登录

@protocol NIMLoginManager <NSObject>
/**
 *  登录
 *
 *  @param account    帐号
 *  @param token      令牌 (在后台绑定的登录token)
 *  @param completion 完成回调
 */
- (void)login:(NSString *)account
        token:(NSString *)token
   completion:(NIMLoginHandler)completion;
@end

示例

NSString *account = @"your account";
NSString *token   = @"your token";
[[[NIMSDK sharedSDK] loginManager] login:account
                                   token:token
                              completion:^(NSError *error) {}];

error 为登录错误信息,成功则为 nil。

在手动登录之前, APP 的本地数据为关闭状态,登录成功后即可调用查询本地数据方法,如本地好友,群组等。

SDK 不支持直接添加云信用户,请参考这里,在您的应用服务器上使用 Http 接口进行添加。

自动登录

APP 启动时,如果已保存用户名和密码可以选择调用自动登录接口,并立刻打开主界面。此时 APP 可以在无网络,未登录成功的状态下直接访问用户本地数据。此类登录需要调用如下接口:

原型

@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 的错误);强制模式下的自动登录,服务器将不检查当前登录设备是否为上一次登录设备,安全性较低,但较为便捷。

示例

NIMAutoLoginData *loginData = [[NIMAutoLoginData alloc] init];
loginData.account = account;
loginData.token = token;

[[[NIMSDK sharedSDK] loginManager] autoLogin:loginData];

和手动登录不同,自动登录在失败后会自动重试登录,并通过委托通知登录状态。 APP 需要实现如下回调 (手动登录也会收到同样的委托回调)

@protocol NIMLoginManagerDelegate <NSObject>
/**
 *  登录回调
 *
 *  @param step 登录步骤
 *  @discussion 这个回调主要用于客户端UI的刷新
 */
- (void)onLogin:(NIMLoginStep)step
@end

NIMLoginStep 枚举列表

说明
NIMLoginStepLinking 连接服务器
NIMLoginStepLinkOK 连接服务器成功
NIMLoginStepLinkFailed 连接服务器失败
NIMLoginStepLogining 登录
NIMLoginStepLoginOK 登录成功
NIMLoginStepLoginFailed 登录失败
NIMLoginStepSyncing 开始同步数据
NIMLoginStepSyncOK 同步数据完成
NIMLoginStepLoseConnection 连接断开
NIMLoginStepNetChanged 网络切换

一次完整的登录的基本步骤为

- (void)onAutoLoginFailed:(NSError *)error

自动登录除了会触发相应步骤变化回调外,在发生错误时也会触发如上回调。在碰到一些 SDK 无法自动解决的错误时,开发者需要在此回调里做出相应的处理。

举例来说,当前网络状态较差时,容易导致自动登录发生网络超时错误,此时上层无需处理,SDK 会持续有策略地重连。重连详情请参考这里

而一旦发生用户名密码不匹配的错误时,则需要上层做出相应处理:登出并提示用户手动登录或是从自己的应用服务器刷新相应的用户名密码。一些特殊的登录错误将在下文列出,建议在集成时能尽可能考虑相应应对逻辑。

自动重连机制

SDK 提供了自动重连机制(重新建立与网易云通信服务器的连接并重新登录),所有重连和登录状态都会在上述的 - (void)onLogin:(NIMLoginStep)step 方法中回调。

SDK 在两种场景下会自动进行重连:

  1. 用户在 APP 启动之后调用过云信自动登录方法。
  2. 用户在 APP 启动之后调用过手动登录方法,并登录成功。

满足上述中一个条件,当用户遇到普通网络问题如连接超时,后台返回到前台等,会自动进行重连登录,不需要上层开发者去做额外的重登逻辑

一些严重错误,如账号被踢出、账号被封禁,SDK 不会进行自动重连;重试次数超过预定上限时, SDK 也不会继续重连。

重试次数在 NIMSDKConfig 中定义,默认为 0 ,为无次数限制重试。

原型

@interface NIMSDKConfig : NSObject
/**
 *  自动登录重试次数
 *  @discusssion 默认为 0。即默认情况下,自动登录将无限重试。设置成大于 0 的值后,在没有登录成功前,自动登录将重试最多 maxAutoLoginRetryTimes 次,如果失败,则抛出错误 (NIMLocalErrorCodeAutoLoginRetryLimit)。
 */
@property (nonatomic,assign)    NSInteger   maxAutoLoginRetryTimes;
@end

上层会收到 - (void)onAutoLoginFailed:(NSError *)error 回调, 这个回调只有当自动重连发生严重错误,无法进行重试,或者超过重试次数时,才会抛出。 开发者应该返回至登录界面让用户重新手动登录。

账号信息获取

在手动登录成功后或是使用自动登录后,我们都可以通过如下接口获取用户云信 id:

NSString *userID = [NIMSDK sharedSDK].loginManager.currentAccount;

userID 不为空的情况下,意味着当前 SDK 已经正确打开对应用户资料,后续可以使用其他管理类获取相应的缓存信息,如最近联系人,消息列表等。

特殊错误码介绍

在登录过程中,开发者需要重点关心以下几个错误码 (NIMRemoteErrorDomain):

登出

应用层登出/注销自己的账号时需要调用 SDK 的登出操作,该操作会通知云信服务器进行 APNs 推送信息的解绑操作,避免用户已登出但推送依然发送到当前设备的情况发生。

@protocol NIMLoginManager <NSObject>
- (void)logout:(nullable NIMLoginHandler)completion;
@end

考虑到用户体验,登出的超时时间会比其他请求短一些。上层应用不管登出请求是否成功,UI 表现上都应该做出登出行为。

示例:

[[[NIMSDK sharedSDK] loginManager] logout:^(NSError *error) {
    //jump to login page
}];

如果遇到登出失败,开发者仍然应该跳转到登录界面,登出失败只是云信服务器进行 APNs 推送信息的解绑失败,本地信息仍然是清理成功的,不会影响到正常业务逻辑与消息收发。

多端登录和互踢

当用户在某个客户端登录时,其他没有被踢掉的端会触发回调:

- (void)onMultiLoginClientsChanged;

同时,可以查询当前时间登录的设备列表:

- (NSArray<NIMLoginClient *> *)currentLoginClients;

云信内置踢人策略为:移动端(Android,iOS)互踢,桌面端(PC,Web)互踢,移动端和桌面端共存。

如果当前的互踢策略无法满足业务需求的话,可以联系我们取消内置互踢,根据多端登录的回调和当前的设备列表,判断本设备是否需要被踢出。如果需要踢出,直接调用登出接口并在界面上给出相关提示即可。

被踢的回调

-(void)onKick:(NIMKickReason)code 
   clientType:(NIMLoginClientType)clientType

APP收到被踢回调后需要进行注销并切换到登录界面。

登录与用户信息同步

NIM SDK 的登录一共有大约十个步骤,包括正在连接,连接成功,正在登录等。详见 NIMLoginStep 枚举。其中重要的两个步骤为:登录成功 (NIMLoginStepLoginOK) 和 同步成功 (NIMLoginStepSyncOK)。

NIM SDK 在登录后会同步群信息,离线消息,漫游消息,系统通知等数据。