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

前提条件

• 已开通圈组功能。
  可在云信控制台开通“圈组功能”

  在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组即可配置。
  
• 已了解什么是圈组。
• 已完成 SDK 初始化且已登录 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方法手动登录圈组。

• 示例代码

  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方法即可登出圈组。

登录相关机制与策略

多端登录与互踢

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

方式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) {
            // 踢出其他端错误
         }
      });

登录状态变化流程

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