跳到主要内容

订阅用户在线状态

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

提示

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

开通服务​

您可以通过融云控制台 IM 服务的服务购买页面开通客户端用户在线状态订阅服务。

开通客户端在线状态订阅

监听订阅事件​

为了及时接收订阅事件的变更通知，您需要在应用调用 IMLib SDK 的初始化之后，且在调用 IMLib SDK 的连接之前，设置订阅在线状态监听器。

您在处理订阅事件变更的通知时，需要根据回调方法中的 SubscribeType 的类型来处理对应的业务。在线订阅状态的类型为 SubscribeTypeOnlineStatus。

提示

从 25.12.0 版本开始，SubscribeType 包含了在线状态订阅 SubscribeTypeOnlineStatus(1)、用户信息托管 SubscribeTypeUserProfile(2)、好友在线状态订阅 SubscribeTypeFriendOnlineStatus(3)、好友用户信息托管 SubscribeTypeFriendUserProfile(4) 这四种类型。

TypeScript
let listener: SubscribeEventListener = {
  onEventChange : (events: Array<SubscribeInfoEvent>) => {
    // 订阅事件变化
  },
  onSubscriptionSyncCompleted : (type: SubscribeType) => {
    // 订阅同步完成
  },
  onSubscriptionChangedOnOtherDevices : (events: Array<SubscribeEvent>) => {
    // 订阅在其他设备上发生变化
  }
}
IMEngine.getInstance().addSubscribeEventListener(listener);

订阅用户在线状态​

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

  1. 您需要创建订阅请求对象 SubscribeEventRequest，设置订阅类型为订阅在线状态 SubscribeTypeOnlineStatus， 并设置好需要订阅的所有用户的 userId 列表和订阅时长。
提示
  • 单次订阅的用户的上限为 200 个用户。
  • 总订阅上限为 1000 个用户。
  • 设置订阅时间：定义一个整数值，该值表示订阅的持续时间，订阅时长的范围为 60 秒到 2592000 秒。
  • 单个用户最多可被 5000 个用户订阅。

示例代码​

TypeScript
// 设置订阅类型
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeOnlineStatus;
// 设置订阅时间，取值范围为 [60, 2592000]（单位：秒）
let expiry: number = 180000;
// 订阅用户 userId，即单聊的 targetId（一次最多订阅 200 个）
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
IMEngine.getInstance().subscribeEvent(request).then((result: IAsyncResult<Array<String>>) => {
  if (result.code === EngineError.Success) {
    // 订阅用户在线状态完成
  } else {
    // 订阅用户在线状态失败
  }
});

批量查询已订阅用户的在线状态​

批量查询已订阅用户的在线状态。开通"客户端好友在线状态变更通知"功能后，支持查询当前用户指定好友的当前在线状态。

提示

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

示例代码​

TypeScript
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
IMEngine.getInstance().getSubscribeUsersOnlineStatus(userIds).then((result: IAsyncResult<Array<SubscribeUserOnlineStatus>>) => {
  if (result.code === EngineError.Success) {
    // 获取用户在线状态完成
  } else {
    // 获取用户在线状态失败
  }
});

取消订阅用户在线状态​

当您不再需要跟踪用户的在线状态时，可以使用 unsubscribeEvent 方法取消订阅。

示例代码​

TypeScript
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeOnlineStatus;
let expiry: number = 60;
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
IMEngine.getInstance().unsubscribeEvent(request).then((result: IAsyncResult<Array<String>>) => {
  if (result.code === EngineError.Success) {
    // 取消订阅用户在线状态完成
  } else {
    // 取消订阅用户在线状态失败
  }
});

查询指定用户订阅状态信息​

您可以使用 querySubscribeEvent 方法查询指定用户和订阅类型的状态信息。一次最多查询 200 个用户的状态信息。

示例代码​

TypeScript
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeOnlineStatus;
let expiry: number = 60;
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
IMEngine.getInstance().querySubscribeEvent(request).then((result: IAsyncResult<Array<SubscribeInfoEvent>>) => {
  if (result.code === EngineError.Success) {
    // 查询用户在线状态订阅信息完成
  } else {
    // 查询用户在线状态订阅信息失败
  }
});

分页查询已订阅用户的状态信息​

如果您需要分页获取已订阅的所有事件状态信息，可以使用 querySubscribeEventByPage 方法，并指定分页大小和起始索引。

  • pageSize：分页大小 [1~200]。
  • startIndex：第一页传 0，下一页取返回所有数据的数组数量（比如 pageSize = 20，第二页传 20，第三页传 40）。

示例代码​

TypeScript
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeOnlineStatus;
let expiry: number = 60;
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
let pageSize = 10;
let startIndex = 0;
IMEngine.getInstance().querySubscribeEventByPage(request, pageSize, startIndex).then((result: IAsyncResult<Array<SubscribeInfoEvent>>) => {
  if (result.code === EngineError.Success) {
    // 分页查询用户在线状态订阅信息完成
  } else {
    // 分页查询用户在线状态订阅信息失败
  }
});
最后于 更新