Presence

  • HarmonyOS

更新时间

Presence 提供用户在线状态查询、频道成员查询,以及临时状态管理和变更通知能力。通过 Presence,你可以获取以下信息:

  • 查询当前 App ID 下指定用户的 RTM 在线状态
  • 用户加入或离开指定频道的实时事件通知
  • 自定义临时用户状态及其变更实时事件通知
  • 查询指定用户加入或订阅了哪些频道
  • 查询指定频道有哪些用户加入及其用户临时状态数据

信息

Presence 的频道相关能力适用于 Message Channel 和 Stream Channel。

getUserOnlineStatus

接口描述

查询当前 App ID 下指定用户是否存在有效的 RTM 登录连接。每次查询一个 User ID,支持查询自己;查询方和目标用户均无需加入或订阅频道。

接口方法

TypeScript
getUserOnlineStatus(userId: string): Promise<GetUserOnlineStatusResponse>
参数类型是否必填默认值描述
userIdstring必填-目标用户的精确 User ID,须符合 RTM User ID 规则。查询自己时也须传入完整 User ID,空字符串不代表自己。
表格内容超出当前宽度,可横向滚动查看更多列。

返回 Promise<GetUserOnlineStatusResponse>:成功时 resolve 并返回结果,失败时 reject 并抛出 RtmError。

注意事项

  • 调用方须具有可用的 MESSAGE service,且 MESSAGE session 已连接。该查询不依赖 Presence 服务开关或 Sync Database 就绪。
  • 结果是服务端响应时刻的状态快照。异常断网后,服务端需要经过失联检测窗口才能判定用户离线。该接口不提供最后在线时间或在线状态变更订阅。
  • logout 会取消在途请求;release 会清理请求资源,不保证客户端释放后仍会回调。重复或晚到的响应不会使同一请求重复完成。

基本用法

以下示例假设客户端已初始化、登录成功且 session 已连接。

TypeScript
try {
  const status = await rtmClient.presence.getUserOnlineStatus('targetUserId');
  if (status.online) {
    console.log(`${status.userId} is online`);
  } else {
    console.log(`${status.userId} is offline or does not exist`);
  }
} catch (error) {
  console.error('Query failed:', error);
}

使用说明见查询用户在线状态。

错误码

数值名称触发条件
-10006INVALID_USER_IDuserId 为空字符串或非法 UID。 参数类型为 string,不要传入 null 或 undefined。
-10025NOT_CONNECTED调用方 session 未连接。
-10022SERVICE_NOT_SUPPORTED私有配置的 service 未包含 MESSAGE。
-10021OPERATION_RATE_EXCEED_LIMITATION本接口调用频率超过限制。默认每个 RtmClient 实例内独立计数,限额为 20 次/秒,不与其他 API 共用配额。
-13012PRESENCE_OPERATION_TIMEOUT5 秒内未收到有效响应,SDK 不做超时重试。
-13013PRESENCE_OPERATION_FAILED响应条目数不是 1,或返回的 UID 与请求不匹配。
-13015PRESENCE_PENDING_REQUEST_CANCELLEDlogout 取消在途请求。
表格内容超出当前宽度,可横向滚动查看更多列。

GetUserOnlineStatusResponse

查询成功时 Promise resolve 并返回以下字段;Promise rejection 表示查询失败,不表示目标用户离线。

TypeScript
interface GetUserOnlineStatusResponse extends BaseResponse {
  userId: string;
  online: boolean;
}
属性类型描述
userIdstring被查询的 UID。
onlinebooleantrue:存在有效的 RTM 登录连接;false:用户离线或不存在。
timestampnumber继承自 BaseResponse,保留字段且固定为 0,不是最后在线时间、状态变更时间或查询时间。
表格内容超出当前宽度,可横向滚动查看更多列。

whoNow

接口描述

调用 whoNow 方法,你可以实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。

接口方法

你可以通过以下方式调用 whoNow 方法:

TypeScript
async whoNow(channelName: string, channelType: RtmChannelType, options: PresenceOptions): Promise<WhoNowResponse>
参数类型是否必填默认值描述
channelNamestring必填-频道名称。
channelTypeRtmChannelType必填-频道类型。详见 RtmChannelType。
optionsPresenceOptions必填-查询附加选项。
表格内容超出当前宽度,可横向滚动查看更多列。

PresenceOptions 数据类型包含以下属性:

属性类型是否必填默认值描述
includeUserIdboolean选填true返回结果中是否包含在线成员的用户 ID。
includeStateboolean选填false返回结果中是否包含在线用户的临时状态数据。
pagestring选填''页码书签。如果不填写,则 SDK 默认返回第一页结果。你可以在返回值中查看是否还有下一页。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

该方法返回一个 Promise,成功时 resolve 并返回 WhoNowResponse 对象,失败时 reject 并抛出 RtmError 异常。

WhoNowResponse 数据结构如下:

属性类型描述
timestampnumber操作的时间戳(保留字段,供未来使用)。
userStateListUserState[]频道在线用户及其临时状态信息列表。
totalOccupancynumber频道当前总在线人数。当 includeUserId 和 includeState 都设置为 false 时,userStateList 可能为空,但此值表示频道实际在线人数。
nextPagestring

下一页书签。通过该属性可以确认是否有下一页:

  • 值为空字符串表示没有下一页。
  • 值不为空表示有下一页。你可以将该值填写在 whoNow 的 page 属性中,从而查询下一页结果。
表格内容超出当前宽度,可横向滚动查看更多列。

UserState 数据类型包含以下属性:

属性类型描述
userIdstring用户 ID。
statesStateItem[]频道在线用户及其临时状态信息列表。
表格内容超出当前宽度,可横向滚动查看更多列。

StateItem 数据类型包含以下属性:

属性类型描述
keystring用户状态的键。如果指定的键已经存在,则该键的值会被新值覆盖;如果指定的键不存在,则 SDK 会新增该键/值对。
valuestring用户状态的值。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

TypeScript
import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full';
import type { PresenceOptions } from '@shengwang/rtm-full';

// Query with detailed user info
const options: PresenceOptions = {
  includeState: true,
  includeUserId: true
};

try {
  const response = await rtmClient.presence.whoNow('channelName', RtmChannelType.MESSAGE, options);
  console.log('Total users in channel:', response.totalOccupancy);
  console.log('User list length:', response.userStateList.length);
  
  // Process user states
  response.userStateList.forEach((userState) => {
    console.log('User:', userState.userId);
    userState.states.forEach((state) => {
      console.log(`  ${state.key}: ${state.value}`);
    });
  });
  
  // Check for next page
  if (response.nextPage) {
    const nextPageOptions: PresenceOptions = {
      includeState: true,
      includeUserId: true,
      page: response.nextPage
    };
    const nextPageResult = await rtmClient.presence.whoNow('channelName', RtmChannelType.MESSAGE, nextPageOptions);
    console.log('Next page users:', nextPageResult.userStateList.length);
  }
} catch (error) {
  if (error instanceof RtmError) {
    console.error('whoNow failed:', error.errorCode, error.reason);
  }
}

whereNow

接口描述

在数据统计、App 调试等场景中,你可能需要了解指定用户订阅或加入的所有频道。调用 whereNow 方法,你可以实时获取指定用户所在频道的列表。

接口方法

你可以通过以下方式调用 whereNow 方法:

TypeScript
async whereNow(userId: string): Promise<WhereNowResponse>
参数类型是否必填默认值描述
userIdstring必填-用户 ID。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

该方法返回一个 Promise,成功时 resolve 并返回 WhereNowResponse 对象,失败时 reject 并抛出 RtmError 异常。

WhereNowResponse 数据结构如下:

属性类型描述
timestampnumber操作的时间戳(保留字段,供未来使用)。
channelsChannelInfo[]频道信息列表。
表格内容超出当前宽度,可横向滚动查看更多列。

ChannelInfo 数据类型包含以下属性:

属性类型描述
channelNamestring频道名称。
channelTypeRtmChannelType频道类型。详见 RtmChannelType。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

TypeScript
import { RtmClient, RtmError } from '@shengwang/rtm-full';

try {
  const response = await rtmClient.presence.whereNow('tony');
  console.log('User is in', response.channels.length, 'channels');
  
  response.channels.forEach((channel) => {
    console.log('Channel:', channel.channelName, 'Type:', channel.channelType);
  });
} catch (error) {
  if (error instanceof RtmError) {
    console.error('whereNow failed:', error.errorCode, error.reason);
  }
}

setState

接口描述

为满足不同业务场景对用户状态的设置需求,RTM 提供 setState 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。

设置成功后,只要用户保持订阅频道并一直在线,自定义状态就会在频道中持续存在。setState 方法设置的是临时用户状态,当用户离开频道或断开与 RTM 的连接时,状态会消失。如果需要在重新加入频道或者重新连接时恢复用户状态,你需要实时在本地缓存该数据。如果你希望永久保存用户状态数据,声网推荐改用 Storage 功能的 setUserMetadata 方法。

如果用户修改了临时用户状态,RTM 会实时触发 REMOTE_STATE_CHANGED 类型的 presence 事件通知。你可以通过订阅频道并配置对应属性来接收该事件。

接口方法

你可以通过以下方式调用 setState 方法:

TypeScript
async setState(channelName: string, channelType: RtmChannelType, items: StateItem[]): Promise<SetStateResponse>
参数类型是否必填默认值描述
channelNamestring必填-频道名称
channelTypeRtmChannelType必填-频道类型。详见 RtmChannelType。
itemsStateItem[]必填-用户状态数组。
表格内容超出当前宽度,可横向滚动查看更多列。

StateItem 数据类型包含以下属性:

属性类型描述
keystring用户状态的键。如果指定的键已经存在,则该键的值会被新值覆盖;如果指定的键不存在,则 SDK 会新增该键/值对。
valuestring用户状态的值。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

该方法返回一个 Promise,成功时 resolve 并返回 SetStateResponse 对象,失败时 reject 并抛出 RtmError 异常。

SetStateResponse 数据结构如下:

属性类型描述
timestampnumber操作的时间戳(保留字段,供未来使用)。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

TypeScript
import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full';
import type { StateItem } from '@shengwang/rtm-full';

const states: StateItem[] = [
  { key: 'mood', value: 'pumped' },
  { key: 'status', value: 'online' }
];

try {
  const response = await rtmClient.presence.setState('channelName', RtmChannelType.MESSAGE, states);
  console.log('User state set successfully');
} catch (error) {
  if (error instanceof RtmError) {
    console.error('setState failed:', error.errorCode, error.reason);
  }
}

getState

接口描述

如需获取指定频道中指定用户的临时用户状态,你可以调用 getState 方法。

接口方法

你可以通过以下方式调用 getState 方法:

TypeScript
async getState(channelName: string, channelType: RtmChannelType, userId: string): Promise<GetStateResponse>
参数类型是否必填默认值描述
channelNamestring必填-频道名称。
channelTypeRtmChannelType必填-频道类型。详见 RtmChannelType。
userIdstring必填-用户 ID。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

该方法返回一个 Promise,成功时 resolve 并返回 GetStateResponse 对象,失败时 reject 并抛出 RtmError 异常。

GetStateResponse 数据结构如下:

属性类型描述
timestampnumber操作的时间戳(保留字段,供未来使用)。
userStateUserState频道在线用户及其临时状态信息。
表格内容超出当前宽度,可横向滚动查看更多列。

UserState 数据类型包含以下属性:

属性类型描述
userIdstring用户 ID。
statesStateItem[]频道在线用户及其临时状态信息列表。
表格内容超出当前宽度,可横向滚动查看更多列。

StateItem 数据类型包含以下属性:

属性类型描述
keystring用户状态的键。如果指定的键已经存在,则该键的值会被新值覆盖;如果指定的键不存在,则 SDK 会新增该键/值对。
valuestring用户状态的值。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

TypeScript
import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full';

try {
  const response = await rtmClient.presence.getState('channelName', RtmChannelType.MESSAGE, 'tony');
  console.log('User ID:', response.userState.userId);
  
  response.userState.states.forEach((state) => {
    console.log(`${state.key}: ${state.value}`);
  });
} catch (error) {
  if (error instanceof RtmError) {
    console.error('getState failed:', error.errorCode, error.reason);
  }
}

removeState

接口描述

当不再需要某个临时用户状态时,你可以调用 removeState 方法删除自己的一个或多个临时状态。

成功删除用户状态后,订阅该频道且开启 Presence 事件监听的用户会收到 REMOTE_STATE_CHANGED 类型的 presence 事件通知,详见事件监听。

接口方法

你可以通过以下方式调用 removeState 方法:

TypeScript
async removeState(channelName: string, channelType: RtmChannelType, keys: string[]): Promise<RemoveStateResponse>
参数类型是否必填默认值描述
channelNamestring必填-频道名称
channelTypeRtmChannelType必填-频道类型。详见 RtmChannelType。
keysstring[]必填-需要删除状态的 key 列表。如果传入空数组,则删除全部状态。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

该方法返回一个 Promise,成功时 resolve 并返回 RemoveStateResponse 对象,失败时 reject 并抛出 RtmError 异常。

RemoveStateResponse 数据结构如下:

属性类型描述
timestampnumber操作的时间戳(保留字段,供未来使用)。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

TypeScript
import { RtmClient, RtmError, RtmChannelType } from '@shengwang/rtm-full';

// Remove specific keys
const keysToRemove = ['key0', 'key1', 'key2'];

try {
  const response = await rtmClient.presence.removeState('channelName', RtmChannelType.MESSAGE, keysToRemove);
  console.log('Specific states removed successfully');
} catch (error) {
  if (error instanceof RtmError) {
    console.error('removeState failed:', error.errorCode, error.reason);
  }
}

// Remove all states (pass empty array)
try {
  const response = await rtmClient.presence.removeState('channelName', RtmChannelType.MESSAGE, []);
  console.log('All states removed successfully');
} catch (error) {
  if (error instanceof RtmError) {
    console.error('removeState failed:', error.errorCode, error.reason);
  }
}