跳到主要内容

用户在线状态订阅 (Presence)

趣小界支持实时展示好友/聊天对象的在线状态及当前在线终端（如 iOS、Android、Web、macOS）。QXJIMSDK 提供了完整的订阅、取消订阅、批量查询以及实时变更事件流 userStatusEvents。

断线重连自动续订保障

QXJIMClient 内部维护了当前已订阅的 subscribedUserIDs 集合。当设备网络闪断并重新连接 WebSocket 成功（.connected）时，SDK 会自动在后台重新向服务器发起订阅请求，业务层无需手动编写重连恢复逻辑。

1. 数据模型 (IMUserOnlineStatus)​

public struct IMUserOnlineStatus: Codable, Sendable, Equatable, Identifiable {
    public var userID: String
    public var status: Int32?          // 1 = 在线 (Online), 0 = 离线 (Offline)
    public var platformIDs: [Int32]?   // 当前在线的平台 ID 数组

    /// 便捷属性：是否在线
    public var isOnline: Bool

    /// 便捷属性：当前在线的平台枚举列表（如 [.iOS, .web]）
    public var onlinePlatforms: [IMPlatform]
}

2. 订阅与监听在线状态​

// 1. 订阅指定用户的在线状态（调用后会立即返回这些用户当前的在线状态）
let currentStatuses = try await QXJIMClient.shared.subscribeUsersStatus(
    userIDs: ["u_10002", "u_10003"]
)
for status in currentStatuses {
    print("用户 \(status.userID) 当前是否在线: \(status.isOnline), 在线设备: \(status.onlinePlatforms)")
}

// 2. 实时监听已订阅用户的上下线变化
Task {
    for await statusChange in QXJIMClient.shared.userStatusEvents.stream() {
        print("用户 \(statusChange.userID) 状态变更为: \(statusChange.isOnline ? "在线" : "离线")")
    }
}

3. 取消订阅与主动查询​

// 当用户离开好友列表或聊天窗口时，取消订阅不再需要关注的用户
try await QXJIMClient.shared.unsubscribeUsersStatus(userIDs: ["u_10002"])

// 获取当前所有已订阅用户的最新在线状态
let allSubscribed = try await QXJIMClient.shared.getSubscribeUsersStatus()

// 一次性查询指定用户的在线状态
let queried = try await QXJIMClient.shared.getUserStatus(userIDs: ["u_10005"])