IM 即时通讯
Android
开发指南

登录管理

更新时间: 2023/09/22 11:47:55

圈组是网易云信开发的类 Discord 场景能力模块。在使用圈组的相关能力前,需要先登录圈组。

前提条件

登录圈组前,请确保:

登录圈组前,必须先登录 IM。否则将无法成功登录圈组。

实现流程

本节介绍圈组登录与登出的实现流程。

登录圈组

步骤1:注册监听

  • 注册圈组登录状态观察者(observeStatusChange),监听圈组登录状态变化事件(QChatStatusChangeEvent)。SDK 在该事件中返回当前的状态码StatusCode,其中StatusCode说明详见本文末尾的圈组登录状态变化流程

  • 注册多端登录状态观察者(observeMultiSpotLogin),监听圈组的多端登录事件(QChatMultiSpotLoginEvent)。

    点击展开查看 QChatMultiSpotLoginEvent 的参数说明
    返回值 参数 说明
    QChatMultiSpotNotifyType getNotifyType 获取多点登陆通知类型
    • QCHAT_IN:通知其他端当前端已上线
    • QCHAT_OUT:通知其他在线端当前端已下线
    QChatClient getOtherClient 获取其他端信息
  • 注册被踢出圈组观察者(observeKickedOut),监听“被同时登录圈组的其他端踢下线”的事件(QChatKickedOutEvent)。

    点击展开查看 QChatKickedOutEvent 的参数说明
    返回值 参数 说明
    int getClientType 获取客户端类型
    QChatKickOutReason getKickReason 获取被踢原因:
    • UNKNOWN:未知(出错情况)
    • KICK_BY_SAME_PLATFORM:相同类型终端登录时被踢
    • KICK_BY_SERVER:被管理后台禁止登录
    • KICK_BY_OTHER_PLATFORM:被同时在线的其他端踢下线
    String getExtension 获取描述
    int getCustomClientType 获取自定义客户端类型

示例代码如下:

注册登录状态观察者
NIMClient.getService(QChatServiceObserver.class).observeStatusChange(new Observer<QChatStatusChangeEvent>() {
   @Override
   public void onEvent(QChatStatusChangeEvent qChatStatusChangeEvent) {
      //当前状态
      StatusCode status = qChatStatusChangeEvent.getStatus();
   }
},true);
注册多端登录状态观察者
//注册多端登录状态监听
NIMClient.getService(QChatServiceObserver.class).observeMultiSpotLogin(new Observer<QChatMultiSpotLoginEvent>() {
   @Override
   public void onEvent(QChatMultiSpotLoginEvent qChatMultiSpotLoginEvent) {
      //其他端信息
      QChatClient otherClient = qChatMultiSpotLoginEvent.getOtherClient();
      //多端登录通知类型
      QChatMultiSpotNotifyType notifyType = qChatMultiSpotLoginEvent.getNotifyType();
   }
},true);
注册被踢出圈组观察者
//注册被踢出监听
NIMClient.getService(QChatServiceObserver.class).observeKickedOut(new Observer<QChatKickedOutEvent>() {
   @Override
   public void onEvent(QChatKickedOutEvent qChatKickedOutEvent) {
      //被踢出
   }
},true);

步骤2:手动登录

调用login方法手动登录圈组。

调用该方法登录圈组时,一般无需传入参数,SDK 会直接获取并使用登录 IM 时传入的参数。

  • 示例代码

    QChatLoginParam loginParam = new QChatLoginParam();
    NIMClient.getService(QChatService.class).login(loginParam).setCallback(new RequestCallback<QChatLoginResult>() {
       @Override
       public void onSuccess(QChatLoginResult result) {
          LogUtil.i(TAG, "login success");
          // your code
       }
    
       @Override
       public void onFailed(int code) {
          LogUtil.i(TAG, "login failed");
          // your code
       }
    
       @Override
       public void onException(Throwable exception) {
          // your code
       }
    });
    
  • 参数说明

    该方法的参数结构为QChatLoginParam

    点击展开查看 QChatLoginParam 部分重要参数的说明
    返回值
    参数 说明
    String getAccount 获取用户账号
    String getAppKey 获取 app Key
    String getToken 获取用户 token
    int getAuthType 获取鉴权方式,0 或 1,默认 0,
    • 0 表示静态 Token 鉴权,即通过 accid固定token 进行鉴权登录
    • 1 表示动态 Token 鉴权,即通过accid动态token进行鉴权登录。动态token需要基于 appSecret 通过动态 Token 的约定算法计算得出
    String getLoginExt 获取登录自定义字段
    void setLoginExt(String loginExt) 设置登录自定义字段,用于提交给用户的第三方回调服务进行登录检测,不会同步给其他端
    Integer getCustomClientType 获取自定义客户端类型
    void setCustomClientType(int customClientType) 设置自定义客户端类型
    String getCustomTag 获取自定义Tag
    void setCustomTag(String customTag) 设置自定义Tag
    String getCustomPushContentType 获取自定义推送文案类型
    void setCustomPushContentType(String customPushContentType) 设置自定义推送文案类型,离线推送不显示详情时,要显示的文案对应的类型名称
  • 返回信息

    调用成功后,QChatLoginResult返回当前登录客户端信息和其他登录客户端信息列表,参数说明如下:

    返回值 参数 说明
    QChatClient getCurrentClient 获取当前登录客户端信息
    List<QChatClient> getOtherClients 获取其他登录客户端信息列表

    其中QChatClient参数说明如下:

    返回值 参数 说明
    String getOs 客户端的操作系统信息
    int getClientType 客户端类型
    long getLoginTime 登录时间
    String getClientIp 客户端 IP 地址
    String getClientPort 客户端端口
    String getDeviceId 客户端设备 ID
    String getCustomTag 自定义 Tag
    int getCustomClientType 自定义客户端类型

登出圈组

用户调用logout方法即可登出圈组。

此方法和 IM 登出不一样,该方法有异步回调:

登录相关机制与策略

多端登录与互踢

您可通过云信控制台或者接口对多端登录进行管控。

方式1:通过控制台管控

可在云信控制台配置如下多端登录与互踢策略

  • 只允许一端登录
  • 桌面端(PC 与 Web)互踢、移动端(Android 和 iOS )互踢、桌面端与移动端可同时登录。
  • 各端均可以同时登录在线(最多 10 个设备同时在线)

方式2:通过接口管控

也可调用QChatService#kickOtherClients方法,将同时登录圈组的其他设备端踢下线。

示例代码如下:

QChatKickOtherClientsParam kickOtherClientsParam = new QChatKickOtherClientsParam(deviceIdList);
NIMClient.getService(QChatService.class).kickOtherClients(kickOtherClientsParam).setCallback(
      new RequestCallback<QChatKickOtherClientsResult>() {
         @Override
         public void onSuccess(QChatKickOtherClientsResult result) {
            //被成功踢掉的客户端的deviceId列表
            List<String> clientIds = result.getClientIds();

         }

         @Override
         public void onFailed(int code) {
            // 踢出其他端失败,返回失败code
         }

         @Override
         public void onException(Throwable exception) {
            // 踢出其他端错误
         }
      });

如果已在本端注册多端登录状态观察者(observeMultiSpotLogin),当被其他端踢掉,本端会收到QChatKickedOutEvent事件。收到该事件回调后,建议进行注销并切换到登录界面。

登录状态变化流程

圈组的登录状态变化流程参见下图。图中,深蓝色元素代表登录状态,浅绿色元素代表调用login方法的手动登录。

圈组的登录状态变化流程与 IM 的基本相同,但不支持自动登录(重连)。

登录状态(StatusCode)
说明
INVALID 未定义
UNLOGIN 未登录/登录失败
NET_BROKEN 网络连接已断开
CONNECTING 正在连接云信服务端
LOGINING 正在登录中
SYNCING 正在同步数据,登录成功后开始同步
LOGINED 已成功登录
KICKOUT 被其他端的登录踢下线,此时应该跳转至手动登录界面。具体机制参见多端登录与互踢策略。被踢后,无法自动登录
KICK_BY_OTHER_CLIENT 被同时在线的其他端主动踢下线(通过kickOtherClients方法),此时应该跳转至手动登录界面。被踢后,无法自动登录
FORBIDDEN 被服务器禁止登录(云信 IM 账号被禁用)。被禁止登录后,无法自动登录
VER_ERROR SDK 版本错误。出现该登录异常后,无法自动登录
PWD_ERROR 云信 IM 账号(accid)或 Token 错误。出现该登录异常后,无法自动登录
DATA_UPGRADE 数据库需要迁移到加密状态(类似被踢出、云信 IM 账号被禁用、Token 错误等情况。如自动登录失败,需要返回到登录界面进行重新登录操作)
此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 实现流程
  • 登录圈组
  • 步骤1:注册监听
  • 步骤2:手动登录
  • 登出圈组
  • 登录相关机制与策略
  • 多端登录与互踢
  • 方式1:通过控制台管控
  • 方式2:通过接口管控
  • 登录状态变化流程