Skip to main content

Subscribe to User Online Status

This document guides developers on implementing user online status subscription, querying, and monitoring in the RongCloud IM iOS Client SDK. Through this document, you will learn how to obtain and track other users' online statuses, as well as receive notifications when statuses change.

tip

The user online status subscription feature has been supported since version 5.8.1.

Service Requirements​

This feature is only available with the Chat Pro Plan. Once you purchase the Pro Plan, this feature is automatically available without requiring separate activation.

Monitor Subscription Events​

To promptly receive notifications of subscription event changes, you need to set up a subscription status listener delegate after initializing the IMLib SDK but before connecting to the IMLib SDK. Implement the relevant delegate methods of the RCSubscribeEventDelegate protocol.

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

When handling subscription event change notifications, you need to process the corresponding business based on the RCSubscribeType in the callback method. The online status subscription type is RCSubscribeTypeOnlineStatus.

  • Starting from version 5.10.0, RCSubscribeType includes two types: online status subscription RCSubscribeTypeOnlineStatus (1) and user profile hosting RCSubscribeTypeUserProfile (2).
  • Starting from version 5.12.0, RCSubscribeType adds two new types: friend online status subscription RCSubscribeTypeFriendOnlineStatus (3) and friend user profile hosting RCSubscribeTypeFriendUserProfile (4).

Implement the delegates:

  1. After successfully connecting to IM, the IMLib SDK automatically synchronizes subscription data changes internally. When subscription data is successfully synchronized to the local device or system, the following method is triggered. You can execute subsequent business logic in this method.
/// Deprecated, please use onSubscriptionSyncCompleted: instead
- (void)onSubscriptionSyncCompleted;

/// Subscription data synchronization completed
/// Use type to distinguish between different subscription types. When type equals RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
/// - Since: 5.10.0
- (void)onSubscriptionSyncCompleted:(RCSubscribeType)type;
  1. When subscription events change, you can implement this method to handle event changes, such as updating the user interface or processing new data. Typically, this method is called in a background thread, so you need to switch to the main thread to update the UI. subscribeEvents is a list of subscription events containing all changed events. Note that subscription expiration does not trigger notifications, so you need to monitor the expiration time yourself.
/// Note: Starting from version 5.10.0, you need to check the subscribeType of RCSubscribeInfoEvent. When it equals RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
- (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents;
  1. When a user's subscription information changes on another device, you can update the status information on the current device in this method to ensure consistency of subscription information. subscribeEvents contains a list of changed subscription events.
/// Starting from version 5.10.0, you need to check the subscribeType of RCSubscribeEvent. When it equals RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
- (void)onSubscriptionChangedOnOtherDevices:(NSArray<RCSubscribeEvent *> *)subscribeEvents;

Subscribe to User Online Status​

  1. You need to create a subscription request object RCSubscribeEventRequest, set the subscription type to online status subscription RCSubscribeTypeOnlineStatus, and specify the list of user IDs to subscribe to and the subscription duration.
tip
  • The maximum number of users that can be subscribed to in a single request is 200.
  • The total subscription limit is 1000 users.
  • A single user can be subscribed to by a maximum of 5000 users.
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
request.expiry = 180000;
  1. Call the subscribeEvent:completion: method with the RCSubscribeEventRequest object created in the first step to execute the subscription operation.
[[RCCoreClient sharedCoreClient] subscribeEvent:request 
                                     completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // Subscription successful.
    }
}];

Unsubscribe from User Online Status​

  1. When you no longer need to track the online status of subscribed users, create a subscription request object RCSubscribeEventRequest, set the subscription type to online status subscription RCSubscribeTypeOnlineStatus, and specify the list of user IDs to unsubscribe from.
tip
  • The maximum number of users that can be unsubscribed from in a single request is 200.
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
  1. Call the unSubscribeEvent:completion: method with the RCSubscribeEventRequest object created in the first step to unsubscribe from the online status of all specified users.
[[RCCoreClient sharedCoreClient] unSubscribeEvent:request 
                                       completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // Unsubscription successful.
    }
}];

Query Subscription Status Information for Specified Users​

  1. To query the online subscription status information for specific users, create a subscription request object RCSubscribeEventRequest, set the subscription type to online status subscription RCSubscribeTypeOnlineStatus, and specify the list of user IDs to query.
tip
  • The maximum number of users that can be queried in a single request is 200.
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
request.userIds = @[@"test1",@"test2",@"test3"];
  1. Call the querySubscribeEvent:completion: method with the RCSubscribeEventRequest object created in the first step to query the online subscription status information for all specified users.
[[RCCoreClient sharedCoreClient] querySubscribeEvent:request 
                                          completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
}];

Paginated Query of Online Status Information for All Subscribed Users​

  1. To paginate query the online subscription status information for all subscribed users, create a subscription request object RCSubscribeEventRequest and set the subscription type to online status subscription RCSubscribeTypeOnlineStatus.
RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeOnlineStatus;
  1. Call the querySubscribeEvent:pageSize:startIndex:completion: method with the RCSubscribeEventRequest object created in the first step, and specify the pagination start index and the number of users to query per page.
  • pageSize: The number of users to retrieve per page, ranging from [1~200].
  • startIndex: The starting index. For the first page, pass 0. For the next page, use the total number of records already retrieved (e.g., if pageSize = 20, when retrieving the second page, you have already retrieved 20 records from the first page, so set startIndex to 20; when retrieving the third page, you have already retrieved 40 records from the first two pages, so set startIndex to 40).
[[RCCoreClient sharedCoreClient] querySubscribeEvent:request 
                                            pageSize:20 
                                          startIndex:index 
                                          completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
    if (RC_SUCCESS == status && subscribeEvents.count > 0) {
    }
}];

Query Online Status of Subscribed Users​

tip

This interface has been available since SDK version 5.28.0.

When you need to query the online status of subscribed users, you can use the [getSubscribeUsersOnlineStatus:completion:] method to batch query the online status of multiple users. This method returns detailed online status information for each user across different platforms.

Interface Prototype​



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


#### Parameter Description

| Parameter | Type | Description |
| :-------- | :-------- | :--------- |
| `userIds` | NSArray | User ID collection, limited to [1, 200]. Exceeding this limit or having a length of 0 will return error code 34215 |
| `completion` | Block | Result callback, returns error code and online status array |


#### Return Value RCSubscribeUserOnlineStatus

| Property | Type | Description |
| :-------- | :-------- | :--------- |
| `userId` | NSString | User ID |
| `details` | NSArray | Platform details array containing online status for each platform |
| `isOnline` | BOOL | Online status. Returns `YES` if the user is online on any platform |


#### Return Value RCPlatformOnlineStatus

| Property | Type | Description |
| :-------- | :-------- | :--------- |
| `platform` | [RCPlatform] | Platform type enumeration |
| `isOnline` | BOOL | Whether the user is online on this platform |
| `updateTime` | long long | Status update timestamp (millisecond timestamp) |


#### Example Code

```objectivec
// Create an array of user IDs to query
NSArray *userIds = @[@"user_001", @"user_002"];

// Query online status of subscribed users
[[RCCoreClient sharedCoreClient] getSubscribeUsersOnlineStatus:userIds
                                                     completion:^(RCErrorCode code, NSArray<RCSubscribeUserOnlineStatus *> * _Nonnull status) {
    if (code == RC_SUCCESS) {
        NSLog(@"Successfully retrieved online status for %lu users", (unsigned long)status.count);

        // Iterate through each user's online status
        for (RCSubscribeUserOnlineStatus *userStatus in status) {
            NSLog(@"User %@ online status: %@", userStatus.userId, userStatus.isOnline ? @"Online" : @"Offline");

            // Iterate through detailed platform status for this user
            for (RCPlatformOnlineStatus *platformStatus in userStatus.details) {
                NSLog(@"Platform: %ld, Online: %@, Update time: %lld",
                      (long)platformStatus.platform,
                      platformStatus.isOnline ? @"Yes" : @"No",
                      platformStatus.updateTime);
            }
        }
    } else {
        NSLog(@"Failed to query online status, error code: %ld", (long)code);
    }
}];
[getSubscribeUsersOnlineStatus:completion:]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/zh_CN/documentation/rongimlibcore/rccoreclient/getSubscribeUsersOnlineStatus(_:completion:)?language=objc

[RCSubscribeUserOnlineStatus]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/zh_CN/documentation/rongimlibcore/rcsubscribeuseronlinestatus?language=objc

[RCPlatformOnlineStatus]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/zh_CN/documentation/rongimlibcore/rcplatformonlinestatus?language=objc

[RCPlatform]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/zh_CN/documentation/rongimlibcore/rcplatform?language=objc
Last updated on