跳到主要内容

订阅用户在线状态

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

提示

订阅用户在线状态功能在 5.8.1 版本开始支持。

开通服务​

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

开通客户端在线状态订阅

监听订阅事件​

为了及时接收订阅事件的变更通知，你需要在应用调用 IMLib SDK 的初始化之后，且在调用 IMLib SDK 的连接之前，设置订阅在线状态监听器的代理委托，并实现 RCSubscribeEventDelegate 协议的相关代理方法。

Objective C
[[RCCoreClient sharedCoreClient] addSubscribeEventDelegate:self];
[[RCCoreClient sharedCoreClient] removeSubscribeEventDelegate:self];
提示

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

  • 从 5.10.0 版本开始，RCSubscribeType 包含了在线状态订阅 RCSubscribeTypeOnlineStatus (1)、用户信息托管 RCSubscribeTypeUserProfile (2) 这2种类型。
  • 从 5.12.0 版本开始，RCSubscribeType 新增了好友在线状态订阅 RCSubscribeTypeFriendOnlineStatus (3)、好友用户信息托管 RCSubscribeTypeFriendUserProfile (4) 这2种类型。

实现代理：

  1. 您在连接 IM 成功后，IMLib SDK 内部会自动同步订阅数据的变动。当订阅数据成功同步到本地设备或系统后，会触发下面的方法，您可以在此方法中执行后续业务逻辑。

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

    /// 订阅数据同步完成
    /// 使用 type 区分不同的订阅类型，等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
    /// - Since: 5.10.0
    - (void)onSubscriptionSyncCompleted:(RCSubscribeType)type;

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

    Objective C
    /// 注意：从 5.10.0 版本开始，需要判断 RCSubscribeInfoEvent 的 subscribeType，等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
    - (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents;

  3. 当用户在其他设备上的订阅信息发生变更时，您可以在当前设备的此方法中更新当前设备上的状态信息，以保证订阅信息的一致性。 subscribeEvents 包含发生变化的订阅事件的列表。

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

订阅用户在线状态​

  1. 您需要创建订阅请求对象 RCSubscribeEventRequest，设置订阅类型为订阅在线状态 RCSubscribeTypeOnlineStatus， 并设置好需要订阅的所有用户的 userId 列表和订阅时长。
提示
  • 单次订阅的用户的上限为 200 个用户。
  • 总订阅上限为 1000 个用户。
  • 单个用户最多可被 5000 个用户订阅。
Objective C
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
request.expiry = 180000;
  1. 您通过调用 subscribeEvent:completion: 方法传入第一步设置好的 RCSubscribeEventRequest 对象执行订阅操作。
Objective C

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

取消订阅用户在线状态​

  1. 当您不再需要跟踪已被订阅用户的在线状态时,您需要创建订阅请求对象 RCSubscribeEventRequest，设置订阅类型为订阅在线状态 RCSubscribeTypeOnlineStatus，并设置好需要取消订阅在线状态的所有用户的 userId 列表。
提示
  • 单次取消订阅的用户的上限为 200 个用户。
Objective C
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
  1. 您通过调用 unSubscribeEvent:completion: 方法传入第一步设置好的 RCSubscribeEventRequest 对象取消对传入的所有用户的在线状态的订阅。
Objective C
[[RCCoreClient sharedCoreClient] unSubscribeEvent:request
                                       completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // 取消订阅成功。
    }
}];

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

  1. 当您需要查询指定用户的在线订阅类型的状态信息时，您需要创建订阅请求对象 RCSubscribeEventRequest，设置订阅类型为订阅在线状态 RCSubscribeTypeOnlineStatus，并设置好需要查询订阅在线状态的所有用户的 userId 列表。
提示
  • 单次查询订阅的用户的上限为 200 个用户。
Objective C
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
  1. 您通过调用 querySubscribeEvent:completion: 方法传入第一步设置好的 RCSubscribeEventRequest 对象查询传入的所有用户的在线订阅类型的相关状态信息。
Objective C
[[RCCoreClient sharedCoreClient] querySubscribeEvent:request
                                          completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
}];

分页查询已订阅所有用户的在线状态信息​

  1. 当您需要分页查询所有已订阅用户的在线订阅类型的状态信息时，您需要创建订阅请求对象 RCSubscribeEventRequest，设置订阅类型为订阅在线状态 RCSubscribeTypeOnlineStatus。
Objective C
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
  1. 您通过调用 querySubscribeEvent:pageSize:startIndex:completion:方法传入第一步设置好的 RCSubscribeEventRequest 对象，同时设置好每次查询的分页的起始的值以及每页需要查询的用户的数量。
  • pageSize: 每页获取的用户的数量，取值范围为[1~200]。
  • startIndex: 起始索引。第一页传 0， 下一页取已经获取到的所有数据的数组数量（比如 pageSize = 20，当获取第二页时，您已经获取到了第一页的 20 条数据，所以 startIndex 设置为 20；当获取第三页时，您已经获取到了前两页的 40 条数据，所以 startIndex 设置为 40。
Objective C
[[RCCoreClient sharedCoreClient] querySubscribeEvent:request
                                            pageSize:20
                                          startIndex:index
                                          completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
    if (RC_SUCCESS == status && subscribeEvents.count > 0) {
    }
}];

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

提示

SDK 从 5.28.0 版本开始提供该接口。

当您需要查询已订阅用户的在线状态信息时，可以使用 getSubscribeUsersOnlineStatus:completion: 方法批量查询多个用户的在线状态。该方法会返回每个用户在各个平台的详细在线状态。

接口原型​

Objective C
- (void)getSubscribeUsersOnlineStatus:(NSArray<NSString *> *)userIds
                           completion:(nullable void(^)(RCErrorCode code, NSArray<RCSubscribeUserOnlineStatus *> *status))completion;

参数说明​

参数类型说明
userIdsNSArray用户 ID 集合，限制范围在 [1, 200]，超出限制或长度为 0 会返回错误码 34215
completionBlock结果回调，返回错误码和在线状态数组

返回值 RCSubscribeUserOnlineStatus​

属性类型说明
userIdNSString用户 ID
detailsNSArray平台详细信息数组，包含各平台的在线状态
isOnlineBOOL是否在线，只要有一个平台在线，该值就为 YES

返回值 RCPlatformOnlineStatus​

属性类型说明
platformRCPlatform平台类型枚举
isOnlineBOOL该平台是否在线
updateTimelong long状态更新时间（毫秒时间戳）

示例代码​

Objective C
// 创建要查询的用户 ID 数组
NSArray *userIds = @[@"user_001", @"user_002"];

// 查询已订阅用户的在线状态
[[RCCoreClient sharedCoreClient] getSubscribeUsersOnlineStatus:userIds
                                                     completion:^(RCErrorCode code, NSArray<RCSubscribeUserOnlineStatus *> * _Nonnull status) {
    if (code == RC_SUCCESS) {
        NSLog(@"成功获取在线状态，用户数量：%lu", (unsigned long)status.count);

        // 遍历每个用户的在线状态
        for (RCSubscribeUserOnlineStatus *userStatus in status) {
            NSLog(@"用户 %@ 在线状态：%@", userStatus.userId, userStatus.isOnline ? @"在线" : @"离线");

            // 遍历该用户在各平台的详细状态
            for (RCPlatformOnlineStatus *platformStatus in userStatus.details) {
                NSLog(@"平台：%ld，在线：%@，更新时间：%lld",
                      (long)platformStatus.platform,
                      platformStatus.isOnline ? @"是" : @"否",
                      platformStatus.updateTime);
            }
        }
    } else {
        NSLog(@"查询在线状态失败，错误码：%ld", (long)code);
    }
}];