跳到主要内容

订阅用户在线状态

本文档旨在指导开发者如何在融云即时通讯 Flutter IMLib SDK 中实现用户在线状态的订阅、查询和监听。通过本文档，Flutter 开发者将了解如何获取和跟踪用户在线状态，以及在状态变更时接收通知。

提示

此功能在 5.24.3 版本开始支持。

开通服务​

您可以通过控制台开通服务。在融云控制台，选择 IM 服务 > IM 服务管理 > 客户端用户在线状态订阅 ，开启服务。

订阅用户在线状态​

为了跟踪特定用户的在线状态，您需要使用 subscribeEvent 方法进行订阅。

  1. 定义订阅用户 ID 列表：创建一个包含您希望订阅用户 ID 的列表（即单聊的 targetId）。一次订阅的用户上限为 200 个，订阅的用户总数最多为 1000 个，一个用户最多可以被 5000 个用户订阅。
  2. 设置订阅时间：定义一个整数值，表示订阅持续时间，范围为 60 秒到 2592000 秒。
  3. 指定订阅类型：使用 RCIMIWSubscribeType.onlineStatus。
  4. 调用 subscribeEvent 执行订阅。

参数说明

参数类型说明
requestRCIMIWSubscribeEventRequest订阅请求
callbackIRCIMIWSubscribeEventCallback结果回调

RCIMIWSubscribeEventRequest 字段

字段类型说明
subscribeTypeRCIMIWSubscribeType在线状态：onlineStatus(1)
expiryint订阅时长（秒），范围 [60~2592000]
userIdsList<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 取消订阅。

参数说明

参数类型说明
requestRCIMIWSubscribeEventRequest取消订阅请求
callbackIRCIMIWSubscribeEventCallback结果回调

RCIMIWSubscribeEventRequest 字段

字段类型说明
subscribeTypeRCIMIWSubscribeType在线状态：onlineStatus(1)
userIdsList<String>需取消订阅的用户 ID，单次最多 200 个
expiryint无需传（忽略）
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 个用户的状态信息。

参数说明

参数类型说明
requestRCIMIWSubscribeEventRequest查询请求
callbackIRCIMIWQuerySubscribeEventCallback结果回调

RCIMIWSubscribeEventRequest 字段

字段类型说明
subscribeTypeRCIMIWSubscribeType在线状态：onlineStatus(1)
userIdsList<String>待查询的用户 ID，单次最多 200 个
expiryint无需传（忽略）
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）

参数说明

参数类型说明
requestRCIMIWSubscribeEventRequest查询请求
pageSizeint分页大小，范围 [1~200]
startIndexint第一页传 0，下一页传已返回总数
callbackIRCIMIWQuerySubscribeEventCallback结果回调

RCIMIWSubscribeEventRequest 字段

字段类型说明
subscribeTypeRCIMIWSubscribeType在线状态：onlineStatus(1)
userIdsList<String>无需传（忽略）
expiryint无需传（忽略）
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 表示在线状态。

参数说明

参数/属性类型说明
onEventChangeFunction(List<RCIMIWSubscribeInfoEvent>? subscribeEvents)订阅事件变化回调
onSubscriptionSyncCompletedFunction(RCIMIWSubscribeType? type)订阅数据同步完成回调
onSubscriptionChangedOnOtherDevicesFunction(List<RCIMIWSubscribeEvent>? subscribeEvents)其他设备订阅信息变更回调
提示

当前支持类型：在线状态 onlineStatus(1)、用户信息托管 userProfile(2)。

Dart
engine.onEventChange = (List<RCIMIWSubscribeInfoEvent>? subscribeEvents) {
  // 在线状态变更
};

engine.onSubscriptionSyncCompleted = (RCIMIWSubscribeType? type) {
  // 订阅数据同步完成
};

engine.onSubscriptionChangedOnOtherDevices = (
  List<RCIMIWSubscribeEvent>? subscribeEvents,
) {
  // 其他设备订阅信息变更
};
最后于 更新