实现在线消息提醒
更新时间: 2024/08/05 15:06:18
云信 NIM SDK 提供内置的消息提醒功能,该功能与离线推送功能相互独立,可单独使用。
使用场景
当应用进程在存活的情况下,应用退后台或者收到非当前会话的消息会触发消息提醒。消息提醒作用的场景与推送不同,一般对即时通讯的场景来说,主要作用在:
-
APP 处于后台,且 SDK 进程未被清理时
-
在前台与用户 A 聊天,但收到其他用户(非用户 A )的发来的消息时
-
在非聊天界面且非最近会话列表界面时
以下场景一般不需要消息提醒:
-
如果用户正处于聊天界面,且收到当前会话的消息
-
如果用户停留在最近联系人列表界面,收到消息也不应该有消息提醒(但会有未读数变更通知)
实现消息提醒
SDK 通过初始化参数 SDKOptions.statusBarNotificationConfig
来控制通知栏消息提醒功能,默认为 null,即 SDK 不提供通知栏提醒功能,由客户 APP 自行实现。
-
在 初始化 时,配置
SDKOptions.statusBarNotificationConfig
参数,即 SDK 提供通知栏提醒功能。statusBarNotificationConfig
参数详情请参考 通知栏消息提醒配置项参考。示例代码如下:StatusBarNotificationConfig config = new StatusBarNotificationConfig(); // 点击通知需要跳转到的界面 config.notificationEntrance = WelcomeActivity.class; // 通知铃声的uri字符串 config.notificationSound = "raw/msg"; config.notificationFolded = true; config.notificationFoldStyle = NotificationFoldStyle.ALL; config.downTimeEnableNotification = true; // 呼吸灯配置 config.ledARGB = Color.GREEN; config.ledOnMs = 1000; config.ledOffMs = 1500; // 是否APP ICON显示未读数红点(Android O有效) config.showBadge = true; config.notificationFilter = new StatusBarNotificationFilter() { @Override public FilterPolicy apply(IMMessage imMessage) { return FilterPolicy.PERMIT; } }; options.statusBarNotificationConfig = config;
-
(可选)开启/关闭通知栏消息提醒功能。SDK 默认开启通知栏消息提醒功能,不需要单独调用
toggleNotification
方法开启。但是如果主动关闭过消息提醒功能,则需要单独调用该接口重新开启。示例代码如下:NIMClient.toggleNotification(true);
- SDK 默认开启撤回消息操作的通知栏提醒,如需关闭,可通过
toggleRevokeMessageNotification
方法实现。 - 只有
statusBarNotificationConfig
配置不为空时,toggleNotification
和toggleRevokeMessageNotification
方法才有效。
- SDK 默认开启撤回消息操作的通知栏提醒,如需关闭,可通过
-
(可选)启用通知栏消息提醒后,需要依据当前页面环境动态调整是否需要消息提醒。此处,需要结合未读数相关接口进行处理:
-
进入聊天界面,调用
setChattingAccount
方法设置当前正在聊天的对象(account)。设置后会影响内置的消息提醒。如果有新消息到达,且消息来源是正在聊天的对象(account),将不会有消息提醒。 -
进入最近联系人列表界面,同样调用
setChattingAccount
方法设置所有消息无需进行消息提醒。 -
退出聊天界面或离开最近联系人列表界面,调用
setChattingAccount
方法设置所有消息都进行消息提醒。
示例代码如下:
java
// 进入聊天界面,建议放在 onResume 中,表示来自 account 的消息无需进行消息提醒。 NIMClient.getService(MsgService.class).setChattingAccount(account, sessionType); // 进入最近联系人列表界面,建议放在onResume中。表示所有消息无需进行消息提醒。 NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_ALL, SessionTypeEnum.None); // 退出聊天界面或离开最近联系人列表界面,建议放在onPause中。表示所有消息都可以进行消息提醒。 NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);
-
-
(可选)后续若需要修改通知栏消息提醒配置,可通过
updateStatusBarNotificationConfig
方法进行更新。具体请参考 配置消息提醒功能。
通知栏消息提醒配置项参考
StatusBarNotificationConfig 参数 | 说明 |
---|---|
notificationSmallIconId | 通知栏提醒的小图标的资源ID。如果不提供,使用 app 的 icon |
ring | 是否需要响铃提醒,默认为 true |
notificationSound | 响铃提醒的声音资源,如果不提供,使用系统默认提示音 |
vibrate | 是否需要振动提醒,默认为 true |
ledARGB | 呼吸灯的颜色 建议尽量使用绿色、蓝色、红色等基本颜色,避免使用混合色 |
ledOnMs | 呼吸灯亮时的持续时间(毫秒) |
ledOffMs | 呼吸灯熄灭时的持续时间(毫秒) |
hideContent | 不显示消息详情开关,同时也不再显示消息发送者昵称。默认为 false |
downTimeToggle | 免打扰设置开关,默认为关闭 |
downTimeBegin | 免打扰的开始时间,格式为 HH:mm (24小时制) |
downTimeEnd | 免打扰的结束时间,格式为 HH:mm(24小时制) 如果结束时间小于开始时间,免打扰时间为开始时间-24:00-结束时间 |
notificationEntrance | 通知栏提醒的响应 intent 的 activity 类型,通过配置该参数实现消息提醒通知栏的跳转 若为 null,将使用包的 launcher 的入口 intent 的 activity |
titleOnlyShowAppName | 通知栏提醒的标题是否只显示应用名,默认 false
|
notificationColor | 消息通知栏颜色,将应用到 NotificationCompat.Builder 的 setColor 方法 |
downTimeEnableNotification | 免打扰期间,是否显示通知,默认为显示 |
notificationFoldStyle | 消息通知栏的折叠类型:
|
notificationExtraType | 点击在线通知的通知栏传递的 extra 类型
|
showBadge | APP 图标是否显示未读数(红点) |
customTitleWhenTeamNameEmpty | 通知栏标题,如果群名称为 null 或者空串,则使用该字段作为通知栏 title |
notificationFilter | 弹出通知之前,SDK 通过该接口询问 App,根据 App 返回结果决定是否弹出通知,为空等同于返回 DEFAULT,默认 null |
postNotificationsRequester | Android13 弹出通知之前,SDK 通过该接口向 App 请求权限 Manifest.permission#POST_NOTIFICATIONS,根据权限赋予结果决定是否弹出通知 |