# Presence (/zh-CN/api-reference/rtm/react-native/presence) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). Presence 提供监控用户上线、下线及用户历史状态变更通知的能力。通过 Presence 功能,你可以实时获取以下信息: - 用户加入或离开指定频道的实时事件通知 - 自定义临时用户状态及其变更实时事件通知 - 查询指定用户加入或订阅了哪些频道 - 查询指定频道有哪些用户加入及其用户临时状态数据 :::info[信息] Presence 能力适用于 Message Channel 和 Stream Channel。 ::: ## whoNow [#whonow] ### 接口描述 [#接口描述] 调用 `whoNow` 方法,你可以实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。 ### 接口方法 [#接口方法] 你可以通过以下方式调用 `whoNow` 方法: ```typescript whoNow( channelName: string, channelType: RtmChannelType, options?: PresenceOptions ): Promise; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ---------- | --- | ----- | --- | ---- | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | RtmChannelType | 必填 | - | 频道类型。支持的取值见[频道类型](/zh-CN/api-reference/rtm/react-native/enumv#channeltype)。 | | `options` | object | 选填 | - | 查询附加选项。 | `options` 包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ------------- | ---- | ----- | ---- | --------------- | | `includedUserId` | boolean | 选填 | `true` | 返回结果中是否包含在线成员的用户 ID。 | | `includedState` | boolean | 选填 | `false` | 返回结果中是否包含在线用户的临时状态数据。 | | `page` | string | 选填 | - | 页码书签。如果不填写,则 SDK 默认返回第一页结果。你可以在返回值中查看是否还有下一页。 | ### 基本用法 [#基本用法] ```typescript const options = { includedUserId : true, includedState : true, page : "yourBookMark" } try { const result = await rtm.presence.whoNow( "chat_room", "MESSAGE", options); console.log(result); } catch(status){ console.log(status); } ``` ### 返回值 [#返回值] 如果方法调用成功,则返回一个 `WhoNowResponse` 类型数据: ```typescript type WhoNowResponse = { timestamp: number, // 预留字段 totalOccupancy: number, // 频道当前总在线人数 occupants: [{ states: StateItem[{}], userId: string, statesCount: number }], // 频道在线用户及其临时状态信息列表 nextPage: string // 下一页的页码书签 } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```typescript type ErrorInfo = { error: boolean; // 本次操作是否出错 reason: string; // 本次操作的 API 名称 operation: string; // 错误码 errorCode: number; // 错误描述 }; ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 ## whereNow [#wherenow] ### 接口描述 [#接口描述-1] 在数据统计、App 调试等场景中,你可能需要了解指定用户订阅或加入的所有频道。调用 `whereNow` 方法,你可以实时获取指定用户所在频道的列表。 ### 接口方法 [#接口方法-1] 你可以通过以下方式调用 `whereNow` 方法: ```typescript whereNow(userId: string): Promise; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ----- | --- | ----- | ---------------- | -------- | | `userId` | string | 必填 | - | 用户 ID。如果设为空字符串 `""`,则使用本地用户的 `userId` 进行查询。 | ### 基本用法 [#基本用法-1] ```typescript try { const result = await rtm.presence.whereNow("Tony"); console.log(result); } catch (status) { console.log(status); } ``` ### 返回值 [#返回值-1] 如果方法调用成功,则返回一个 `WhereNowResponse` 类型数据: ```typescript type WhereNowResponse = { timestamp: number, // 预留字段 totalChannel: number, // 用户所在频道的个数 channels: [{ channelName: string, // 用户所在频道的名称 channelType: RtmChannelType // 用户所在频道的类型 }] } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```typescript type ErrorInfo = { error: boolean; // 本次操作是否出错 reason: string; // 本次操作的 API 名称 operation: string; // 错误码 errorCode: number; // 错误描述 }; ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 ## setState [#setstate] ### 接口描述 [#接口描述-2] 为满足不同业务场景对用户状态的设置需求,RTM 提供 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。 设置成功后,只要用户保持订阅频道并一直在线,自定义状态就会在频道中持续存在。`setState` 方法设置的是临时用户状态,当用户离开频道或断开与 RTM 的连接时,状态会消失。如果需要在重新加入频道或者重新连接时恢复用户状态,你需要实时在本地缓存该数据。如果你希望永久保存用户状态数据,声网推荐改用 Storage 功能的 `setUserMetadata` 方法。 如果用户修改了临时用户状态,RTM 会实时触发 `remoteStateChanged` 类型的 `presence` 事件通知。你可以通过订阅频道并配置对应属性来接收该事件。 ### 接口方法 [#接口方法-2] 你可以通过以下方式调用 `setState` 方法: ```typescript setState( channelName: string, channelType: RtmChannelType, state: StateItem ): Promise; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ---------- | --- | ----- | --- | -------------- | | `channelName` | string | 必填 | - | 频道名称 | | `channelType` | RtmChannelType | 必填 | - | 频道类型。支持的取值见[频道类型](/zh-CN/api-reference/rtm/react-native/enumv#channeltype)。 | | `state` | object | 必填 | - | 键值对格式的 JSON 对象,其中键值必须为 string 类型。 | ### 基本用法 [#基本用法-2] ```typescript var newState = { "mood": "pumped", "isTyping": false }; try { const result = await rtm.Presence.setState("chat_room", "MESSAGE", newState); console.log(result); } catch (status) { console.log(status); } ``` ### 返回值 [#返回值-2] 如果方法调用成功,则返回一个 `SetStateResponse` 类型数据: ```typescript type SetStateResponse = { timestamp: number // 预留字段 } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```typescript type ErrorInfo = { error: boolean; // 本次操作是否出错 reason: string; // 本次操作的 API 名称 operation: string; // 错误码 errorCode: number; // 错误描述 }; ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 ## getState [#getstate] ### 接口描述 [#接口描述-3] 如需获取指定频道中指定用户的临时用户状态,你可以调用 `getState` 方法。 ### 接口方法 [#接口方法-3] 你可以通过以下方式调用 `getState` 方法: ```typescript getState( userId: string, channelName: string, channelType: RtmChannelType ): Promise; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ---------- | --- | ----- | --- | ------------- | | `userId` | string | 必填 | - | 用户 ID。 | | `channelName` | string | 必填 | - | 频道名称。 | | `channelType` | RtmChannelType | 必填 | - | 频道类型。支持的取值见[频道类型](/zh-CN/api-reference/rtm/react-native/enumv#channeltype)。 | ### 基本用法 [#基本用法-3] ```typescript try { const result = await rtm.presence.getState("Tony", "chat_room", "MESSAGE"); console.log(result); } catch (status) { console.log(status); } ``` ### 返回值 [#返回值-3] 如果方法调用成功,则返回一个 `GetStateResponse` 类型数据: ```typescript type GetStateResponse = { timestamp: number, // 预留字段 userId: string, // 用户 ID states: object, // 返回用户状态键值对 statesCount: number // 用户状态个数 } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```typescript type ErrorInfo = { error: boolean; // 本次操作是否出错 reason: string; // 本次操作的 API 名称 operation: string; // 错误码 errorCode: number; // 错误描述 }; ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 ## removeState [#removestate] ### 接口描述 [#接口描述-4] 当不再需要某个临时用户状态时,你可以调用 `removeState` 方法删除自己的一个或多个临时状态。成功删除用户状态后,订阅该频道且开启 Presence 事件监听的用户会收到 `remoteStateChanged` 类型的 `presence` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/react-native/configuration#事件监听)。 ### 接口方法 [#接口方法-4] 你可以通过以下方式调用 `removeState` 方法: ```typescript removeState( channelName: string, channelType: RtmChannelType, // 传入 state key, 不传代表全部删除 options?: RemoveStateOptions ): Promise; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ---------- | --- | ----- | --- | ------------- | | `channelName` | string | 必填 | - | 频道名称 | | `channelType` | RtmChannelType | 必填 | - | 频道类型。支持的取值见[频道类型](/zh-CN/api-reference/rtm/react-native/enumv#channeltype)。 | | `options` | object | 选填 | - | 删除临时用户状态的选项。如果不填写,则 SDK 会默认删除全部状态。 | `options` 包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ---- | ---- | ----- | ---- | ----- | | `states` | string[] | 选填 | - | 需要删除状态的 `key` 列表。如果不填写或设为空数组,则 SDK 会默认删除全部状态。 | ### 基本用法 [#基本用法-4] ```typescript const options = { states: ["mode", "Typing"] } try { const result = await rtm.Presence.removeState("chat_room", "MESSAGE", options); console.log(result); } catch (status) { console.log(status); } ``` ### 返回值 [#返回值-4] 如果方法调用成功,则返回一个 `RemoveStateResponse` 类型数据: ```typescript type RemoveStateResponse = { timestamp: number // 预留字段 } ``` 如果方法调用失败,则返回一个 `ErrorInfo` 类型数据: ```typescript type ErrorInfo = { error: boolean; // 本次操作是否出错 reason: string; // 本次操作的 API 名称 operation: string; // 错误码 errorCode: number; // 错误描述 }; ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。