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

前提条件

登录圈组前，请确保您已完成初始化并登录 IM。

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

实现流程

登录圈组

1. 注册圈组登录状态变化事件流（onStatusChange）、多端登录状态事件流（onMultiSpotLogin）和被踢下线事件流（onKickedOut）。

   • 通过登录状态事件流，可监听圈组登录状态变化（即用户在线状态变化）。具体状态变化的流程和说明，请参见下文的登录状态变化流程。

   • 通过多端登录状态事件流，可监听其他设备端的圈组登录或注销事件。

   • 通过被踢下线事件流，可监听用户多端在线时被其中某个端主动踢下线的事件。

   示例代码如下：

   登录状态监听

   dartNimCore.instance.qChatObserver.onStatusChange.listen((event) {
     var status = event.status;
     // your code
   });
   

   多端登录监听

   dartNimCore.instance.qChatObserver.onMultiSpotLogin.listen((event) {
     // your code
   });
   

   被踢下线事件监听

   dartNimCore.instance.qChatObserver.onKickedOut.listen((event) {
     // your code
   });
   

2. 调用login方法登录圈组。

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

   
   

   示例代码如下：

   dartNimCore.instance.qChatService.login(QChatLoginParam()).then((value) {
     if (value.isSuccess) {
       print("login success.");
       // your code
     } else {
       print("login failed.");
       // your code
     }
   });
   

登出圈组

调用logout方法登出圈组。

示例代码如下：

dartNimCore.instance.qChatService.logout().then((value) {
  if (value.isSuccess) {
    print("logout success.");
  } else {
    print("logout failed.");
  }
});

登录相关机制与策略

多端登录与互踢

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

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

也可调用kickOtherClients方法，将同时登录圈组的其他客户端踢下线。

dartvar param = QChatKickOtherClientsParam(deviceIdList);
NimCore.instance.qChatService.kickOtherClients(param).then((value){
  if (value.isSuccess) {
    // 被成功踢掉的客户端的deviceId列表
    var clientIds = value.data?.clientIds;
  } else {
    // 踢出其他端失败
  }
});

如已注册多端登录状态事件流（onMultiSpotLogin），当被其他端踢掉，本端会收到 QChatKickedOutEvent 事件。收到该事件回调后，建议进行注销并切换到登录界面。

登录状态变化流程

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

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

登录状态由QChatStatusChangeEvent类的status定义，具体包含如下状态：

登录状态	说明
unknown	未知状态
unLogin	未登录/登录失败
netBroken	网络连接已断开
connecting	正在连接云信服务端
logging	正在登录中
dataSyncStart	正在同步数据，登录成功后开始同步
dataSyncFinish	数据同步完成
loggedIn	已成功登录
kickOut	被其他端的登录踢下线，此时应该跳转至手动登录界面。具体机制参见多端登录与互踢策略。被踢后，无法自动登录
kickOutByOtherClient	被同时在线的其他端主动踢下线（通过kickOtherClient方法），此时应该跳转至手动登录界面。被踢后，无法自动登录
forbidden	被服务器禁止登录（云信 IM 账号被禁用）。被禁止登录后，无法自动登录
versionError	SDK 版本错误。
pwdError	云信 IM 账号（accid）或 Token 错误。