免打扰功能概述
「免打扰功能」用于控制用户在客户端设备离线时,是否可针对离线消息接收推送通知。
- 客户端为离线状态:会话中有新离线消息时,用户默认通过推送通道收到消息且默认弹出通知。设置免打扰后,融云服务端不会为相关消息触发推送。
- 客户端在后台运行:会话中有新消息时,用户直接收到消息。如果使用 IMLib,您需要自行判断 App 是否在后台运行,并根据业务需求自行实现本地通知弹窗。
如果不需要接收推送,可以通过设置 SDK 的初始化配置中的 enablePush
参数为 false
,向融云服务申请禁用推送服务(当前设备)。您也可以在断开连接时设置不接收推送(当前设备)。
免打扰设置维度
客户端 SDK 支持对单聊、群聊、系统会话业务进行以下多个维度的免打扰设置:
- App 的免打扰设置
- 按指定会话类型设置免打扰级别
- 按会话设置免打扰级别
- 全局免打扰
App 的免打扰设置
以 App Key 为单位,设置整个应用所有用户的默认免打扰级别。默认未设置,等同于全部消息都接收通知。该级别的配置暂未在控制台开放,如有需要,请提交工单。
- 全部消息均通知:当前 App 下的用户可针对任何消息接收推送通知。
- 未设置:默认全部消息都通知。
- 仅 @ 消息通知:当前 App 下,仅针对提及(@)指定用户和群组全体成员的消息向离线用户发送推送通知。
- 仅 @ 指定用户通知:当前 App 下,用户仅针对提及(@)当前用户的消息接收推送通知。例如:仅张三会接收且仅接收 “@张三 Hello” 的消息的通知。
- 仅 @群全员通知: 当前 App 下,用户仅针对提及(@)群组全体成员的消息接收推送通知。
- 都不接收通知:当前 App 下,用户不针对任何消息接收推送通知,即任何离线消息都不会触发推送通知。
- 除 @ 消息外群聊消息不发推送:当前 App 下,用户针对单聊消息、提及(@)指定用户的消息、和提及(@)群组全体成员的消息接收推送通知。
融云服务端判断是否需要推送时,App 级别的免打扰配置的优先级最低。如果存在以下任何一种用户级别的免打扰配置,以用户级别配置为准:
- 按指定会话类型设置免打扰级别
- 按会话设置免打扰级别
- 全局免打扰
按会话类型设置免打扰级别
客户端 SDK 从 5.2.2.1 开始支持该功能。该功能属于用户级别设置。
客户端 SDK 提供 PushNotificationLevel
,允许用户 为会话类型(单聊、群聊、超级群、系统会话)配置触发推送通知的消息类别,或完全关闭通知。提供以下六个级别:
枚举值 | 数值 | 说明 |
---|---|---|
PUSH_NOTIFICATION_LEVEL_ALL_MESSAGE | -1 | 与融云服务端断开连接后,当前用户可针对指定类型会话中的所有消息接收通知。 |
PUSH_NOTIFICATION_LEVEL_DEFAULT | 0 | 未设置。未设置时均为此初始状态。 |
PUSH_NOTIFICATION_LEVEL_MENTION | 1 | 与融云服务端断开连接后,当前用户仅针对指定类型的会话中提及(@)当前用户和全体群成员的消息接收通知。 |
PUSH_NOTIFICATION_LEVEL_MENTION_USERS | 2 | 与融云服务端断开连接后,当前用户仅针对指定类型的会话中提及(@)当前用户的消息接收通知。例如:张三只会接收 “@张三 Hello” 的消息的通知。 |
PUSH_NOTIFICATION_LEVEL_MENTION_ALL | 4 | 与融云服务端断开连接后,当前用户仅针对指定类型的会话中提及(@)全部群成员的消息接收通知。 |
PUSH_NOTIFICATION_LEVEL_BLOCKED | 5 | 当前用户针对指定类型的会话中的任何消息都不接收推送通知。 |
具体设置方法详见按会话类型设置免打扰。
融云服务端判断是否需要为用户发送推送通知时,如果同时存在以下任何一种用户级别的免打扰配置,以下列配置为准:
- 按会话设置免打扰级别
- 全局免打扰
按会话设置免打扰级别
客户端 SDK 从 5.2.2 开始支持该功能。该功能属于用户级别设置。
客户端 SDK 提供 PushNotificationLevel
,允许用户为会话配置触发通知的消息类别,或完全关闭通知。提供以下六个级别:
枚举值 | 数值 | 说明 |
---|---|---|
PUSH_NOTIFICATION_LEVEL_ALL_MESSAGE | -1 | 与融云服务端断开连接后,当前用户可针对指定类型会话中的所有消息接收通知。 |
PUSH_NOTIFICATION_LEVEL_DEFAULT | 0 | 未设置。未设置时均为此初始状态。 |
PUSH_NOTIFICATION_LEVEL_MENTION | 1 | 与融云服务端断开连接后,当前用户仅针对指定会话中提及(@)当前用户和全体群成员的消息接收通知。 |
PUSH_NOTIFICATION_LEVEL_MENTION_USERS | 2 | 与融云服务端断开连接后,当前用户仅针对接收指定会话中提及(@)当前用户的消息接收通知。例如:张三只会接收 “@张三 Hello” 的消息的通知。 |
PUSH_NOTIFICATION_LEVEL_MENTION_ALL | 4 | 与融云服务端断开连接后,当前用户仅针对指定会话中提及(@)全部群成员的消息接收通知。 |
PUSH_NOTIFICATION_LEVEL_BLOCKED | 5 | 当前用户针对指定会话中的任何消息都不接收推送通知。 |
具体设置方法详见按会话设置免打扰。
融云服务端判断是否需要为用户发送推送通知时,如果该用户已配置全局免打扰,则已全局免打扰的配置细节为准。
全局免打扰
客户端 SDK 从 5.2.2 开始提供 PushNotificationQuietHoursLevel
,允许用户配置何时接收通知以及触发通知的消息类别。 提供了以下三个级别:
枚举值 | 数值 | 说明 |
---|---|---|
PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_DEFAULT | 0 | 未设置。如未设置,SDK 会依次查询消息所属群的用户级别免打扰设置及其他非用户级别设置,再判断是否需要推送通知。 |
PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_MENTION_MESSAGE | 1 | 与融云服务端断开连接后,当前用户仅在指定时段内针对指定会话中提及(@)当前用户和全体群成员的消息接收通知。 |
PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_BLOCKED | 5 | 当前用户在指定时段内针对任何消息都不接收推送通知。 |
具体设置方法详见全局免打扰。
早于 5.2.2 的 SDK 版本不支持设置触发通知的消息类别,仅支持设置为接收或不接收推送通知。
免打扰设置的优先级
针对单聊、群聊、系统会话、融云服务端会遵照以下顺序搜索免打扰配置。优先级从左至右依次降低,以优先级最高的配置为准判断是否需要触发推送:
全局免打扰设置(用户级) > 指定会话类型的免打扰设置(用户级) > 指定会话的免打扰设置(用户级) > App 级的免打扰设置
API 接口列表
下表描述了适用于单聊、群聊、系统会话的免打扰配置 API 接口。
免打扰配置维度 | 客户端 API | 服务端 API |
---|---|---|
设置指定时段内,应用全局的免打扰级别。 | 详见全局免打扰。 | 详见 设置用户免打扰时段 |
设置指定类型会话的免打扰级别 | 详见按会话类型设置免打扰。 | 详见设置会话类型免打扰。 |
设置指定会话的免打扰级别 | 详见按会话设置免打扰。 | 详见设置会话免打扰。 |
设置 App 级免打扰级别 | 客户端 SDK 不提供 API。 | 服务端不提供该 API。 |