在线状态订阅

大约 6 分钟

在线状态订阅

功能说明

用户在线状态(即 Presence)包含用户的在线、离线以及自定义状态。使用该功能前,你需要在 环信控制台open in new window 开通该服务。详见 环信控制台文档。

本文介绍如何在即时通讯应用中发布、订阅和查询用户的在线状态。

关于用户的在线、离线和自定义状态的定义、变更以及用户的实时感知,详见用户在线状态管理。

功能开通

使用在线状态订阅功能前,需要在环信控制台开通该服务。详见 环信控制台文档。

订阅流程

订阅用户在线状态的基本工作流程如下:

img

如上图所示,订阅用户在线状态的基本步骤如下:

  1. 用户 A 订阅用户 B 的在线状态;
  2. 用户 B 的在线状态发生变更;
  3. 用户 A 收到 ChatPresenceEventListener#onPresenceStatusChanged 回调。

效果如下图:

img

前提条件

使用在线状态功能前,请确保满足以下条件:

订阅指定用户的在线状态

默认情况下,你不关注任何其他用户的在线状态。你可以通过调用 ChatPresenceManager#subscribe 方法订阅指定用户的在线状态,示例代码如下:

members 为要订阅的用户 ID 数组,expiry 为订阅时长,单位为秒。两个参数均为必填参数。

const members = ['<user_id>'];
// 订阅时长,单位为秒;此处设置为 1 天
const expiry = 1 * 24 * 3600;

try {
  // 订阅指定用户的在线状态
  const presences = await ChatClient.getInstance().presenceManager
    .subscribe(members, expiry);
  // 处理被订阅用户的当前在线状态
  console.log('订阅成功:', presences);
} catch (error: unknown) {
  console.error('订阅在线状态失败:', error);
}

成功订阅指定用户的在线状态后,SDK 通过 Promise 返回被订阅用户的在线状态。

被订阅用户的在线状态发生变化时,订阅者会收到 ChatPresenceEventListener#onPresenceStatusChanged 回调。

提示

  • 订阅时长最长为 30 天,过期需重新订阅。如果未过期的情况下重复订阅,新设置的有效期会覆盖之前的有效期。
  • 每次调用接口最多只能订阅 100 个账号,若数量较大需多次调用。
  • 每个用户 ID 订阅的用户数不超过 3000。如果超过 3000,后续订阅也会成功,但默认会将订阅剩余时长较短的替代。
  • 每个用户最多可被 3000 个用户订阅。

发布自定义在线状态

用户在线时,可调用 ChatPresenceManager#publishPresence 方法发布自定义在线状态:

try {
  // 发布自定义在线状态
  await ChatClient.getInstance().presenceManager
    .publishPresence('自定义状态');
  console.log('发布自定义在线状态成功');
} catch (error: unknown) {
  console.error('发布自定义在线状态失败:', error);
}

description 参数用于设置自定义在线状态,调用时请显式传入字符串。

在线状态发布后,发布者和订阅者均会收到 ChatPresenceEventListener#onPresenceStatusChanged 回调。

添加在线状态监听器

添加用户在线状态的监听器,示例代码如下:

const presenceListener: ChatPresenceEventListener = {
  onPresenceStatusChanged(presences: ChatPresence[]): void {
    // 处理在线状态变化
    console.log('在线状态已更新:', presences);
  },
};

// 添加在线状态监听器
ChatClient.getInstance().presenceManager
  .addPresenceListener(presenceListener);

参考以上示例代码,使用 ChatPresenceEventListener 监听器实现 onPresenceStatusChanged(presences: ChatPresence[]) 方法。当订阅的用户在线状态发生变化时,会收到 ChatPresenceEventListener#onPresenceStatusChanged 回调。

不再需要监听时,可调用 ChatPresenceManager#removePresenceListener 移除监听器,传入注册时使用的同一个监听器对象:

// 移除在线状态监听器
ChatClient.getInstance().presenceManager
  .removePresenceListener(presenceListener);

取消订阅指定用户的在线状态

若取消指定用户的在线状态订阅,可调用 ChatPresenceManager#unsubscribe 方法,示例代码如下:

const members = ['<user_id>'];

try {
  // 取消订阅指定用户的在线状态
  await ChatClient.getInstance().presenceManager.unsubscribe(members);
  console.log('取消订阅成功');
} catch (error: unknown) {
  console.error('取消订阅失败:', error);
}

查询被订阅用户列表

为方便用户管理订阅关系,SDK 提供 ChatPresenceManager#fetchSubscribedMembers 方法,可使用户分页查询自己订阅的用户列表,示例代码如下:

// pageNum:当前页码,从 1 开始,默认值为 1
const pageNum = 1;
// pageSize:每页返回的用户数量,取值范围为 [1,100],默认值为 20
const pageSize = 20;

try {
  // 分页查询自己订阅的用户列表
  const subscribedMembers = await ChatClient.getInstance().presenceManager
    .fetchSubscribedMembers(pageNum, pageSize);
  console.log('被订阅用户列表:', subscribedMembers);
} catch (error: unknown) {
  console.error('查询被订阅用户列表失败:', error);
}

获取用户的当前在线状态

如果不关注用户的在线状态变更,你可以调用 ChatPresenceManager#fetchPresenceStatus 获取用户当前的在线状态,而无需订阅状态。示例代码如下:

// members:要查询状态的用户 ID,每次最多可传 100 个用户 ID
const members = ['<user_id>'];

try {
  // 获取指定用户当前的在线状态
  const presences = await ChatClient.getInstance().presenceManager
    .fetchPresenceStatus(members);
  console.log('当前在线状态:', presences);
} catch (error: unknown) {
  console.error('获取在线状态失败:', error);
}

接口列表

API 名称或属性所属模块/类说明
subscribeChatPresenceManager订阅指定用户的在线状态。
publishPresenceChatPresenceManager发布当前用户的自定义在线状态。
unsubscribeChatPresenceManager取消订阅指定用户的在线状态。
fetchSubscribedMembersChatPresenceManager分页查询当前用户已订阅的用户列表。
fetchPresenceStatusChatPresenceManager查询指定用户当前的在线状态。
addPresenceListenerChatPresenceManager添加在线状态监听器。
removePresenceListenerChatPresenceManager移除在线状态监听器。
onPresenceStatusChangedChatPresenceEventListener在线状态发生变化时触发。
publisherChatPresence在线状态发布者 ID。
statusDetailsChatPresence发布者各设备的在线状态,类型为 Map<string, number>。
statusDescriptionChatPresence自定义在线状态扩展信息。
lastTimeChatPresence状态更新时间,Unix 时间戳,单位为秒。
expiryTimeChatPresence订阅到期时间,Unix 时间戳,单位为秒。
上次编辑于: