# Presence (/zh-CN/api-reference/rtm/swift/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-swift-接口描述]
查询当前 App ID 下指定用户是否存在有效的 RTM 登录连接。每次查询一个 User ID,支持查询自己;查询方和目标用户均无需加入或订阅频道。
### 接口方法 [#getUserOnlineStatus-swift-接口方法]
```swift
if let presence = rtmClient.getPresence() {
presence.getUserOnlineStatus(userId: userId, completion: completionBlock)
} else {
print("Presence is unavailable")
}
```
使用 completion 形式的 `getUserOnlineStatus(userId:completion:)` 绑定。
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `userId` | `String` | 必填 | - | 目标用户的精确 User ID,须符合 RTM User ID 规则。查询自己时也须传入完整 User ID,空字符串不代表自己。 |
| `completion` | `AgoraRtmGetUserOnlineStatusBlock` | 接收结果时提供 | - | 成功时返回 `AgoraRtmUserOnlineStatus` 且无错误;失败时返回错误信息。 |
### 注意事项 [#getUserOnlineStatus-swift-注意事项]
- 调用方须具有可用的 MESSAGE service,且 MESSAGE session 已连接。该查询不依赖 Presence 服务开关或 Sync Database 就绪。
- 结果是服务端响应时刻的状态快照。异常断网后,服务端需要经过失联检测窗口才能判定用户离线。该接口不提供最后在线时间或在线状态变更订阅。
- `logout` 会取消在途请求;`release` 会清理请求资源,不保证客户端释放后仍会回调。重复或晚到的响应不会使同一请求重复完成。
### 基本用法 [#getUserOnlineStatus-swift-基本用法]
以下示例假设客户端已初始化、登录成功且 session 已连接。
```swift
if let presence = rtmClient.getPresence() {
presence.getUserOnlineStatus(userId: "targetUserId") { status, errorInfo in
if let errorInfo = errorInfo {
print("Query failed: \(errorInfo)")
return
}
guard let status = status else {
print("No usable result")
return
}
if status.online {
print("\(status.userId) is online")
} else {
print("\(status.userId) is offline or does not exist")
}
}
} else {
print("Presence is unavailable")
}
```
使用说明见[查询用户在线状态](/zh-CN/realtime-media/rtm/build/state-and-attributes/presence-basic/swift#query-user-online-status-swift)。
### 错误码 [#getUserOnlineStatus-errors]
| 数值 | 名称 | 触发条件 |
| --- | --- | --- |
| `-10006` | `invalidUserId` | `userId` 为空字符串或非法 UID。 参数为非可选 `String`,不要传入 `nil`。 |
| `-10025` | `notConnected` | 调用方 session 未连接。 |
| `-10022` | `serviceNotSupport` | 私有配置的 service 未包含 MESSAGE。 |
| `-10021` | `operationRateExceedLimitation` | 本接口调用频率超过限制。默认每个 `RtmClient` 实例内独立计数,限额为 20 次/秒,不与其他 API 共用配额。 |
| `-13012` | `presenceOperationTimeout` | 5 秒内未收到有效响应,SDK 不做超时重试。 |
| `-13013` | `presenceOperationFailed` | 响应条目数不是 1,或返回的 UID 与请求不匹配。 |
| `-13015` | `presencePendingRequestCancelled` | logout 取消在途请求。 |
## AgoraRtmUserOnlineStatus [#AgoraRtmUserOnlineStatus]
以下字段仅在 completion 回调成功时有效。调用失败时应检查 `errorInfo`,不能据此判定目标用户离线。
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 被查询的 UID。 |
| `online` | `Bool` | `true`:存在有效的 RTM 登录连接;`false`:用户离线或不存在。 |
## AgoraRtmGetUserOnlineStatusBlock [#AgoraRtmGetUserOnlineStatusBlock]
`getUserOnlineStatus` 的完成回调。成功时返回非 nil 的 `AgoraRtmUserOnlineStatus`,错误信息为 `nil`;失败时返回错误信息,没有可用结果。读取 `online` 前先检查错误及结果,不得将 nil 结果当作离线结果。
## whoNow [#whonow]
### 接口描述 [#接口描述]
调用 `whoNow` 方法,你可以实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。
### 接口方法 [#接口方法]
你可以通过以下方式调用 `whoNow` 方法:
```swift
whoNow(
channelName: String,
channelType: AgoraRtmChannelType,
options: AgoraRtmPresenceOptions?
) async -> (AgoraRtmWhoNowResponse?, AgoraRtmErrorInfo?)
```
```swift
whoNow(
channelName: String,
channelType: AgoraRtmChannelType,
options: AgoraRtmPresenceOptions?,
completion completionBlock: AgoraRtmWhoNowBlock? = nil
)
```
| 参数 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | String | 必填 | - | 频道名称。 |
| `channelType` | `AgoraRtmChannelType` | 必填 | - | 频道类型。详见 [`AgoraRtmChannelType`](/zh-CN/api-reference/rtm/swift/enumv#channeltype)。 |
| `options` | `AgoraRtmPresenceOptions` | 选填 | - | 查询附加选项。 |
| `completion` | `AgoraRtmWhoNowBlock` | 选填 | - | [presence-swift-html-0-4-4 details](#table-slot-presence-swift-html-0-4-4) |
**presence-swift-html-0-4-4 details**
调用结果回调:
- 调用成功:在 `response` 参数中返回 `AgoraRtmWhoNowResponse` 数据,在 `errorInfo` 参数中返回 `nil`。
- 调用失败:在 `response` 参数中返回 `nil`,在 `errorInfo` 参数中返回错误信息。
`AgoraRtmPresenceOptions` 数据类型包含以下属性:
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| -------------- | ----- | ------ | ----- | --------------- |
| `includeUserId` | Bool | 选填 | `true` | 返回结果中是否包含在线成员的用户 ID。 |
| `includeState` | Bool | 选填 | `false` | 返回结果中是否包含在线用户的临时状态数据。 |
| `page` | String | 必填 | - | 页码书签。你可以在返回值中查看是否还有下一页。 |
`AgoraRtmWhoNowResponse` 数据类型包含以下属性:
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `totalOccupancy` | Int32 | `userStateList` 列表长度。当 `AgoraRtmPresenceOptions` 中的 `includeUserId` 和 `includeState` 属性都设置为 `false` 时,此值表示频道当前总在线人数。 |
| `userStateList` | `[AgoraRtmUserState]` | 频道在线用户及其临时状态信息列表。 |
| `nextPage` | String | [presence-swift-html-1-3-2 details](#table-slot-presence-swift-html-1-3-2) |
**presence-swift-html-1-3-2 details**
下一页书签。通过该属性可以确认是否有下一页:
- 值为空表示没有下一页。
- 值不为空表示有下一页。你可以将该值填写在 `whoNow` 的 `page` 属性中,从而查询下一页结果。
`AgoraRtmUserState` 数据类型包含以下属性:
| 属性 | 类型 | 描述 |
| ------- | ---- | ------ |
| `userId` | String | 用户 ID。 |
| `states` | `[String : String]` | 频道在线用户及其临时状态信息列表。 |
### 接口方法 [#接口方法-1]
```swift tab="async-await"
// async-await
let presenceOptions = AgoraRtmPresenceOptions()
presenceOptions.includeUserId = true
presenceOptions.includeState = true
let (response, error) = await rtmClient.getPresence()!.whoNow(
channelName: "exampleChannel",
channelType: .message,
options: presenceOptions)
if let errorInfo = error {
print("Error querying presence: \(errorInfo.reason)")
} else if let whoNowResponse = response {
// Handle the response containing user presence information
print("Users in channel: \(whoNowResponse)")
}
```
```swift tab="callback"
// callback
let presenceOptions = AgoraRtmPresenceOptions()
presenceOptions.includeUserId = true
presenceOptions.includeState = true
rtmClient.getPresence()!.whoNow(
channelName: "exampleChannel",
channelType: .message,
options: presenceOptions
) { (response, error) in
if let errorInfo = error {
print("Error querying presence: \(errorInfo.reason)")
} else if let whoNowResponse = response {
// Handle the response containing user presence information
print("Users in channel: \(whoNowResponse)")
} else {
print("Presence query completed with no response or error.")
}
}
```
## whereNow [#wherenow]
### 接口描述 [#接口描述-1]
在数据统计、App 调试等场景中,你可能需要了解指定用户订阅或加入的所有频道。调用 `whereNow` 方法,你可以实时获取指定用户所在频道的列表。
### 接口方法 [#接口方法-2]
你可以通过以下方式调用 `whereNow` 方法:
```swift
whereNow(userId: String) async -> (AgoraRtmWhereNowResponse?, AgoraRtmErrorInfo?)
```
```swift
whereNow(userId: String, completion completionBlock: AgoraRtmWhereNowBlock? = nil)
```
| 参数 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `userId` | String | 必填 | - | 用户 ID。 |
| `completion` | `AgoraRtmWhereNowBlock` | 选填 | - | [presence-swift-html-2-2-4 details](#table-slot-presence-swift-html-2-2-4) |
**presence-swift-html-2-2-4 details**
调用结果回调:
- 调用成功:在 `response` 参数中返回 `AgoraRtmWhereNowResponse` 数据,在 `errorInfo` 参数中返回 `nil`。
- 调用失败:在 `response` 参数中返回 `nil`,在 `errorInfo` 参数中返回错误信息。
`AgoraRtmWhereNowResponse` 数据类型包含以下属性:
| 属性 | 类型 | 描述 |
| ---- | ------ | --------- |
| `totalChannel` | Int32 | 用户所在频道个数。 |
| `channels` | `[AgoraRtmChannelInfo]` | 用户所在频道信息类表,其中包含频道名和频道类型。 |
`AgoraRtmChannelInfo` 数据类型包含以下属性:
| 属性 | 类型 | 描述 |
| ------------ | ----------------- | --------- |
| `channelName` | String | 频道名称。 |
| `channelType` | `AgoraRtmChannelType` | 频道类型。详见 [`AgoraRtmChannelType`](/zh-CN/api-reference/rtm/swift/enumv#channeltype)。 |
### 基本用法 [#基本用法]
```swift tab="async-await"
// async-await
let (response, error) = await rtmClient.getPresence()!.whereNow(userId:"your_userID")
if let errorInfo = error {
print("Error querying presence: \(errorInfo.reason)")
} else if let whereNowResponse = response {
// Handle the response containing user presence information
print("channels: \(whereNowResponse)")
}
```
```swift tab="callback"
// callback
rtmClient.getPresence()!.whereNow(userId: "your_userID") { (response, error) in
if let errorInfo = error {
print("Error querying presence: \(errorInfo.reason)")
} else if let whereNowResponse = response {
// Process the list of channels the user is currently in
print("User is present in channels: \(whereNowResponse.channels)")
} else {
print("No response or error.")
}
}
```
## setState [#setstate]
### 接口描述 [#接口描述-2]
为满足不同业务场景对用户状态的设置需求,RTM 提供 `setState` 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。
设置成功后,只要用户保持订阅频道并一直在线,自定义状态就会在频道中持续存在。`setState` 方法设置的是临时用户状态,当用户离开频道或断开与 RTM 的连接时,状态会消失。如果需要在重新加入频道或者重新连接时恢复用户状态,你需要实时在本地缓存该数据。如果你希望永久保存用户状态数据,声网推荐改用 Storage 功能的 `setUserMetadata` 方法。
如果用户修改了临时用户状态,RTM 会实时触发 `remoteStateChanged` 类型的 `didReceivePresenceEvent` 事件通知。你可以通过订阅频道并配置对应属性来接收该事件。
### 接口方法 [#接口方法-3]
你可以通过以下方式调用 `setState` 方法:
```swift
setState(
channelName: String,
channelType: AgoraRtmChannelType,
items: [String : String]
) async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
```
```swift
setState(
channelName: String,
channelType: AgoraRtmChannelType,
items: [String : String],
completion completionBlock: AgoraRtmOperationBlock? = nil
)
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | String | 必填 | - | 频道名称 |
| `channelType` | `AgoraRtmChannelType` | 必填 | - | 频道类型。详见 [`AgoraRtmChannelType`](/zh-CN/api-reference/rtm/swift/enumv#channeltype)。 |
| `items` | `[String: String]` | 必填 | - | 用户状态,类型为 `StateItem` 数组。 |
| `completion` | `AgoraRtmOperationBlock` | 选填 | - | [presence-swift-html-3-4-4 details](#table-slot-presence-swift-html-3-4-4) |
**presence-swift-html-3-4-4 details**
调用结果回调:
- 调用成功:在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据,在 `errorInfo` 参数中返回 `nil`。
- 调用失败:在 `response` 参数中返回 `nil`,在 `errorInfo` 参数中返回错误信息。
### 接口方法 [#接口方法-4]
```swift tab="async-await"
// async-await
let stateItems: [String: String] = ["user1": "online","user2": "busy"]
// Call the setState function
let (response, error) = await rtmClient.getPresence()!.setState(
channelName: "exampleChannel",
channelType: .message,
items: stateItems
)
if let errorInfo = error {
print("Error setting state: \(errorInfo.reason)")
} else if let setStateResponse = response {
// Handle the response indicating the result of the state update
print("State update response: \(setStateResponse)")
}
```
```swift tab="callback"
// callback
let stateItems: [String: String] = ["user1": "online", "user2": "busy"]
// Call the setState function using a callback
rtmClient.getPresence()?.setState(
channelName: "exampleChannel",
channelType: .message,
items: stateItems
) { (response, error) in
if let errorInfo = error {
print("Error setting state: \(errorInfo.reason)")
} else if let setStateResponse = response {
// Handle the response indicating the result of the state update
print("State update response: \(setStateResponse)")
} else {
print("No response or error received.")
}
}
```
## getState [#getstate]
### 接口描述 [#接口描述-3]
如需获取指定频道中指定用户的临时用户状态,你可以调用 `getState` 方法。
### 接口方法 [#接口方法-5]
你可以通过以下方式调用 `getState` 方法:
```swift
getState(
channelName: String,
channelType: AgoraRtmChannelType,
userId: String
) async -> (AgoraRtmPresenceGetStateResponse?, AgoraRtmErrorInfo?)
```
```swift
getState(
channelName: String,
channelType: AgoraRtmChannelType,
userId: String,
completion completionBlock: AgoraRtmPresenceGetStateBlock? = nil
)
```
| 参数 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | String | 必填 | - | 频道名称。 |
| `channelType` | `AgoraRtmChannelType` | 必填 | - | 频道类型。详见 [`AgoraRtmChannelType`](/zh-CN/api-reference/rtm/swift/enumv#channeltype)。 |
| `userId` | String | 必填 | - | 用户 ID。 |
| `completion` | `AgoraRtmPresenceGetStateBlock` | 选填 | - | [presence-swift-html-4-4-4 details](#table-slot-presence-swift-html-4-4-4) |
**presence-swift-html-4-4-4 details**
调用结果回调:
- 调用成功:在 `response` 参数中返回 `AgoraRtmPresenceGetStateResponse` 数据,在 `errorInfo` 参数中返回 `nil`。
- 调用失败:在 `response` 参数中返回 `nil`,在 `errorInfo` 参数中返回错误信息。
`AgoraRtmPresenceGetStateResponse` 数据类型包含以下属性:
| 属性 | 类型 | 描述 |
| ---- | ----- | -------- |
| `state` | `AgoraRtmUserState` | 频道在线用户及其临时状态信息列表。 |
`AgoraRtmUserState` 数据类型包含以下属性:
| 属性 | 类型 | 描述 |
| ------- | ---------------- | --- |
| `userId` | String | 用户 ID。 |
| `states` | `[String : String]` | 频道在线用户及其临时状态信息列表。 |
### 基本用法 [#基本用法-1]
```swift tab="async-await"
// async-await
let userId = "user1"
// Call the getState function
let (response, error) = await rtmClient.getPresence()!.getState(
channelName: "exampleChannel",
channelType: .message,
userId: userId
)
if let errorInfo = error {
print("Error getting state: \(errorInfo.reason)")
} else if let getStateResponse = response {
// Handle the response containing the user's state
print("User state response: \(getStateResponse)")
}
```
```swift tab="callback"
// callback
let userId = "user1"
// Call the getState function
rtmClient.getPresence()?.getState(
channelName: "exampleChannel",
channelType: .message,
userId: userId,
completion: { (response, error) in
if let errorInfo = error {
print("Error getting state: \(error.reason)")
} else if let getStateResponse = response {
// Handle the response containing the user's state
print("User state response: \(getStateResponse)")
}
}
)
```
## removeState [#removestate]
### 接口描述 [#接口描述-4]
当不再需要某个临时用户状态时,你可以调用 `removeState` 方法删除自己的一个或多个临时状态。成功删除用户状态后,订阅该频道且开启 Presence 事件监听的用户会收到 `remoteStateChanged` 类型的 `didReceivePresenceEvent` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/swift/configuration#事件监听)。
### 接口方法 [#接口方法-6]
你可以通过以下方式调用 `removeState` 方法:
```swift
removeState(
channelName: String,
channelType: AgoraRtmChannelType,
keys: [String]
) async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
```
```swift
removeState(
channelName: String,
channelType: AgoraRtmChannelType,
keys: [String],
completion completionBlock: AgoraRtmOperationBlock? = nil
)
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | String | 必填 | - | 频道名称 |
| `channelType` | `AgoraRtmChannelType` | 必填 | - | 频道类型。详见 [`AgoraRtmChannelType`](/zh-CN/api-reference/rtm/swift/enumv#channeltype)。 |
| `keys` | `[String]` | 必填 | - | 需要删除状态的 `key` 列表。如果不填写,则删除全部状态。 |
| `completion` | `AgoraRtmOperationBlock` | 选填 | - | [presence-swift-html-5-4-4 details](#table-slot-presence-swift-html-5-4-4) |
**presence-swift-html-5-4-4 details**
调用结果回调:
- 调用成功:在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据,在 `errorInfo` 参数中返回 `nil`。
- 调用失败:在 `response` 参数中返回 `nil`,在 `errorInfo` 参数中返回错误信息。
### 基本用法 [#基本用法-2]
```swift tab="async-await"
// async-await
let stateKeys: [String] = ["user1", "user2"]
// Call the removeState function
let (response, error) = await rtmClient.getPresence()!.removeState(
channelName: "exampleChannel",
channelType: .message,
keys: stateKeys
)
if let errorInfo = error {
print("Error removing state: \(errorInfo.reason)")
} else if let removeStateResponse = response {
// Handle the response indicating the result of the state removal
print("State removal response: \(removeStateResponse)")
}
```
```swift tab="callback"
// callback
let stateKeys: [String] = ["user1", "user2"]
rtmClient.getPresence()?.removeState(
channelName: "exampleChannel",
channelType: .message,
keys: stateKeys,
completion: { (response, error) in
if let errorInfo = error {
print("Error removing state: \(errorInfo.reason)")
} else if let removeStateResponse = response {
// Handle the response indicating the result of the state removal
print("State removal response: \(removeStateResponse)")
}
}
)
```