Subscribe to User Online Status

This document aims to guide developers on how to implement the subscription, querying, and monitoring of user online status in the RC Instant Messaging Android Client SDK. Through this document, Android 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.

Enable the Service

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

Subscribe to User Online Status

To track the online status of specific users, you need to use the subscribeEvent method to subscribe.

1. Define the list of user IDs to subscribe to: Create an ArrayList containing the user IDs you wish to subscribe to, i.e., the targetId for one-to-one chat. The maximum number of users you can subscribe to in one go is 200, and the total number of users you can subscribe to is 1000. A single user can be subscribed to by up to 5000 users.
2. Set the subscription duration: Define an integer value representing the duration of the subscription, which ranges from 60 seconds to 2592000 seconds.
3. Specify the subscription type: Use SubscribeEvent.SubscribeType.ONLINE_STATUS to indicate that you are subscribing to the user's online status.
4. Execute the subscription operation using the subscribeEvent method.

Sample Code

// Set the subscription type.
SubscribeEvent.SubscribeType type= SubscribeEvent.SubscribeType.ONLINE_STATUS;
// Set the subscription duration, ranging from [60,2592000] (unit: seconds).
int expiry=180000;
// Subscribe to user userId, i.e., the targetId for one-to-one chat (maximum of 200 users per subscription).
List<String> userList=new ArrayList<>();
userList.add("user1");
userList.add("user2");
userList.add("user3");
SubscribeEventRequest request = new SubscribeEventRequest(type,expiry,userList);
RongCoreClient.getInstance().subscribeEvent(request, new IRongCoreCallback.SubscribeEventCallback<List<String>>() {
    @Override
    public void onSuccess() {
        // Subscription successful.
    }

    @Override
    public void onError(int errorCode, List<String> strings) {
        // Subscription failed.
    }
});

Unsubscribe from User Online Status

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

// Set the type of subscription to unsubscribe from.
SubscribeEvent.SubscribeType type= SubscribeEvent.SubscribeType.ONLINE_STATUS;
// Unsubscribe from user userId, i.e., the targetId for one-to-one chat, with a maximum of 200 users per unsubscription.
List<String> userList=new ArrayList<>();
userList.add("user1");
userList.add("user2");
userList.add("user3");
SubscribeEventRequest request = new SubscribeEventRequest(type,userList);
RongCoreClient.getInstance().unSubscribeEvent(request, new IRongCoreCallback.SubscribeEventCallback<List<String>>() {
    @Override
    public void onSuccess() {
        // Unsubscription successful.
    }

    @Override
    public void onError(int errorCode, List<String> strings) {
        // Unsubscription failed.
    }
});

Query Subscription Status Information for Specified Users

You can use the querySubscribeEvent method to query the status information of specified users and subscription types. You can query the status information of up to 200 users at a time.

// Set the query type.
SubscribeEvent.SubscribeType type= SubscribeEvent.SubscribeType.ONLINE_STATUS;
// Query user online status.
List<String> userList=new ArrayList<>();
userList.add("user1");
userList.add("user2");
userList.add("user3");
SubscribeEventRequest request = new SubscribeEventRequest(type,userList);
RongCoreClient.getInstance().querySubscribeEvent(request, new IRongCoreCallback.ResultCallback<List<SubscribeInfoEvent>>() {
    @Override
    public void onSuccess(List<SubscribeInfoEvent> subscribeInfoEvents) {
        // Query successful, returns the queried user information.
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Query failed.
    }
});

Paginated Query of Subscribed Users' Status Information

If you need to paginate through all the subscribed event status information, you can use the querySubscribeEvent method and specify the page size and start index.

• Parameter pageSize: Page size [1~200].
• Parameter startIndex: For the first page, pass 0. For the next page, pass the number of all data returned in the array (e.g., if pageSize = 20, pass 20 for the second page, 40 for the third page).

// Query type
SubscribeEvent.SubscribeType type= SubscribeEvent.SubscribeType.ONLINE_STATUS;
SubscribeEventRequest request = new SubscribeEventRequest(type);
// Page size, ranging from [1,200].
int pageSize=20;
// Start index for pagination. For the first page, pass 0. For the next page, pass the number of all data returned in the array, e.g., if pageSize = 20, pass 20 for the second page, 40 for the third page.
int startIndex=0;
RongCoreClient.getInstance().querySubscribeEvent(request,pageSize,startIndex, new IRongCoreCallback.ResultCallback<List<SubscribeInfoEvent>>() {
    @Override
    public void onSuccess(List<SubscribeInfoEvent> subscribeInfoEvents) {
        // Query successful, returns the queried user information.
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Query failed.
    }
});

Listen to Subscription Events

To receive notifications of subscription event changes, you need to set up a subscription listener. The listener needs to be called before connecting.

Subscription event changes need to be handled according to the SubscribeType. When it equals ONLINE_STATUS, it represents the online status.

tip

• Starting from version 5.10.0, SubscribeType includes online status subscription ONLINE_STATUS(1) and user profile hosting USER_PROFILE(2).
• Starting from version 5.12.0, SubscribeType adds friend online status subscription FRIEND_ONLINE_STATUS(3) and friend user profile hosting FRIEND_USER_PROFILE(4).

RongCoreClient.getInstance().addSubscribeEventListener(new OnSubscribeEventListener() {
    /**
     * @param subscribeEvents The list of subscription events, containing all events that have changed.
     * When the status of the subscribed user changes, SubscribeEvent.operationType has no value.
     * There is no notification for subscription expiration; developers need to monitor the expiration time themselves.
     * Note: You need to check the SubscribeType of SubscribeInfoEvent. When it equals ONLINE_STATUS, it represents the online status.
     */
    @Override
    public void onEventChange(List<SubscribeInfoEvent> subscribeEvents) {

    }

    /**
     * Subscription data synchronization completed.
     * This method is called after the subscription data is successfully synchronized to the device or system, for subsequent processing.
     * @deprecated Deprecated. Please use {@link #onSubscriptionSyncCompleted(SubscribeEvent.SubscribeType)}
     */
    @Override
    public void onSubscriptionSyncCompleted() {

    }

    /**
     * Marks the completion of subscription data synchronization. This method is called after the subscription data is successfully synchronized to the device or system, for subsequent processing.
     * Note: You need to check the SubscribeType. When it equals ONLINE_STATUS, it represents the online status.
     *
     * @param type The type of synchronization completed. You need to determine the specific business based on the type.
     * @since 5.10.0
     */
    @Override
    public void onSubscriptionSyncCompleted(SubscribeEvent.SubscribeType type) {

    }

    /**
     * This method is called when the subscription information of the user changes on other devices.
     * This can be used to update the user status on the current device, ensuring the consistency of subscription information.
     * Note: You need to check the SubscribeType of SubscribeInfoEvent. When it equals ONLINE_STATUS, it represents the online status.
     * @param subscribeEvents The list of subscription events
     */
    @Override
    public void onSubscriptionChangedOnOtherDevices(List<SubscribeEvent> subscribeEvents) {

    }
});