订阅用户在线状态
本文档旨在指导开发者如何在融云即时通讯 iOS 客户端 SDK 中实现用户在线 状态的订阅、查询和监听。通过本文档,开发者将了解如何获取和跟踪用户在线状态,以及如何在状态变更时接收通知。
此功能在 5.8.1 版本开始支持。
开通服务
您可以通过控制台开通服务。在融云控制台,选择 IM 服务 > IM 服务管理 > 客户端用户在线状态订阅 ,开启服务。
订阅用户在线状态
- 导入 SDK 头文件。
#import <RongIMLibCore/RongIMLibCore.h>
- 创建
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];
实现代理:
-
当订阅事件发生变化时,以下方法将被调用。您可以通过实现此方法来处理事件的变化,例如更新用户界面或处理新的数据。通常,该方法在后台线程中被调用,因此更新UI时需要切换到主线程。
subscribeEvents
是订阅事件的列表,包含所有发生变化的事件。 请注意,订阅过期没有通知, 您需自行关注过期时间。/// 注意:从 5.10.0 版本开始,需要判断 RCSubscribeInfoEvent 的 subscribeType,等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
- (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents; -
订阅数据同步完成。当订阅数据成功同步到本地设备或系统后,将调用此方法来执行后续业务逻辑。
/// 已废弃,请使用 onSubscriptionSyncCompleted: 代替
- (void)onSubscriptionSyncCompleted;
/// 订阅数据同步完成
/// 使用 type 区分不同的订阅类型,等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
/// - Since: 5.10.0
- (void)onSubscriptionSyncCompleted:(RCSubscribeType)type; -
远程设备订阅信息变更。当用户在其他设备上的订阅信息发生变更时,此方法将被调用。您可以利用这个方法来更新当前设备上的状态信息,以保证订阅信息的一致性。
subscribeEvents
包含发生变化的订阅事件的列表。/// 从 5.10.0 版本开始,需要判断 RCSubscribeEvent 的 subscribeType,等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
- (void)onSubscriptionChangedOnOtherDevices:(NSArray<RCSubscribeEvent *> *)subscribeEvents;