订阅用户在线状态
本文档旨在指导开发者如何在融云即时通讯 Flutter IMLib SDK 中实现用户在线状态的订阅、查询和监听。通过本文档，Flutter 开发者将了解如何获取和跟踪用户在线状态，以及在状态变更时接收通知。
提示
此功能在 5.24.3 版本开始支持。
开通服务
您可以通过控制台开通服务。在融云控制台，选择 IM 服务 > IM 服务管理 > 客户端用户在线状态订阅 ，开启服务。
订阅用户在线状态
为了跟踪特定用户的在线状态，您需要使用 subscribeEvent 方法进行订阅。
- 定义订阅用户 ID 列表：创建一个包含您希望订阅用户 ID 的列表（即单聊的
targetId）。一次订阅的用户上限为 200 个，订阅的用户总数最多为 1000 个，一个用户最多可以被 5000 个用户订阅。 - 设置订阅时间：定义一个整数值，表示订阅持续时间，范围为 60 秒到 2592000 秒。
- 指定订阅类型：使用
RCIMIWSubscribeType.onlineStatus。 - 调用
subscribeEvent执行订阅。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
request | RCIMIWSubscribeEventRequest | 订阅请求 |
callback | IRCIMIWSubscribeEventCallback | 结果回调 |
RCIMIWSubscribeEventRequest 字段
| 字段 | 类型 | 说明 |
|---|---|---|
subscribeType | RCIMIWSubscribeType | 在线状态：onlineStatus(1) |
expiry | int | 订阅时长（秒），范围 [60~2592000] |
userIds | List<String> | 待订阅的用户 ID，单次最多 200 个 |
示例代码：
Dart
final RCIMIWSubscribeEventRequest request = RCIMIWSubscribeEventRequest.create(
subscribeType: RCIMIWSubscribeType.onlineStatus,
expiry: 180000,
userIds: <String>["user1", "user2", "user3"],
);
final IRCIMIWSubscribeEventCallback callback = IRCIMIWSubscribeEventCallback(
onSuccess: () {
// 订阅成功
},
onError: (int? code, List<String>? failedUserIds) {
// 订阅失败
},
);
final int? ret = await engine.subscribeEvent(request, callback: callback);
取消订阅用户在线状态
当您不再需要跟踪用户在线状态时，使用 unSubscribeEvent 取消订阅。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
request | RCIMIWSubscribeEventRequest | 取消订阅请求 |
callback | IRCIMIWSubscribeEventCallback | 结果回调 |
RCIMIWSubscribeEventRequest 字段
| 字段 | 类型 | 说明 |
|---|---|---|
subscribeType | RCIMIWSubscribeType | 在线状态：onlineStatus(1) |
userIds | List<String> | 需取消订阅的用户 ID，单次最多 200 个 |
expiry | int | 无需传（忽略） |
Dart
final RCIMIWSubscribeEventRequest request = RCIMIWSubscribeEventRequest.create(
subscribeType: RCIMIWSubscribeType.onlineStatus,
userIds: <String>["user1", "user2", "user3"],
);
final IRCIMIWSubscribeEventCallback callback = IRCIMIWSubscribeEventCallback(
onSuccess: () {
// 取消订阅成功
},
onError: (int? code, List<String>? failedUserIds) {
// 取消订阅失败
},
);
final int? ret = await engine.unSubscribeEvent(request, callback: callback);
指定用户查询订阅状态信息
使用 querySubscribeEvent 查询指定用户和订阅类型的状态信息。一次最多查询 200 个用户的状态信息。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
request | RCIMIWSubscribeEventRequest | 查询请求 |
callback | IRCIMIWQuerySubscribeEventCallback | 结果回调 |
RCIMIWSubscribeEventRequest 字段
| 字段 | 类型 | 说明 |
|---|---|---|
subscribeType | RCIMIWSubscribeType | 在线状态：onlineStatus(1) |
userIds | List<String> | 待查询的用户 ID，单次最多 200 个 |
expiry | int | 无需传（忽略） |
Dart
final RCIMIWSubscribeEventRequest request = RCIMIWSubscribeEventRequest.create(
subscribeType: RCIMIWSubscribeType.onlineStatus,
userIds: <String>["user1", "user2", "user3"],
);
final IRCIMIWQuerySubscribeEventCallback callback = IRCIMIWQuerySubscribeEventCallback(
onSuccess: (List<RCIMIWSubscribeInfoEvent>? events) {
// 查询成功，返回状态信息
},
onError: (int? code) {
// 查询失败
},
);
final int? ret = await engine.querySubscribeEvent(request, callback: callback);
分页查询已订阅用户的状态信息
如果需要分页获取已订阅的所有事件状态信息，使用 querySubscribeEventByPage，并指定分页大小与起始索引。
pageSize：分页大小 [1~200]startIndex：第一页传 0，下一页传已返回数据总数（例如pageSize = 20，则第二页传 20，第三页传 40）
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
request | RCIMIWSubscribeEventRequest | 查询请求 |
pageSize | int | 分页大小，范围 [1~200] |
startIndex | int | 第一页传 0，下一页传已返回总数 |
callback | IRCIMIWQuerySubscribeEventCallback | 结果回调 |
RCIMIWSubscribeEventRequest 字段
| 字段 | 类型 | 说明 |
|---|---|---|
subscribeType | RCIMIWSubscribeType | 在线状态：onlineStatus(1) |
userIds | List<String> | 无需传（忽略） |
expiry | int | 无需传（忽略） |
Dart
final RCIMIWSubscribeEventRequest request = RCIMIWSubscribeEventRequest.create(
subscribeType: RCIMIWSubscribeType.onlineStatus,
);
const int pageSize = 20;
const int startIndex = 0;
final IRCIMIWQuerySubscribeEventCallback callback = IRCIMIWQuerySubscribeEventCallback(
onSuccess: (List<RCIMIWSubscribeInfoEvent>? events) {
// 查询成功
},
onError: (int? code) {
// 查询失败
},
);
final int? ret = await engine.querySubscribeEventByPage(
request,
pageSize,
startIndex,
callback: callback,
);
监听订阅事件
为接收订阅事件变更通知，需要设置订阅监听器，建议在连接之前设置。
订阅事件的变更需要根据 RCIMIWSubscribeType 处理：等于 onlineStatus 表示在线状态。
参数说明
| 参数/属性 | 类型 | 说明 |
|---|---|---|
onEventChange | Function(List<RCIMIWSubscribeInfoEvent>? subscribeEvents) | 订阅事件变化回调 |
onSubscriptionSyncCompleted | Function(RCIMIWSubscribeType? type) | 订阅数据同步完成回调 |
onSubscriptionChangedOnOtherDevices | Function(List<RCIMIWSubscribeEvent>? subscribeEvents) | 其他设备订阅信息变更回调 |
提示
当前支持类型：在线状态 onlineStatus(1)、用户信息托管 userProfile(2)。
Dart
engine.onEventChange = (List<RCIMIWSubscribeInfoEvent>? subscribeEvents) {
// 在线状态变更
};
engine.onSubscriptionSyncCompleted = (RCIMIWSubscribeType? type) {
// 订阅数据同步完成
};
engine.onSubscriptionChangedOnOtherDevices = (
List<RCIMIWSubscribeEvent>? subscribeEvents,
) {
// 其他设备订阅信息变更
};