圈组支持接收方在个人使用的多个维度（设备、圈组服务器和频道）配置需要接收的推送消息类型，也支持发送方在发消息或自定义系统通知时决定该消息或系统通知是否需要推送并配置推送文案。

NIM SDK 的QChatPushService类提供了设备维度的圈组推送服务接口，QChatServerService类提供圈组服务器维度的推送配置方法，QChatChannelService类提供频道维度的推送配置方法。

功能介绍

圈组根据消息优先级和推送范围的大小确定消息是否离线推送，具体推送机制见下图。

上图中，推送消息被分为高中低优先级三种类型：

• 高优先级消息：@指定人（有具体目标、有@意愿）。对于被@的用户而言，该消息为高优消息。
• 中优先级消息：@所有人、@指定身份组（没有具体目标、有@意愿）。
• 低优先级消息：普通消息（没有具体目标、没有@意愿）。

消息优先级基于消息接收者判断。如某消息@A用户，那么对于A用户来说该消息为高优消息，而对于除A外的其他圈组服务器成员而言，该消息为低优消息（普通消息）。

NIM SDK 支持通过QChatPushMsgType枚举配置需要接收的推送消息类型，具体枚举值如下：

枚举值	说明
all	接收全部类型的推送消息
highLevel	只接收高优先级的推送消息
highMidLevel	只接收高优先级和中优先级的推送消息
inherit	继承用户个人使用的上一个维度的推送消息类型配置，具体维度从上到下为设备维度、服务器维度和频道维度。例如，如果设备维度的推送消息类型设置为all的情况下，服务器维度的推送消息类型设置为inherit，那么服务器维度的推送消息类型实际也为all，即接收全部类型的推送消息
none	全部推送消息都不接收

推送消息类型可在用户个人使用的不同维度配置，包括设备维度、服务器维度和频道维度。

• 如果多个维度同时配置了推送消息类型，最终接收方能够收到的推送消息类型取决于维度的优先级。

  不同维度的优先级为频道>服务器>设备。最终实际生效的推送消息类型，为 最高优维度 的配置。

• 圈组在设备维度的推送消息类型默认为“接收全部类型的推送消息”（all），在其他维度的推送消息类型默认为“继承上一维度的推送消息类型配置”（inherit)。具体的“继承”示例，可参见本文末尾的常见问题。

• 服务器成员数大于或等于 2000 人阈值时，即使接收方将推送消息类型设置为“接收全部类型的消息推送”(all)，也无法收到低优先级消息的离线推送。
• 如果接收方离线而且消息不走推送，接收方可通过查询历史消息的方式获取离线消息。

前提条件

在实现圈组的离线推送前，请确保：

• 已了解消息被推送前的流转过程，具体见图解圈组消息流转。
• 已在初始化 SDK 时完成第三方推送相关基础配置，包括：
  • 推送渠道的选择
  • 各第三方推送的相关配置（如添加推送证书名），具体请参见小米推送、华为推送、VIVO 推送、OPPO 推送、魅族推送或谷歌推送。

实现圈组消息推送

实现圈组消息推送的流程如下图所示。

下图可能因为网络问题而显示异常。如显示异常，一般刷新当前页面即可正常显示。

步骤1：接收方开启第三方推送服务

接收方确认未关闭圈组的第三方推送服务（仅限 Android）。该服务默认开启。

如需关闭，接收方可调用enableAndroid方法关闭。

dartNimCore.instance.qChatPushService.enableAndroid(true).then((value) {
  if (value.isSuccess) {
    // 开启圈组推送成功
  } else {
    // 开启圈组推送失败
  }
});

步骤2：接收方配置圈组推送选项

接收方开启圈组的第三方推送服务后，还可按需配置其他选项，包括推送免打扰、不展示推送文案详情、需要接收的推送消息类型等。

圈组推送配置

调用setPushConfig方法配置圈组是否开启推送免打扰（若开启，默认免打扰时段为 22：00-08：00，可修改）、是否不显示推送文案详情以及设备维度（即当前设备）需要接收的推送消息类型。

• 如果不展示推送文案详情，默认的推送文案为“你收到一条新消息”。
• 设备维度的推送消息类型，默认为all，即“接收圈组所有的离线消息推送”。

示例代码如下：

dartfinal param = QChatPushConfig(
  isPushShowNoDetail: false,
  isNoDisturbOpen: true,
  startNoDisturbTime: '00:00',
  stopNoDisturbTime: '08:30',
  pushMsgType: QChatPushMsgType.all);
NimCore.instance.qChatPushService.setPushConfig(param).then((value) {
  if (value.isSuccess) {
    // 设置圈组推送配置成功
  } else {
    // 设置圈组推送配置失败
  }
});

服务器维度的推送消息类型

调用updateUserServerPushConfig方法更新用户个人在某个服务器下需要接收的推送消息类型。

• 服务器维度的推送消息类型默认为inherit，即继承设备维度的推送消息类型配置。
• 具体的更新配置示例，参见本文末尾的常见问题。

示例代码如下：

dartfinal param = QChatUpdateUserServerPushConfigParam(serverId, QChatPushMsgType.all);
NimCore.instance.qChatServerService.updateUserServerPushConfig(param).then((value) {
  if (value.isSuccess) {
    // 操作成功
  } else {
    // 操作失败
  }
});

频道维度的推送消息类型

调用updateUserChannelPushConfig方法更新用户个人在某个频道下需要接收的推送消息类型。

• 频道维度的推送消息类型默认为inherit，即继承设备维度的推送消息类型配置。
• 具体的更新配置示例，参见本文末尾的常见问题。

示例代码如下：

dartfinal param = QChatUpdateUserChannelPushConfigParam(
  serverId: serverId,
  channelId: channelId,
  pushMsgType: QChatPushMsgType.all);
NimCore.instance.qChatChannelService.updateUserChannelPushConfig(param).then((value) {
  if (value.isSuccess) {
    // 操作成功
  } else {
    // 操作失败
  }
});

步骤3：发送方发消息时配置推送

发送方在调用sendMessage方法发送某条消息时，或调用sendSystemNotification方法发送自定义系统通知时，确认入参pushEnable设置为 true，即该消息需要在接收方离线的情况下推送给接收方。

pushEnable默认为 true，即圈组的消息默认需要推送。

用户发送消息或自定义系统通知时还可进行如下配置：

参数	说明
needPushNick	是否需要推送昵称，默认为用户昵称
pushContent	设置推送文案，长度限制 500 字符，消息撤回时该字段无效
pushPayload	设置推送的 payload，长度限制 2000 字符。消息撤回时该字段无效。可通过设置消息体的 payload 实现点击推送通知栏跳转至目标界面（相关说明可参考推送通知栏跳转）

获取圈组推送配置

接收方配置了上文的圈组推送选项后，在其他设备端登录时，可按需调用如下方法获取相应的配置。

获取是否已开启第三方推送

调用isEnableAndroid方法，判断是否已经开启了圈组的 Android 第三方推送服务。

获取圈组推送配置

调用getPushConfig方法获取圈组的推送配置，包括是否开启推送免打扰、是否不展示推送文案详情和设备维度的推送消息类型。

dartNimCore.instance.qChatPushService.getPushConfig().then((value) {
  if (value.isSuccess) {
    // 获取圈组推送配置成功
    var config = value.data;
  } else {
    // 获取圈组推送配置失败
  }
});

获取服务器维度的推送配置列表

调用getUserServerPushConfigs方法查询多个服务器的推送配置列表。

单次调用最多可传入 10 个服务器 ID 进行查询。

示例代码如下：

dartfinal serverIdList = getServerIdList();
final param = QChatGetUserServerPushConfigsParam(serverIdList);
NimCore.instance.qChatServerService.getUserServerPushConfigs(param).then((value) {
  if (value.isSuccess) {
    // 操作成功
    var userPushConfigs = value.data?.userPushConfigs;
  } else {
    // 操作失败
  }
});

获取频道维度的推送配置列表

调用getUserChannelPushConfigs获取多个频道的推送配置列表。

单次调用最多可传入 10 个频道 ID 进行查询。

示例代码如下：

dartfinal channelIdInfos = getChannelIdInfos();
final param = QChatGetUserChannelPushConfigsParam(channelIdInfos);
NimCore.instance.qChatChannelService.getUserChannelPushConfigs(param).then((value) {
  if (value.isSuccess) {
    // 操作成功
    var userPushConfigs = value.data?.userPushConfigs;
  } else {
    // 操作失败
  }
});

常见问题

1. 如何实现不接收某个服务器的离线消息推送？

调用updateUserServerPushConfig方法时，通过serverId指定需要静默的服务器的 ID，并将pushMsgType设置为none。调用成功后，该用户将不再接收指定服务器的离线消息推送。

2. 如何实现只接收某个服务器的高优离线消息推送？

用户首次配置圈组的离线消息推送时，按照如下步骤配置即可：

1. 调用setPushConfig方法更新设备维度的推送配置，调用时将pushMsgType设置为none。

   本步骤完成后，用户个人使用的设备维度和服务器维度的推送消息类型配置，具体如下：

   用户个人使用的维度	推送消息类型	实际生效	说明
   设备	none	none	当前设备不接收圈组内所有推送消息
   服务器	默认为inherit	none	继承设备维度的配置，即“不接收服务器维度的所有推送消息”

2. 调用updateUserServerPushConfig方法更新服务器的推送消息配置，调用时完成如下配置：

   参数	说明
   serverId	指定服务器的 ID，假设此处指定的服务器为服务器A
   pushMsgType	设置为highLevel

   本步骤完成后，用户个人使用的设备维度和服务器维度的推送消息类型配置，具体如下：

   用户个人使用的维度	推送消息类型	实际生效	说明
   设备	none	none	当前设备不接收圈组内所有推送消息
   其他服务器	仍为inherit	NONE	继承设备维度的配置，即“不接收服务器维度的所有推送消息”
   服务器A	highLevel	highLevel	只接收服务器A 内的“@消息”等高优先级的推送消息

3. 如何实现不接收某个频道的离线消息推送？

调用updateUserChannelPushConfig方法，调用时通过serverId指定频道所属的服务器的ID，并将pushMsgType设置为NONE。调用成功后，该用户将不再接收指定频道的所有离线消息推送。

4. 如何实现只接收某个频道的高优先级离线消息推送？

用户首次配置圈组的离线消息推送时，按照如下步骤配置即可：

1. 调用setPushConfig方法更新设备维度的推送消息类型配置，调用时将pushMsgType设置为NONE。

   本步骤完成后，用户个人使用的各个维度的推送消息类型配置，具体如下：

   用户个人使用的维度	推送消息类型	实际生效	说明
   设备	none	none	当前设备不接收圈组内所有推送消息
   服务器	默认为inherit	none	继承设备维度的配置，即在频道所属的服务器“不接收所有推送消息”
   频道分组	默认为inherit	none	继承服务器维度的配置，即在频道所属的频道分组“不接收所有推送消息”
   频道	默认为inherit	none	继承频道分组维度的配置，即在频道“不接收所有推送消息” 如果无频道分组，则将直接继承服务器维度的配置。

2. 调用updateUserChannelPushConfig方法，调用时完成如下配置：

   参数	说明
   serverId	指定频道所属的服务器的 ID
   channelId	指定需要接收高优推送消息的频道的 ID，假设此处指定的为频道A
   pushMsgType	设置为highLevel

   本步骤完成后，用户个人使用的各个维度的推送消息类型配置，将如下表所示：

   用户个人使用的维度	推送消息类型	实际生效	说明
   设备	none	none	当前设备不接收圈组内所有推送消息
   服务器	仍为inherit	none	继承设备维度的配置，即在频道所属的服务器“不接收所有推送消息”
   频道分组	仍为inherit	none	继承服务器维度的配置，即在频道所属的频道分组“不接收所有推送消息”
   频道A	highLevel	highLevel	只接收频道A 内的“@消息”等高优先级的推送消息
   服务器的其他频道	仍为inherit	none	继承服务器维度的配置，即“不接收频道内所有推送消息”