Subscription User Status

This document guides developers on how to implement user online status subscription, query, and monitoring in the RC Instant Messaging iOS Client SDK. Through this document, developers will learn how to obtain and track user online status, as well as receive notifications when the status changes.

tip

This feature is supported starting from version 5.8.1.

Activate Service

You can activate the service through the Console. In the RC Console, select Chat settings > Chat pricing plans > Subscription User Status, and enable the service.

Subscribe to User Online Status

1. Import the SDK header file.

#import <RongIMLibCore/RongIMLibCore.h>

2. Create an RCSubscribeEventRequest object, set the subscription type to RCSubscribeTypeOnlineStatus, the list of user IDs to subscribe to, and the subscription duration. The maximum number of users that can be subscribed to in one request is 200, and the total number of users that can be subscribed to is 1000. A single user can be subscribed to by up to 5000 users.

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

3. 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

When you no longer need to track a user's online status, you can use the unSubscribeEvent:completion: method to unsubscribe.

Sample Code

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) {
        // Unsubscription successful.
    }
}];

Query Subscription Status Information

You can use the querySubscribeEvent:completion: method to query the status information of specified users and subscription types.

Sample Code

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

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

Paginated Query of Subscribed User Status Information

If you need to paginate through all subscribed event status information, you can use the querySubscribeEvent:pageSize:startIndex:completion: method, specifying the page size and start index.

• pageSize: The page size, ranging from [1~200].
• startIndex: The start index. Pass 0 for the first page, and for the next page, pass the total number of data returned in the array (e.g., if pageSize = 20, pass 20 for the second page, 40 for the third page).

Sample Code

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) {
    }
}];

Listen to Subscription Events

To receive notifications of subscription event changes, you need to set up a subscription listener. Implementing this functionality requires developers to conform to the RCSubscribeEventDelegate protocol.

tip

Subscription event changes need to be handled based on the type of RCSubscribeType.

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

After initializing the application and before establishing a connection, you need to set the delegate for the listener.

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

Implement the delegate:

1. When a subscription event changes, the following method will be called. 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 when updating the UI. subscribeEvents is a list of subscription events, containing all events that have changed. Note that there is no notification for subscription expiration; 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;

2. Subscription data synchronization completed. When subscription data is successfully synchronized to the local device or system, this method will be called to execute subsequent business logic.

   /// Deprecated, please use onSubscriptionSyncCompleted: instead
   - (void)onSubscriptionSyncCompleted;
   
   /// Subscription data synchronization completed
   /// Use type to distinguish different subscription types. When it equals RCSubscribeTypeOnlineStatus, it represents an online status subscription event.
   /// - Since: 5.10.0
   - (void)onSubscriptionSyncCompleted:(RCSubscribeType)type;

3. Remote device subscription information changed. When a user's subscription information changes on another device, this method will be called. You can use this method to update the status information on the current device to ensure consistency of subscription information. subscribeEvents contains a list of subscription events that have changed.

   /// 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;