系统通知

系统通知是网易云通信系统内建的消息/通知,其对应的数据结构为 SystemMessage。由网易云通信服务器推送给用户的通知类消息,用于网易云通信系统类的事件通知。现在主要包括群变动的相关通知,例如入群申请,入群邀请等,如果第三方应用还托管了好友关系,好友的添加、删除也是这个类型的通知。系统通知由 SDK 负责接收和存储,并提供较简单的未读数管理。

SystemMessage 接口说明:

返回值 SystemMessage 接口 说明
String getAttach() 获取系统通知的附件内容
Object getAttachObject() 获取系统通知附件内容解析后的对象
String getContent() 获取系统通知的内容
String getFromAccount() 该系统通知的发起方帐号
long getMessageId() 获取系统通知 ID
SystemMessageStatus getStatus() 获取系统通知的处理状态
String getTargetId() 获取系统通知的目标 ID
long getTime() 获取系统通知的发出时间,单位为 ms
SystemMessageType getType() 获取系统通知类型
boolean isUnread() 判断该系统通知是否已读
void setAttach(String attach) 设置系统通知的附件内容
void setAttachObject(Object object) 设置解析后的附件对象
void setContent(String content) 设置系统通知的内容
void setFromAccount(String fromAccount) 设置发起方帐号
void setMessageId(long messageId) 设置系统通知 ID
void setStatus(SystemMessageStatus status) 设置系统通知的处理状态
void setTargetId(String targetId) 设置系统通知的目标 ID
void setTime(long time) 设置系统通知的发出时间
void setType(int type) 设置系统通知类型
void setUnread(boolean unread) 设置改系统通知已读/未读

内置系统通知

监听系统通知

监听系统通知的到达事件。

/**
 * 注册/注销系统消息接收事件观察者
 * @param observer 观察者, 参数为接收到的系统消息
 * @param register true为注册,false为注销
 */
public void observeReceiveSystemMsg(Observer<SystemMessage> observer, boolean register);
NIMClient.getService(SystemMessageObserver.class)
    .observeReceiveSystemMsg(new Observer<SystemMessage>() {
            @Override
            public void onEvent(SystemMessage message) {
                // 收到系统通知,可以做相应操作
            }
        }, register);

监听未读数变化

此接口可以监听系统消息未读数的变化。

/**
 * 注册/注销系统消息未读数变化事件观察者
 * @param observer 观察者, 参数当前的系统消息未读数
 * @param register true为注册,false为注销
 */
public void observeUnreadCountChange(Observer<Integer> observer, boolean register);
NIMClient.getService(SystemMessageObserver.class)
    .observeUnreadCountChange(sysMsgUnreadCountChangedObserver, register);

private Observer<Integer> sysMsgUnreadCountChangedObserver = new Observer<Integer>() {
        @Override
        public void onEvent(Integer unreadCount) {
            // 更新未读数变化
        }
    };

查询系统通知列表

1、异步版本

/**
 * 查询系统通知列表(异步版本)
 *
 * @return InvocationFuture, 可设置回调函数,参数为系统通知列表
 */
public InvocationFuture<List<SystemMessage>> querySystemMessages(int offset, int limit);

2、同步版本

/**
 * 查询系统通知列表(同步版本)
 *
 * @return 系统通知列表
 */
public List<SystemMessage> querySystemMessagesBlock(int offset, int limit);
参数 说明
offset 数据库查询偏移量
limit 数据库查询条数

1、异步版本

// 从10条开始,查询10条系统消息
NIMClient.getService(SystemMessageService.class).querySystemMessages(10, 10)
        .setCallback(new RequestCallback<List<SystemMessage>>() {
    @Override
    public void onSuccess(List<SystemMessage> param) {
        // 查询成功
    }

    @Override
    public void onFailed(int code) {
        // 查询失败
    }

    @Override
    public void onException(Throwable exception) {
        // error
    }
});

2、同步版本

List<SystemMessage> temps = NIMClient.getService(SystemMessageService.class)
    .querySystemMessagesBlock(offset, limit); // 参数offset为当前已经查了offset条,limit为要继续查询limit条。

根据类型查询系统通知列表

需要传入系统消息类型 SystemMessageType 集合。

1、同步版本

/**
 * 根据类型查询系统通知列表(同步版本)
 *
 * @return 指定类型的系统通知集合
 */
public List<SystemMessage> querySystemMessageByTypeBlock(List<SystemMessageType> types, int offset, int limit);

2、异步版本

/**
 * 根据类型查询系统通知列表(异步版本)
 *
 * @return InvocationFuture, 可设置回调函数,参数为指定类型的系统通知集合
 */
public InvocationFuture<List<SystemMessage>> querySystemMessageByType(List<SystemMessageType> types, int offset, int limit);
参数 说明
types 待查询的系统通知类型集合
offset 数据库查询偏移条数
limit 数据库查询条数

SystemMessageType 属性说明

SystemMessageType 属性 说明
AddFriend 对方(请求/已经)加你为好友
ApplyJoinTeam 用户申请加入群组通知
DeclineTeamInvite 用户拒绝入群邀请的系统通知
RejectTeamApply 管理员拒绝用户入群申请
TeamInvite 管理员邀请其他用户加入群组的系统通知

1、同步版本

List<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// 只查询“添加好友”类型的系统通知, 从头开始查询,查询3List<SystemMessage> temps = NIMClient.getService(SystemMessageService.class)
    .querySystemMessageByTypeBlock(types, 0, 3);

2、异步版本

List<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// 只查询“添加好友”类型的系统通知, 从头开始查询,查询3条
NIMClient.getService(SystemMessageService.class).querySystemMessageByType(types, 0, 3)
        .setCallback(new RequestCallback<List<SystemMessage>>() {
    @Override
    public void onSuccess(List<SystemMessage> param) {
         // 查询成功
    }

    @Override
    public void onFailed(int code) {
        // 查询失败
    }

    @Override
    public void onException(Throwable exception) {
        // error
    }
});

设置系统通知状态

系统通知状态枚举见 SystemMessageStatus,目前除了提供了未处理、已通过、已拒绝、已忽略、已过期这五种状态之外,提供了五个自定义扩展类型,供第三方开发者使用。 在用户处理过系统通知之后,调用此函数更新系统通知状态。

/**
 * 设置系统通知状态。在用户处理过系统通知之后,可调用此函数更新
 *
 */
public void setSystemMessageStatus(long messageId, SystemMessageStatus status);
参数 说明
messageId 系统通知的 ID
status 待更新的状态

SystemMessageStatus 属性说明:

参数 说明
declined 已拒绝
expired 已过期
extension1 开发者可自定义的扩展类型1
extension2 开发者可自定义的扩展类型2
extension3 开发者可自定义的扩展类型3
extension4 开发者可自定义的扩展类型4
extension5 开发者可自定义的扩展类型5
ignored 已忽略
init 未处理状态
passed 已通过验证
// 以设置系统通知状态为已过期为例
SystemMessageStatus status = SystemMessageStatus.expired;
NIMClient.getService(SystemMessageService.class)
     .setSystemMessageStatus(message.getMessageId(), status);

删除一条系统通知

/**
 * 删除一条系统通知
 *
 * @param messageId 指定的系统通知ID
 */
public void deleteSystemMessage(long messageId);
NIMClient.getService(SystemMessageService.class)
    .deleteSystemMessage(message.getMessageId());

删除所有系统通知

此接口将删除所有的系统通知。

/**
 * 删除所有系统通知
 */
public void clearSystemMessages();
NIMClient.getService(SystemMessageService.class).clearSystemMessages();

删除指定类型的系统通知

调用此接口,可以删除指定类型的系统通知。删除的类型见 SystemMessageType

/**
 * 删除指定类型的系统通知
 *
 */
public void clearSystemMessagesByType(List<SystemMessageType> types);
参数 说明
types 系统通知类型集合
List<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// 只删除“添加好友”类型的系统通知
NIMClient.getService(SystemMessageService.class).clearSystemMessagesByType(types);

查询系统通知未读数总和

SystemMessage 中属性 unread 用来标志该条系统通知是否未读,该函数将返回所有未读的系统通知总数。

/**
 * 查询系统通知未读数总和
 *
 * @return 系统通知未读总数
 */
public int querySystemMessageUnreadCountBlock();
int unread = NIMClient.getService(SystemMessageService.class)
    .querySystemMessageUnreadCountBlock();

查询指定类型的系统通知未读数总和

/**
 * 查询指定类型的系统通知未读数总和
 *
 * @param types 系统通知类型集合
 * @return 指定类型的系统通知未读数总和
 */
public int querySystemMessageUnreadCountByType(List<SystemMessageType> types);
List<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// 查询“添加好友”类型的系统通知未读数总和
int unread = NIMClient.getService(SystemMessageService.class)
    .querySystemMessageUnreadCountByType(types);

设置单条系统通知为已读

/**
 * 设置单条系统通知为已读
 *
 * @param messageId 系统通知ID
 */
public void setSystemMessageRead(long messageId);
NIMClient.getService(SystemMessageService.class).setSystemMessageRead(messageId);

将所有系统通知设为已读

该函数调用后系统通知未读数将为零。

/**
 * 将所有系统通知设为已读,系统通知的未读消息总数将清零。
 */
public void resetSystemMessageUnreadCount();
// 进入过系统通知列表后,可调用此函数将未读数值为0
NIMClient.getService(SystemMessageService.class).resetSystemMessageUnreadCount();

将指定类型的系统通知设为已读接口

/**
 * 将指定类型的系统通知设为已读
 *
 * @param types 系统通知类型集合
 */
public void resetSystemMessageUnreadCountByType(List<SystemMessageType> types);
List<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// 将“添加好友”类型的系统通知设为已读
NIMClient.getService(SystemMessageService.class).resetSystemMessageUnreadCountByType(types);

自定义系统通知

系统通知属于网易云通信的体系内,如果第三方 APP 需要自己的系统通知,可使用自定义通知,其数据结构为 CustomNotification

CustomNotification 接口说明:

返回值 参数 说明
String getApnsText() 获取如果接收方是 iOS 设备登录,该消息的 APNS 推送文本内容
CustomNotificationConfig getConfig() 自定义通知的配置选项,详见 CustomNotificationConfig
String getContent() 获取消息具体内容
String getFromAccount() 获取该通知的发出者帐号
NIMAntiSpamOption getNIMAntiSpamOption() 获取反垃圾配置
Map getPushPayload() 获取第三方自定义的推送属性
String getSessionId() 获取聊天对象的 Id(好友帐号,群 ID 等)
SessionTypeEnum getSessionType() 获取会话类型
long getTime() 获取消息时间,单位为 ms
boolean isSendToOnlineUserOnly() 该消息是否只发送当前在线的用户/群组
void setApnsText(String apnsText) 设置如果接收方是 iOS 设备登录,该消息的 APNS 推送文本内容
void setConfig(CustomNotificationConfig config) 设置自定义通知的配置选项
void setContent(String content) 设置消息内容
void setFromAccount(String fromAccount) 设置该通知的发起者帐号
void setNIMAntiSpamOption(NIMAntiSpamOption antiSpamOption) 设置反垃圾配置项
void setPushPayload(Map pushPayload) 设置第三方自定义的推送属性
void setSendToOnlineUserOnly(boolean sendToOnlineUserOnly) 设置该消息是否只发送给当前在线的用户
void setSessionId(String sessionId) 设置聊天对象ID
void setSessionType(SessionTypeEnum sessionType) 设置会话类型
void setTime(long time) 设置消息时间

自定义通知提供的灵活性包括:

注意:自定义通知和自定义消息的不同之处在于,自定义消息归属于网易云通信的消息体系内,适用于会话中,由 SDK 存储在消息数据库中,与网易云通信的其他内建消息类型一同展现给用户。而自定义通知主要用于第三方的一些事件状态通知,网易云通信不存储,也不解释这些通知,网易云通信仅仅负责替第三方传递和通知这些事件,起到透传的作用。

发送自定义通知

通过 SDK 提供的接口,第三方 APP 可以在客户端向其他用户或者群组发送自定义通知。SDK 能发送的自定义通知主要分为两种。

1. 只有接收方当前在线才会收到,如果发送方发送时,指定的接收者不在线,这条通知将会被丢弃。在 demo 中,我们以此实现了"正在输入"这种状态的通知。

2. 保证接收方一定会收到,如果接收方当前在线,会立即收到,如果当前不在线,则在下次登录后立即收到。如果接收方上次登录是 iOS 版本,还会收到 APNS 推送通知。

/**
 * 发送一条指令消息。<br>
 * 由于SDK仅负责透传该消息,因此不会记录指令消息状态,但可以设置回调函数监听发送结果。
 *
 * @param notification 指令消息
 * @return InvocationFuture 可设置回调函数,监听发送结果。
 */
public InvocationFuture<Void> sendCustomNotification(CustomNotification notification);

1、以只有接收方当前在线才会收到举例

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

// 构建通知的具体内容。为了可扩展性,这里采用 json 格式,以 "id" 作为类型区分。
// 这里以类型 “1” 作为“正在输入”的状态通知。
JSONObject json = new JSONObject();
json.put("id", "1");
notification.setContent(json.toString());

// 发送自定义通知
NIMClient.getService(MsgService.class).sendCustomNotification(notification);

2、以保证接收方一定会收到举例

// 构造自定义通知,指定接收者
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());

// 设置该消息需要保证送达
notification.setSendToOnlineUserOnly(false);

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

// 自定义推送属性
Map<String,Object> pushPayload = new HashMap<>();
pushPayload.put("key1", "payload 1");
pushPayload.put("key2", 2015);
notification.setPushPayload(pushPayload);

// 发送自定义通知
NIMClient.getService(MsgService.class).sendCustomNotification(notification);

配置并发送自定义通知

发送自定义通知时还可以设置通知配置选项 CustomNotificationConfig

CustomNotificationConfig属性说明:

CustomNotificationConfig 属性 说明
enablePush 该通知是否进行推送(消息提醒)。默认为 true
enablePushNick 该通知是否需要推送昵称(针对iOS客户端有效),
如果为false,那么对方收到通知后,iOS端将不显示推送昵称。
默认为 false
enableUnreadCount 该通知是否要计入未读数,
如果为true,那么对方收到通知后,可以通过读取此配置项决定自己业务的未读计数变更。
默认为 true
CustomNotification command = new CustomNotification();
command.setSessionId(account);
command.setSessionType(sessionType);
CustomNotificationConfig config = new CustomNotificationConfig();
config.enablePush = false; // 不推送
config.enableUnreadCount = false;
command.setConfig(config);
...
NIMClient.getService(MsgService.class).sendCustomNotification(command);

接收自定义通知

上层有两种方式接收自定义通知,一是通过添加通知接收观察者的,二是通过广播的方式接收。SDK 从版本 1.4.0 开始,推荐使用第一种方式接收。从这个版本起,收到消息后就会激活 UI 主进程,并通知到已注册的观察者。只要在主进程的入口添加自定义通知的观察者,就能收到该通知。

/**
 * 注册/注销自定义通知接收观察者
 * @param observer 观察者,参数为收到的自定义通知
 * @param register true为注册,false为注销
 */
public void observeCustomNotification(Observer<CustomNotification> observer, boolean register);
// 如果有自定义通知是作用于全局的,不依赖某个特定的 Activity,那么这段代码应该在 Application 的 onCreate 中就调用
NIMClient.getService(MsgServiceObserve.class).observeCustomNotification(new Observer<CustomNotification>() {
    @Override
    public void onEvent(CustomNotification message) {
        // 在这里处理自定义通知。
    }
}, register);

如果使用广播接收者的方式(Android 未来版本会禁止程序后台接收隐式广播,因此不建议开发者使用该方式),首先需要在 AndroidManifest.xml 文件中声明一个接收器:

<!-- 声明自定义通知的广播接收器,第三方 APP 集成时,action 中的 com.netease.nim.demo 请替换为自己的包名 -->
<!-- 需要权限声明 <uses-permission android:name="com.netease.nim.demo.permission.RECEIVE_MSG"/> -->
<receiver
    android:name=".receiver.CustomNotificationReceiver"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="com.netease.nim.demo.ACTION.RECEIVE_CUSTOM_NOTIFICATION"/>
    </intent-filter>
</receiver>

然后实现这个接收器:

public class CustomNotificationReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        String action = context.getPackageName() + NimIntent.ACTION_RECEIVE_CUSTOM_NOTIFICATION;
        if (action.equals(intent.getAction())) {
            // 从 intent 中取出自定义通知, intent 中只包含了一个 CustomNotification 对象
            CustomNotification notification = (CustomNotification)
            intent.getSerializableExtra(NimIntent.EXTRA_BROADCAST_MSG);
            // 第三方 APP 在此处理自定义通知:存储,处理,展示给用户等
            Log.i("demo", "receive custom notification: " + notification.getContent()
             + " from :" + notification.getSessionId() + "/" + notification.getSessionType());
        }
    }
}