跳到主要内容

订阅用户在线状态

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

提示

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

开通服务

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

开通客户端在线状态订阅

订阅用户在线状态

  1. 导入 SDK 头文件。
#import <RongIMLibCore/RongIMLibCore.h>
  1. 创建 RCSubscribeEventRequest 对象,设置订阅类型为 RCSubscribeTypeOnlineStatus, 订阅用户 ID 列表和订阅时长。一次订阅用户的上限为 200 个, 订阅的用户数最多为 1000 个,一个用户最多可以被 5000 个用户订阅。
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
request.expiry = 180000;

3. 执行订阅操作。

[[RCCoreClient sharedCoreClient] subscribeEvent:request
completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
if (RC_SUCCESS == status) {
// 订阅成功。
}
}];

取消订阅用户在线状态

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

示例代码

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];

[[RCCoreClient sharedCoreClient] unSubscribeEvent:request
completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
if (RC_SUCCESS == status) {
// 取消订阅成功。
}
}];

查询订阅状态信息

您可以使用querySubscribeEvent:completion:方法查询指定用户和订阅类型的状态信息。

示例代码

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];

[[RCCoreClient sharedCoreClient] querySubscribeEvent:request
completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
}];

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

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

  • pageSize: 分页大小,取值范围为[1~200]。
  • startIndex: 起始索引。第一页传 0, 下一页取返回所有数据的数组数量(比如 pageSize = 20,第二页传 20,第三页传40)。

示例代码

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;

[[RCCoreClient sharedCoreClient] querySubscribeEvent:request
pageSize:2
startIndex:index
completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
if (RC_SUCCESS == status && subscribeEvents.count > 0) {
}
}];

监听订阅事件

为了接收订阅事件的变更通知,您需要设置订阅监听器。实现此功能需要开发者遵守 RCSubscribeEventDelegate 协议。

提示

从 5.10.0 版本开始,订阅事件包含了用户在线状态用户信息托管两种种类型,订阅事件的变更,需要根据 RCSubscribeType 的类型来处理对应的业务。

在应用初始化之后,建立连接之前,您需要设置监听器的代理委托。

[[RCCoreClient sharedCoreClient] addSubscribeEventDelegate:self];
[[RCCoreClient sharedCoreClient] removeSubscribeEventDelegate:self];

实现代理:

  1. 当订阅事件发生变化时,以下方法将被调用。您可以通过实现此方法来处理事件的变化,例如更新用户界面或处理新的数据。通常,该方法在后台线程中被调用,因此更新UI时需要切换到主线程。subscribeEvents 是订阅事件的列表,包含所有发生变化的事件。 请注意,订阅过期没有通知, 您需自行关注过期时间。

    /// 注意:从 5.10.0 版本开始,需要判断 RCSubscribeInfoEvent 的 subscribeType,等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
    - (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents;
  2. 订阅数据同步完成。当订阅数据成功同步到本地设备或系统后,将调用此方法来执行后续业务逻辑。

    /// 已废弃,请使用 onSubscriptionSyncCompleted: 代替
    - (void)onSubscriptionSyncCompleted;

    /// 订阅数据同步完成
    /// 使用 type 区分不同的订阅类型,等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
    /// - Since: 5.10.0
    - (void)onSubscriptionSyncCompleted:(RCSubscribeType)type;
  3. 远程设备订阅信息变更。当用户在其他设备上的订阅信息发生变更时,此方法将被调用。您可以利用这个方法来更新当前设备上的状态信息,以保证订阅信息的一致性。 subscribeEvents 包含发生变化的订阅事件的列表。

    /// 从 5.10.0 版本开始,需要判断 RCSubscribeEvent 的 subscribeType,等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
    - (void)onSubscriptionChangedOnOtherDevices:(NSArray<RCSubscribeEvent *> *)subscribeEvents;