IM 即时通讯
Android
开发指南

自定义系统通知收发

更新时间: 2024/01/03 10:34:57

NIM SDK 支持自定义系统通知的收发,帮助您快速实现多样化的业务场景。

本文介绍通过网易云信 NIM SDK 实现自定义系统通知的技术原理、具体的实现流程以及典型的应用场景。

技术原理

NIM SDK 提供自定义系统通知,其对应的数据结构为 CustomNotification(支持自定义配置项)。自定义系统通知既可以由客户端发起,也可以由开发者服务器发起。SDK 仅透传自定义系统通知,不负责解析和存储。通知内容由第三方 APP 自由扩展。

发送自定义系统通知没有重试机制,即如果 2 分钟内没有收到服务器的 ACK,SDK 直接上报发送失败。需要开发者自行实现重试。

开发者可以根据其业务逻辑自定义一些事件状态的通知,来实现各种业务场景。例如实现单聊场景中的对方“正在输入”的功能。

NIM SDK 通过 MsgServiceObserve接口中的observeCustomNotification 方法监听自定义系统通知回调; MsgService 接口中的 sendCustomNotification 方法发送自定义系统通知。

实现流程

uml diagram
  1. 通过调用observeCustomNotification 方法监听自定义系统通知接收回调。

若自定义的系统通知需要作用于全局,不依赖某个特定的 Activity,那么需要提前在 Application 的 onCreate 中调用该监听接口。

示例代码如下:

NIMClient.getService(MsgServiceObserve.class).observeCustomNotification(new Observer<CustomNotification>() {
    @Override
    public void onEvent(CustomNotification message) {
        // 处理自定义系统通知。
    }
}, register);
  1. 根据自定义系统通知的数据结构 CustomNotification 构造自定义系统通知并配置扩展信息。

CustomNotification 重要接口说明:

返回值类型 方法 说明
void setSessionId(String sessionId) 设置通知对象ID
void setSessionType(SessionTypeEnum sessionType) 设置会话类型
void setContent(String content) 设置通知内容
void setSendToOnlineUserOnly(boolean sendToOnlineUserOnly) 设置该通知是否只发送给当前在线的用户/群组
void setConfig(CustomNotificationConfig config) 设置自定义通知的配置选项,主要设置是否推送、是否计入未读数
void setApnsText(String apnsText) 设置推送文案
void setPushPayload(Map pushPayload) 设置第三方自定义的推送属性

CustomNotificationConfig 配置项说明:

属性 说明
enablePush 是否进行推送,业务方可以根据此配置进行推送。
默认为 true
enablePushNick 是否需要推送昵称,业务方进行推送时决定是否显示推送昵称。
默认为 false
enableUnreadCount 是否要计入未读数,
如果为true,那么对方收到通知后,可以通过读取此配置项决定自己业务的未读计数变更。
默认为 true

示例代码:

// 构造自定义通知,指定接收者
CustomNotification notification = new CustomNotification();
notification.setSessionId(receiverId);
notification.setSessionType(sessionType);

// 构建通知的具体内容。为了可扩展性,这里采用 json 格式,以 "id" 作为类型区分。
JSONObject json = new JSONObject();
json.put("id", "2");
JSONObject data = new JSONObject();
data.put("body", "the_content_for_display");
data.put("url", "url_of_the_game_or_anything_else");
json.put("data", data);
notification.setContent(json.toString());

// 若接收者不在线,则当其再次上线时,将收到该自定义系统通知。若设置为 true,则再次上线时,将收不到该通知。
notification.setSendToOnlineUserOnly(false);

// 配置 CustomNotificationConfig
CustomNotificationConfig config = new CustomNotificationConfig();
// 需要推送
config.enablePush = true; 
config.enableUnreadCount = true;
notification.setConfig(config);

// 设置的推送文案
notification.setApnsText("the_content_for_apns");

// 自定义推送属性
Map<String,Object> pushPayload = new HashMap<>();
pushPayload.put("key1", "payload 1");
pushPayload.put("key2", 2015);
notification.setPushPayload(pushPayload);
  1. 通过调用sendCustomNotification 方法发送自定义系统通知。示例代码如下:
NIMClient.getService(MsgService.class).sendCustomNotification(notification);

一秒内默认最多调用该接口 100 次。如需上调上限,请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

  1. 触发回调,收到自定义系统通知。

API 参考

API
说明
observeCustomNotification 监听自定义系统通知接收事件
sendCustomNotification 发送自定义系统通知
此文档是否对你有帮助?
有帮助
去反馈
  • 技术原理
  • 实现流程
  • API 参考