IM 即时通讯
Android
开发指南

服务器未读数管理

更新时间: 2023/09/22 14:50:57

服务器未读数,指圈组服务器下所有频道的总未读数。网易云信 NIM SDK 的QChatServerUnreadInfoChangedEvent接口定义了圈组服务器未读信息变更事件。用户在圈组频道内发送或删除消息后,SDK 触发该事件,事件信息包含未读信息QChatServerUnreadInfo。您可调用QChatServiceObserver接口的observeServerUnreadInfoChanged方法监听该事件。

本文介绍获取服务器未读数并按需清空的实现方法以及相应的示例代码。

游客接收到的消息无已读未读逻辑。不支持对游客展示消息未读数。

前提条件

使用限制

服务器未读数管理存在如下与未读数相关的限制:

  • 所有未读消息(包括@消息)的消息阈值默认为 99 条。
  • @消息的未读数的有效期,默认为 7 天,即默认存储 7 天。

若需要扩展上限,可在控制台配置圈组子功能项(未读的@消息数-周期所有未读消息(包括@)的消息计数-阈值),具体请参考开通和配置圈组功能

实现流程

流程概览

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

uml diagram

流程说明

以下仅对上图中标为橙色的流程进行详细说明。

  1. 用户A 调用 observeServerUnreadInfoChanged 方法监听QChatServerUnreadInfoChangedEvent

    示例代码如下:

    //监听服务器未读数
    NIMClient.getService(QChatServiceObserver.class).observeServerUnreadInfoChanged(new Observer<QChatServerUnreadInfoChangedEvent>() {
        @Override
        public void onEvent(QChatServerUnreadInfoChangedEvent event) {
            //获取变更后服务器未读信息列表
            List<QChatServerUnreadInfo> serverUnreadInfos = event.getServerUnreadInfos();
            //遍历变更的服务器未读信息
            for (QChatServerUnreadInfo serverUnreadInfo : serverUnreadInfos) {
                
            }
        }
    },true);
    
  2. 根据服务器下的频道数量,按如下方法订阅服务器下的所有频道的未读数。订阅后 SDK 获取并缓存各频道的初始未读数。

    • 如果目标服务器下的频道数量不超过 200 个,则用户A 可调用subscribeAllChannel方法一次性订阅服务器下所有的频道的未读数(单次调用最多可传入 10 个 服务器 ID)。
    • 如果目标服务器下的频道数量超过 200 个,则用户 A 需多次调用subscribeChannel方法订阅服务器下所有频道的未读数(单次调用最多可订阅 100 个频道)。
    • 通过subscribeAllChannel订阅频道,单次调用可传入的服务器 ID 数量上限为 10 个。即使多次调用,单个服务器下最多仅能订阅 200 个 频道。如果目标服务器下频道数量大于 200,需改用subscribeChannel方法订阅服务器下所有频道(单次调用最多可订阅 100 个频道)。
    • 获取服务器的精确未读数,必须订阅服务器下的所有频道的未读数。

    示例代码如下:

    调用 subscribeAllChannel 的示例
    QChatSubscribeType type = QChatSubscribeType.CHANNEL_MSG;
    List<Long> serverIds = getServerIds();
    QChatSubscribeAllChannelParam param = new QChatSubscribeAllChannelParam(type,serverIds);
    NIMClient.getService(QChatServerService.class).subscribeAllChannel(param).setCallback(
            new RequestCallback<QChatSubscribeAllChannelResult>() {
                @Override
                public void onSuccess(QChatSubscribeAllChannelResult result) {
                    //订阅成功的频道未读信息
                    List<QChatUnreadInfo> unreadInfoList = result.getUnreadInfoList();
                    //订阅失败的频道Id列表
                    List<Long> failedList = result.getFailedList();
                }
    
                @Override
                public void onFailed(int code) {
                    
                }
    
                @Override
                public void onException(Throwable exception) {
    
                }
            });
    
    调用 subscribeChannel 的示例
    //获取server下所有channelId信息
    List<QChatChannelIdInfo> channelIdInfos = getAllChannelIdInfoOfServer(311254);
    QChatSubscribeChannelParam param = new QChatSubscribeChannelParam(QChatSubscribeType.CHANNEL_MSG_UNREAD_COUNT, QChatSubscribeOperateType.SUB,channelIdInfos);
    NIMClient.getService(QChatChannelService.class).subscribeChannel(param).setCallback(new RequestCallback<QChatSubscribeChannelResult>() {
        @Override
        public void onSuccess(QChatSubscribeChannelResult result) {
            //订阅成功
        }
    
        @Override
        public void onFailed(int code) {
            //订阅失败
        }
    
        @Override
        public void onException(Throwable exception) {
            //订阅异常
        }
    });
    
  3. 其他用户发送消息删除消息后,SDK 对服务器下所有已订阅频道的未读数进行累加计算。

    未读数累加规则如下:

    • 接到新消息,某个频道未读数 +1 时:
      • 如果累加未读数达到未读数上限(maxCount),则触发QChatServerUnreadInfoChangedEvent,并给出maxCount
      • 如果累加未读数没有达到maxCount,则触发QChatServerUnreadInfoChangedEvent,并给出累加未读数。
    • 消息被删除,某个频道未读数 - 1 时:
      • 如果累加未读数达到maxCount,则触发QChatServerUnreadInfoChangedEvent,并给出maxCount
      • 如果累加未读数没有达到maxCount,则触发QChatServerUnreadInfoChangedEvent,并给出累加未读数。
  4. SDK 计算完所有已订阅频道的累加未读数(QChatServerUnreadInfo)后,将其返回给用户A。

    服务器累加未读数在达到maxCount后,QChatServerUnreadInfoChangedEvent事件将不会触发。

  5. 如需清空该服务器的未读数,可调用markRead方法清空。

    示例代码如下:

    List<Long> serverIds = getServerIds();
    NIMClient.getService(QChatServerService.class).markRead(new QChatServerMarkReadParam(serverIds)).setCallback(
            new RequestCallback<QChatServerMarkReadResult>() {
                @Override
                public void onSuccess(QChatServerMarkReadResult result) {
                    //清空未读数成功的服务器Id列表
                    List<Long> successServerIds = result.getSuccessServerIds();
                    //清空未读数失败的服务器Id列表
                    List<Long> failedServerIds = result.getFailedServerIds();
                }
    
                @Override
                public void onFailed(int code) {
    
                }
    
                @Override
                public void onException(Throwable exception) {
    
                }
            });
    
此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 使用限制
  • 实现流程
  • 流程概览
  • 流程说明