# Presence (/zh-CN/api-reference/rtm/harmonyos/presence) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). Presence 提供用户在线状态查询、频道成员查询,以及临时状态管理和变更通知能力。通过 Presence,你可以获取以下信息: - 查询当前 App ID 下指定用户的 RTM 在线状态 - 用户加入或离开指定频道的实时事件通知 - 自定义临时用户状态及其变更实时事件通知 - 查询指定用户加入或订阅了哪些频道 - 查询指定频道有哪些用户加入及其用户临时状态数据 :::info[信息] Presence 的频道相关能力适用于 Message Channel 和 Stream Channel。 ::: ## getUserOnlineStatus [#getUserOnlineStatus] ### 接口描述 [#getUserOnlineStatus-harmonyos-接口描述] 查询当前 App ID 下指定用户是否存在有效的 RTM 登录连接。每次查询一个 User ID,支持查询自己;查询方和目标用户均无需加入或订阅频道。 ### 接口方法 [#getUserOnlineStatus-harmonyos-接口方法] ```typescript getUserOnlineStatus(userId: string): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | `string` | 必填 | - | 目标用户的精确 User ID,须符合 RTM User ID 规则。查询自己时也须传入完整 User ID,空字符串不代表自己。 | 返回 `Promise`:成功时 resolve 并返回结果,失败时 reject 并抛出 `RtmError`。 ### 注意事项 [#getUserOnlineStatus-harmonyos-注意事项] - 调用方须具有可用的 MESSAGE service,且 MESSAGE session 已连接。该查询不依赖 Presence 服务开关或 Sync Database 就绪。 - 结果是服务端响应时刻的状态快照。异常断网后,服务端需要经过失联检测窗口才能判定用户离线。该接口不提供最后在线时间或在线状态变更订阅。 - `logout` 会取消在途请求;`release` 会清理请求资源,不保证客户端释放后仍会回调。重复或晚到的响应不会使同一请求重复完成。 ### 基本用法 [#getUserOnlineStatus-harmonyos-基本用法] 以下示例假设客户端已初始化、登录成功且 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); } ``` 使用说明见[查询用户在线状态](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-basic/harmonyos#query-user-online-status-harmonyos)。 ### 错误码 [#getUserOnlineStatus-errors] | 数值 | 名称 | 触发条件 | | --- | --- | --- | | `-10006` | `INVALID_USER_ID` | `userId` 为空字符串或非法 UID。 参数类型为 `string`,不要传入 `null` 或 `undefined`。 | | `-10025` | `NOT_CONNECTED` | 调用方 session 未连接。 | | `-10022` | `SERVICE_NOT_SUPPORTED` | 私有配置的 service 未包含 MESSAGE。 | | `-10021` | `OPERATION_RATE_EXCEED_LIMITATION` | 本接口调用频率超过限制。默认每个 `RtmClient` 实例内独立计数,限额为 20 次/秒,不与其他 API 共用配额。 | | `-13012` | `PRESENCE_OPERATION_TIMEOUT` | 5 秒内未收到有效响应,SDK 不做超时重试。 | | `-13013` | `PRESENCE_OPERATION_FAILED` | 响应条目数不是 1,或返回的 UID 与请求不匹配。 | | `-13015` | `PRESENCE_PENDING_REQUEST_CANCELLED` | logout 取消在途请求。 | ## GetUserOnlineStatusResponse [#GetUserOnlineStatusResponse] 查询成功时 Promise resolve 并返回以下字段;Promise rejection 表示查询失败,不表示目标用户离线。 ```typescript interface GetUserOnlineStatusResponse extends BaseResponse { userId: string; online: boolean; } ``` | 属性 | 类型 | 描述 | | --- | --- | --- | | `userId` | `string` | 被查询的 UID。 | | `online` | `boolean` | `true`:存在有效的 RTM 登录连接;`false`:用户离线或不存在。 | | `timestamp` | `number` | 继承自 `BaseResponse`,保留字段且固定为 `0`,不是最后在线时间、状态变更时间或查询时间。 | ## whoNow [#whonow] ### 接口描述 [#接口描述] 调用 `whoNow` 方法,你可以实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。 ### 接口方法 [#接口方法] 你可以通过以下方式调用 `whoNow` 方法: ```typescript async whoNow(channelName: string, channelType: RtmChannelType, options: PresenceOptions): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `options` | `PresenceOptions` | 必填 | - | 查询附加选项。 | `PresenceOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ------------- | ---- | ----- | ---- | --------------- | | `includeUserId` | boolean | 选填 | `true` | 返回结果中是否包含在线成员的用户 ID。 | | `includeState` | boolean | 选填 | `false` | 返回结果中是否包含在线用户的临时状态数据。 | | `page` | string | 选填 | `''` | 页码书签。如果不填写,则 SDK 默认返回第一页结果。你可以在返回值中查看是否还有下一页。 | ### 返回值 [#返回值] 该方法返回一个 Promise,成功时 resolve 并返回 `WhoNowResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `WhoNowResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `userStateList` | `UserState[]` | 频道在线用户及其临时状态信息列表。 | | `totalOccupancy` | number | 频道当前总在线人数。当 `includeUserId` 和 `includeState` 都设置为 `false` 时,`userStateList` 可能为空,但此值表示频道实际在线人数。 | | `nextPage` | string | [presence-harmonyos-html-1-4-2 details](#table-slot-presence-harmonyos-html-1-4-2) | **presence-harmonyos-html-1-4-2 details** 下一页书签。通过该属性可以确认是否有下一页: - 值为空字符串表示没有下一页。 - 值不为空表示有下一页。你可以将该值填写在 `whoNow` 的 `page` 属性中,从而查询下一页结果。 `UserState` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ---- | ----- | -------- | | `userId` | string | 用户 ID。 | | `states` | `StateItem[]` | 频道在线用户及其临时状态信息列表。 | `StateItem` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ------ | ------- | ------ | | `key` | string | 用户状态的键。如果指定的键已经存在,则该键的值会被新值覆盖;如果指定的键不存在,则 SDK 会新增该键/值对。 | | `value` | string | 用户状态的值。 | ### 基本用法 [#基本用法] ```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 [#wherenow] ### 接口描述 [#接口描述-1] 在数据统计、App 调试等场景中,你可能需要了解指定用户订阅或加入的所有频道。调用 `whereNow` 方法,你可以实时获取指定用户所在频道的列表。 ### 接口方法 [#接口方法-1] 你可以通过以下方式调用 `whereNow` 方法: ```typescript async whereNow(userId: string): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | string | 必填 | - | 用户 ID。 | ### 返回值 [#返回值-1] 该方法返回一个 Promise,成功时 resolve 并返回 `WhereNowResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `WhereNowResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `channels` | `ChannelInfo[]` | 频道信息列表。 | `ChannelInfo` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ---- | ----- | --------- | | `channelName` | string | 频道名称。 | | `channelType` | `RtmChannelType` | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | ### 基本用法 [#基本用法-1] ```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 [#setstate] ### 接口描述 [#接口描述-2] 为满足不同业务场景对用户状态的设置需求,RTM 提供 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。 设置成功后,只要用户保持订阅频道并一直在线,自定义状态就会在频道中持续存在。`setState` 方法设置的是临时用户状态,当用户离开频道或断开与 RTM 的连接时,状态会消失。如果需要在重新加入频道或者重新连接时恢复用户状态,你需要实时在本地缓存该数据。如果你希望永久保存用户状态数据,声网推荐改用 Storage 功能的 `setUserMetadata` 方法。 如果用户修改了临时用户状态,RTM 会实时触发 `REMOTE_STATE_CHANGED` 类型的 `presence` 事件通知。你可以通过订阅频道并配置对应属性来接收该事件。 ### 接口方法 [#接口方法-2] 你可以通过以下方式调用 `setState` 方法: ```typescript async setState(channelName: string, channelType: RtmChannelType, items: StateItem[]): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `items` | `StateItem[]` | 必填 | - | 用户状态数组。 | `StateItem` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ------ | ------- | ------ | | `key` | string | 用户状态的键。如果指定的键已经存在,则该键的值会被新值覆盖;如果指定的键不存在,则 SDK 会新增该键/值对。 | | `value` | string | 用户状态的值。 | ### 返回值 [#返回值-2] 该方法返回一个 Promise,成功时 resolve 并返回 `SetStateResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `SetStateResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | ### 基本用法 [#基本用法-2] ```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] ### 接口描述 [#接口描述-3] 如需获取指定频道中指定用户的临时用户状态,你可以调用 `getState` 方法。 ### 接口方法 [#接口方法-3] 你可以通过以下方式调用 `getState` 方法: ```typescript async getState(channelName: string, channelType: RtmChannelType, userId: string): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `userId` | string | 必填 | - | 用户 ID。 | ### 返回值 [#返回值-3] 该方法返回一个 Promise,成功时 resolve 并返回 `GetStateResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `GetStateResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | | `userState` | `UserState` | 频道在线用户及其临时状态信息。 | `UserState` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ---- | ----- | -------- | | `userId` | string | 用户 ID。 | | `states` | `StateItem[]` | 频道在线用户及其临时状态信息列表。 | `StateItem` 数据类型包含以下属性: | 属性 | 类型 | 描述 | | ------ | ------- | ------ | | `key` | string | 用户状态的键。如果指定的键已经存在,则该键的值会被新值覆盖;如果指定的键不存在,则 SDK 会新增该键/值对。 | | `value` | string | 用户状态的值。 | ### 基本用法 [#基本用法-3] ```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] ### 接口描述 [#接口描述-4] 当不再需要某个临时用户状态时,你可以调用 `removeState` 方法删除自己的一个或多个临时状态。 成功删除用户状态后,订阅该频道且开启 Presence 事件监听的用户会收到 `REMOTE_STATE_CHANGED` 类型的 `presence` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。 ### 接口方法 [#接口方法-4] 你可以通过以下方式调用 `removeState` 方法: ```typescript async removeState(channelName: string, channelType: RtmChannelType, keys: string[]): Promise ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | string | 必填 | - | 频道名称 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/harmonyos/enumv#channeltype)。 | | `keys` | string[] | 必填 | - | 需要删除状态的 `key` 列表。如果传入空数组,则删除全部状态。 | ### 返回值 [#返回值-4] 该方法返回一个 Promise,成功时 resolve 并返回 `RemoveStateResponse` 对象,失败时 reject 并抛出 `RtmError` 异常。 `RemoveStateResponse` 数据结构如下: | 属性 | 类型 | 描述 | | --- | --- | --- | | `timestamp` | number | 操作的时间戳(保留字段,供未来使用)。 | ### 基本用法 [#基本用法-4] ```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); } } ```