在线状态事件通知

  • 小程序

更新时间

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

添加事件监听

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

参数描述
eventTypePresence 事件类型。详见 API 参考。
channelType频道类型,可能是 Message Channel 或 Stream Channel。
channelName事件发生的频道名称。
publisher触发此事件的用户 ID。
states用户临时状态信息列表,REMOTE_STATE_CHANGED 事件发生时有效。
intervalInterval 模式下,当前频道在上一个周期内用户加入、离开、超时、状态变更等事件通知的聚合增量信息。
snapshot快照详情。用户首次加入或订阅频道触发了 SNAPSHOT 事件时有效。
表格内容超出当前宽度,可横向滚动查看更多列。

事件通知类型

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

枚举值描述
SNAPSHOT1: 用户第一次订阅或加入频道时触发,本地用户会收到此类事件通知。
INTERVAL2: 当频道内人数达到设定值后,频道内的事件通知将由实时通知转为定时通知。
REMOTE_JOIN3: 当用户订阅或加入频道时触发,频道中的其他人会收到此类通知。
REMOTE_LEAVE4: 当用户取消订阅或离开频道时触发,频道中的其他人会收到此类通知。
REMOTE_TIMEOUT5: 当用户掉线超时时触发,频道中的其他人会收到此类通知。
REMOTE_STATE_CHANGED6: 当用户临时状态数据发生变更时触发,频道中的其他人会收到此类通知。
ERROR_OUT_OF_SERVICE7: 用户加入频道时未启用 Presence,本地用户会收到此类事件通知。
表格内容超出当前宽度,可横向滚动查看更多列。

事件通知模式

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

实时通知模式

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

JavaScript
{
    eventType: "REMOTE_JOIN";
    channelType: "MESSAGE";
    channelName: "test_channel";
    publisher: "publisher_name";
    stateChanged: {};
    interval: null;
    snapshot: null;
}

定时通知模式

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

JavaScript
interval: {
    join: { users: ["Tony", "Lily"], userCount: 2 },
    leave: { users: ["Jason"], userCount: 1 },
    timeout: { users: ["Wang"], userCount: 1 },
    userStateList: [
        {
            userId: "Harvard",
            states: { "Mic": "False", "Position": "Beijing" },
            statesCount: 2,
        },
    ],
},