Subscribe to Online Status

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

Note This feature is supported starting from version 5.9.8.

Activate the Service

You can activate 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 subscribeUserStatus method. Below are the detailed steps and sample code:

1. Define the list of user IDs to subscribe to: Create an array 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 at once is 200, with a total subscription limit of 1000 users. A single user can be subscribed to by up to 5000 users.
2. Set the subscription duration: Define a time value representing the duration of the subscription, ranging from 60 seconds to 2592000 seconds.
3. Specify the subscription type: Use RongIMLib.SubscribeType.ONLINE_STATUS to indicate that you are subscribing to the user's online status.
4. Execute the subscription operation using the subscribeUserStatus method.

// List of user IDs to subscribe to, which are also the targetId for one-to-one chat (maximum of 200 users per subscription).
const userIds = ['user1', 'user2']
// Set the subscription duration, ranging from [60,2592000] (unit: seconds).
const expiry=180000;
// Specify the subscription type as user online status.
const type = RongIMLib.SubscribeType.ONLINE_STATUS

RongIMLib.subscribeUserStatus(userIds, type, expiry).then((res) => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('Subscription successful')
  } else if (res.code === RongIMLib.ErrorCode.RC_BESUBSCRIBED_USERIDS_COUNT_EXCEED_LIMIT) {
    console.log('User subscription limit exceeded', res.code, res.data)
  } else {
    console.log('Subscription failed', res.code, res.msg)
  }
})

Unsubscribe from User Online Status

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

// List of user IDs to unsubscribe from, which are also the targetId for one-to-one chat (maximum of 200 users per unsubscribe).
const userIds = ['user1', 'user2']
// Specify the subscription type to unsubscribe from.
const type = RongIMLib.SubscribeType.ONLINE_STATUS

RongIMLib.unSubscribeUserStatus(userIds, type).then((res) => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('Unsubscription successful')
  } else {
    console.log('Unsubscription failed', res.code, res.msg)
  }
})

Query Subscription Status Information

You can use the getSubscribeUserStatus method to query the status information of specified users and subscription types. The maximum number of users you can query at once is 200.

// Specify the user IDs to query, which are also the targetId for one-to-one chat. The maximum number of users you can query at once is 200.
const userIds = ['user1', 'user2']
// Specify the subscription type to query.
const type = RongIMLib.SubscribeType.ONLINE_STATUS

RongIMLib.getSubscribeUserStatus(type, userIds).then((res) => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('Query successful', res.data)
  } else {
    console.log('Query failed', res.code, res.msg)
  }
})

Paginated Query of Subscribed User Status Information

If you need to paginate through the status information of all subscribed events, you can use the getSubscribeUserList method.

// Specify the subscription type to query.
const type = RongIMLib.SubscribeType.ONLINE_STATUS
// Set the page size, ranging from [1~200].
const pageSize = 20
// Set the page offset. The offset constant is used to control the starting position of the query. For the first query (i.e., the first page), it should be set to 0. For subsequent queries (e.g., fetching data for the second or third page), the offset should be set to the cumulative value of the data array count returned from the previous page. For example, if the offset for the first page is 0 and the pageSize is 20, the offset for the second page should be 20, and for the third page, it should be 40.
const offset = 0

RongIMLib.getSubscribeUserList(type, pageSize, offset).then((res) => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('Query successful', res.data)
  } else {
    console.log('Query failed', res.code, res.msg)
  }
})

Listen to Subscription Events

To receive notifications of subscription event changes, you need to set up a subscription listener. Use addEventListener to add a listener for the SUBSCRIBED_USER_STATUS_CHANGE event. The listener needs to be called before establishing a connection.

tip

• Starting from version 5.10.1, subscription events include user online status and user profile hosting types. Changes in subscription events need to be handled according to the subscribeType.
• Starting from version 5.12.0, SubscribeType has added two new types: friend online status subscription FRIEND_ONLINE_STATUS(3) and friend user profile hosting FRIEND_USER_PROFILE(4).

Subscribe to User Status Changes

/**
 * You will receive this notification when the status of a subscribed user changes.
 * After the subscription expires, the RC SDK will not actively notify you. Please monitor the expiration time yourself.
 */
RongIMLib.addEventListener(Events.SUBSCRIBED_USER_STATUS_CHANGE, (event) => {
  // Starting from version 5.10.1, you need to determine whether it is user profile or online status based on the subscribeType in the data.
  console.log('Subscribed user status changed', event)
})

Subscription Relationship Changes (Multi-device Sync)

/**
 * You will receive this notification when subscription information changes on other devices.
 * This can be used to update the user status on the current device, ensuring consistency in subscription information.
 */
RongIMLib.addEventListener(Events.SUBSCRIBED_RELATION_CHANGE, (event) => {
  // Starting from version 5.10.1, you need to determine whether it is user profile or online status based on the subscribeType in the data.
  console.log('Subscription relationship changed', event)
})

Subscription Data Sync Completed

/**
 * Subscription data sync completed.
 * You will receive this notification after the subscription data is successfully synced to the device or system, allowing you to perform subsequent business operations.
 */
RongIMLib.addEventListener(Events.SYNC_SUBSCRIBED_USER_STATUS_FINISHED, (event) => {
  // Starting from version 5.10.1, you need to determine whether it is user profile or online status based on the subscribeType in the data.
  console.log('Subscription data synced', event)
})