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

前提条件

登录圈组前，请确保您已经完成以下操作：

• 开通和配置圈组功能。
• SDK 初始化。
• 登录 IM。

登录圈组

第一步：注册监听

1. 注册圈组登录状态监听（observeStatusChange），监听圈组登录状态变化事件（QChatStatusChangeEvent）。SDK 在该事件中返回当前的状态码 StatusCode，其中 StatusCode 说明请参考本文末尾的 圈组登录状态变化流程。

2. 注册多端登录状态监听（observeMultiSpotLogin），监听圈组的多端登录事件（QChatMultiSpotLoginEvent）。

   单击展开查看 QChatMultiSpotLoginEvent 的参数说明。

   返回值	参数	说明
   QChatMultiSpotNotifyType	getNotifyType	获取多点登录通知类型 QCHAT_IN：通知其他端当前端已上线 QCHAT_OUT：通知其他在线端当前端已下线
   QChatClient	getOtherClient	获取其他端信息

3. 注册被踢出圈组监听（observeKickedOut），监听 被同时登录圈组的其他端踢下线 的事件（QChatKickedOutEvent）。

   单击展开查看 QChatKickedOutEvent 的参数说明。

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

   示例代码：

   注册登录状态监听

   JavaNIMClient.getService(QChatServiceObserver.class).observeStatusChange(new Observer<QChatStatusChangeEvent>() {
      @Override
      public void onEvent(QChatStatusChangeEvent qChatStatusChangeEvent) {
         //当前状态
         StatusCode status = qChatStatusChangeEvent.getStatus();
      }
   },true);
   

   注册多端登录状态监听

   Java//注册多端登录状态监听
   NIMClient.getService(QChatServiceObserver.class).observeMultiSpotLogin(new Observer<QChatMultiSpotLoginEvent>() {
      @Override
      public void onEvent(QChatMultiSpotLoginEvent qChatMultiSpotLoginEvent) {
         //其他端信息
         QChatClient otherClient = qChatMultiSpotLoginEvent.getOtherClient();
         //多端登录通知类型
         QChatMultiSpotNotifyType notifyType = qChatMultiSpotLoginEvent.getNotifyType();
      }
   },true);
   

   注册被踢出圈组监听

   Java//注册被踢出监听
   NIMClient.getService(QChatServiceObserver.class).observeKickedOut(new Observer<QChatKickedOutEvent>() {
      @Override
      public void onEvent(QChatKickedOutEvent qChatKickedOutEvent) {
         //被踢出
      }
   },true);
   

第二步：手动登录

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

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

• 示例代码

  JavaQChatLoginParam 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 登出不一样，该方法有异步回调。

多端登录管控

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

方式一：通过控制台管控

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

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

方式一：通过接口管控

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

示例代码：

JavaQChatKickOtherClientsParam 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 事件。收到该事件回调后，建议进行注销并切换到登录界面。

登录状态变化

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

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

登录状态（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 错误等情况。如自动登录失败，需要返回到登录界面进行重新登录操作）