在线状态事件通知

  • HarmonyOS

更新时间

了解如何在实时消息 RTM 中在线状态事件通知,包括适用场景、配置步骤、实现要点和注意事项。

添加事件监听

接收 Presence 事件通知,你需要实现事件监听程序,详见事件监听。除此之外,你需要在订阅或加入频道时将 withPresence 参数设置成 true。PresenceEvent 数据结构包含以下属性:

事件通知类型

Presence 事件通知有七种类型,它们分别是:

事件通知模式

Presence 事件通知模式是指在频道中如何将 Presence 事件通知到订阅用户。有两种模式:实时通知模式(Announce) 和 定时通知模式(Interval)。

用户可以在控制台的项目设置中通过实时通知最大人数大小来决定两种模式相互切换的条件。定时通知模式可防止频道内在线用户过多而导致的事件嘈杂。实时通知最大人数可以设置的范围为 [8,128],如果你的需求超出此范围,需要联系声网 RTM 团队(rtm-support@shengwang.cn)另行调整。

从 v2.3.0 起,RTM 在现有事件通知模式基础上增加大频道优化策略,默认阈值为 512 人:

  • 当频道在线人数不超过 512 人时,Presence 沿用现有事件通知行为。
  • 当频道在线人数超过 512 人时,SDK 会自动采用大频道优化策略,无需应用开启、关闭或监听模式切换状态。
  • 在大频道优化模式下,客户端持续同步的成员明细最多包含 512 名成员;其他成员的加入、离开、超时和状态变化主要合并为频道总人数变化。
  • 应用可以通过既有的 INTERVAL 事件接收聚合后的成员变化,并通过 interval.totalOccupancy 获取频道总在线人数。
  • 当频道人数回落后,SDK 会自动恢复原有成员同步方式,应用无需管理切换逻辑。

interval.totalOccupancy 表示当前频道的总在线人数。在大频道优化模式下,该值表示频道内所有在线用户的数量,不受最多同步 512 名用户明细的限制;但该值可能有短暂延迟。

实时通知模式

如果频道中的在线人数小于实时通知最大人数参数设定的值(默认值为 50),则 Presence 事件通知处于实时通知模式。在此模式下,REMOTE_JOIN_CHANNEL、REMOTE_LEAVE_CHANNEL、REMOTE_TIMEOUT、REMOTE_STATE_CHANGED 事件在触发时会立即发送到客户端。

TypeScript
{
    eventType: RtmPresenceEventType.REMOTE_JOIN_CHANNEL,
    channelType: RtmChannelType.MESSAGE,
    channelName: "chat_room",
    publisher: "Tony",
    stateChanged: [],
    interval: null,
    snapshot: null,
    timestamp: 1710487149497
}

定时通知模式

当频道中的在线人数超过实时通知最大人数的值时,频道会进入定时通知模式。在这种模式下,REMOTE_JOIN_CHANNEL、REMOTE_LEAVE_CHANNEL、REMOTE_TIMEOUT、REMOTE_STATE_CHANGED 事件会被 INTERVAL 事件代替,并以一定的时间间隔发送给频道中所有用户。

TypeScript
{
    eventType: RtmPresenceEventType.INTERVAL,
    channelType: RtmChannelType.MESSAGE,
    channelName: "chat_room",
    publisher: "",
    stateChanged: [],
    interval: {
        join: ["Tony", "Lily"],
        leave: ["Jason"],
        timeout: ["Wang"],
        userStateList: [
            {
                userId: "Harvard",
                states: [
                    { key: "Mic", value: "False" },
                    { key: "Position", value: "Beijing" }
                ]
            },
            {
                userId: "Alice",
                states: [
                    { key: "Mic", value: "True" },
                    { key: "Position", value: "Shanghai" }
                ]
            }
        ]
    },
    snapshot: null,
    timestamp: 1710487149497
}