IM 即时通讯
Windows/macOS
开发指南

频道未读数管理

更新时间: 2022/12/27 17:42:16

如果您的应用 UI 上需要展示频道未读数,可参考本文介绍的流程获取频道内的消息未读信息并管理其变化。

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

未读信息定义

NIM SDK 中的NIMQChatUnreadInfo类定义了圈组频道的未读信息。

您可通过多个方式获取NIMQChatUnreadInfo,具体方法参见本文的实现频道未读数持续监听实现频道未读数的直接获取

前提条件

开始集成前,请确保:

实现流程

实现频道未读数持续监听

本文通过以下 UI 简图的场景为例,说明如何完成频道 1 未读数的监听、未读数的清零以及清零后的持续监听。

步骤1: 监听未读数

您需要订阅 频道 1 的未读数才能实现监听。完成如下两个子步骤后,当有新的消息下发到频道 1 ,SDK 将触发频道未读信息变更事件 QChatChannelUnreadResp 并上报。

订阅的频道仅在当前登录期间有效(因网络波动导致的断线自动重连除外)。如您调用Logout登出后,需要重新订阅。

  1. 进入服务器 1 后,调用GetChannelsByPage方法刷新频道列表,得到频道 1频道 2频道 3频道 4

  2. 调用nim::Channel::Subscribe方法订阅频道 1。 调用该方法时入参配置如下:

    参数 类型 说明
    id_infos NIMQChatChannelIDInfo * 频道 ID 列表:传入您需要订阅的频道 ID 与该频道所属的服务器的 ID 组成的未读信息列表
    ope_type NIMQChatSubscribeOpeType 操作类型:订阅或取消订阅
    sub_type NIMQChatSubscribeType 订阅类型,本场景下需传入kNIMQChatSubscribeTypeUnreadCount订阅频道的未读数。

    该两步的示例代码如下:

    QChatChannelGetChannelsPageParam param;
    param.server_id = 1;
    param.timestamp = 0;
    param.limit = 100;
    param.cb = [](const QChatChannelGetChannelsPageResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // 记录查到的频道列表
        // ...
    };
    Channel::GetChannelsByPage(param);
    
    QChatChannelSubscribeParam param;
    param.ope_type = kNIMQChatSubscribeOpeTypeSubscribe;
    param.sub_type = kNIMQChatSubscribeTypeMsg;
    NIMQChatChannelIDInfo id_info;
    id_info.server_id = 1;
    id_info.channel_id = 1;
    param.id_infos.push_back(id_info);
    param.cb = [](const QChatChannelSubscribeResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Channel::Subscribe(param);
    

步骤2:清除未读数

以下说明以清除频道 1 的未读数为例,介绍在完成步骤1: 监听未读数后,如何清除频道未读数以及清除后对未读数进行持续监听。

  1. 进入频道 1 后,记住您应用中“代表该频道的属性”(假设为currentChannel)。

  2. 调用nim::Message::MarkRead方法,调用时传timestamp参数为已读的最新消息的时间戳(Unix 时间戳),进行未读数的清零操作。

    未读数清零时,SDK 触发QChatChannelUnreadResp事件,该事件包含的未读数参数unread_count0

    • 针对同一个频道,调用nim::Message::MarkRead方法存在频控限制,200 ms 内只能调用一次。
    • 如果调用nim::Message::MarkRead时传timestamp参数为0,会将频道内所有消息标记为未读。

    示例代码如下:

    QChatMarkMessageReadParam param;
    param.id_info.server_id = 123456;
    param.id_info.channel_id = 123456;
    param.timestamp = 123456;
    param.cb = [](const QChatMarkMessageReadResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Message::MarkRead(param);
    
    
  3. 根据您的应用逻辑做出判断和处理:当currentChannelQChatChannelUnreadResp事件里的channel_id相同时,每当频道 1 有新消息接收时,仍旧会触发该事件。

实现频道未读数的直接获取

如果您不想订阅某个频道,而只想获取该频道当前的未读数,完成以下操作即可。

  1. 确保您已在当前频道中。

  2. 直接调用QueryUnreadInfo查询当前频道未读信息。

    • 该方法调用存在频控,200ms 内最多可调用一次。
    • 该方法单次最多查询频道数量为 100。

    示例代码:

    QChatChannelQueryUnreadInfoParam param;
    NIMQChatChannelIDInfo id_info;
    id_info.server_id = 123456;
    id_info.channel_id = 123456;
    param.id_infos.push_back(id_info);
    param.cb = [](const QChatChannelQueryUnreadInfoResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Channel::QueryUnreadInfo(param);
    

常见问题

1. 什么操作会导致频道未读数增加?

您当前所在的频道中,有用户发送消息或更新消息,对应频道中的当前用户未读信息中的未读数会增加。以下特殊情情况除外:

  • 消息发送者是自己
  • 不存云端消息历史
  • 不需要消息计数
  • 未订阅当前频道

2. 什么操作会导致频道未读数减少?

您当前所在的频道中,有用户删除消息,对应频道中的当前用户未读信息中的未读数会减少。以下特殊情况除外:

  • 删除的是自己发的消息,则未读数不变。
  • 未订阅当前频道。

3. 撤回消息和重发消息是否影响未读数?

这两种操作都不影响未读数。

4. 通过nim::Message::MarkRead方法标记频道消息已读,对未读数有什么影响?

如果在当前频道通过该方法标记消息已读,会更新对应频道的未读信息。

调用该方法时传入timestamp参数(标记消息已读的时间戳),不仅可能减少未读数,还可能增加未读数。例如将timestamp设为0时,会标记所有消息未读从而增加未读数。

此文档是否对你有帮助?
有帮助
去反馈
  • 未读信息定义
  • 前提条件
  • 实现流程
  • 实现频道未读数持续监听
  • 步骤1: 监听未读数
  • 步骤2:清除未读数
  • 实现频道未读数的直接获取
  • 常见问题
  • 1. 什么操作会导致频道未读数增加?
  • 2. 什么操作会导致频道未读数减少?
  • 3. 撤回消息和重发消息是否影响未读数?
  • 4. 通过nim::Message::MarkRead方法标记频道消息已读,对未读数有什么影响?