logo
Console
In-app Chat
Web: JS
Introduction
Sample code
Send and receive messages
Client SDKs
Guides
Offline push notifications
SDK Error Codes
Migration solution
API Reference
Powered Byspreading
On this page

Online Status Subscription

Note

To use this feature, please subscribe to the enterprise plan.

Introduction

User online statuses ZIMUserOnlineStatus include three types: online, logout, and offline.

  • Online: When the user actively calls the login method to log in and maintains a network connection, the user's status changes to online.
  • Logout: After the user actively calls the logout method, the user's status changes to logout.
  • Offline: After the user logs in by calling the login method, if the user kills the app or locks the screen, or the app is in the background, causing the network to disconnect, the user's status changes to offline.

This article introduces how to subscribe to and query users' online statuses.

Subscribe to user online statuses

To continuously monitor the online status of certain users, you can call the subscribeUsersStatus method and pass the target user IDs in the userIDs parameter (up to 100 registered users, excluding the subscriber itself). You also need to pass the subscriptionDuration in the config (during which the online status changes of the target users will be continuously monitored), so that the target users can be added in the subscriber's online status subscription list.

Note
  • A user can subscribe to up to 3,000 people. When the number of subscribed users exceeds 3,000, the earliest subscribed users will be replaced.
  • After a user subscribing to another user's online status, the subscription remains valid even if the user logs out and logs back in within the subscriptionDuration period. There's no need to resubscribe.
Untitled
// Create the subscription configuration
const config = {
    subscriptionDuration: 60, // Subscription duration in minutes, valid range is 1 to 43200 (30 days)

};

// Subscription user ID list
const userIDs = ['userIdA', 'userIdB'];

try {
    // Call the subscribeUsersStatus method
    const result = await zim.subscribeUsersStatus(userIDs, config);

    // Check for users with failed subscriptions
    if (result.errorUserList.length > 0) {
        result.errorUserList.forEach((errorUserInfo) => {
            console.log('User ID with failed subscription: ', errorUserInfo.userID);
            console.log('Error code for failed subscription: ', errorUserInfo.reason);
        });
    } else {
        console.log('All users subscribed successfully!');
    }
} catch (error) {
    // Catch the exception and handle the error code
    console.error('Error occurred while subscribing:', error);
}
1
Copied!

Event notification

Subsequently, the online status changes of the target users within the specified subscriptionDuration will be returned through the userStatusUpdated event callback registered by the on method.

Note

If the user logs off and then logs back in after subscribing, the ZIM SDK will proactively notify the user via the callback about the last status changes of the subscribed target users during the user’s offline period.

Untitled
// Listen for the user status update event
zim.on('userStatusUpdated', function (zim, { userStatusList }) {
    userStatusList.forEach((userStatus) => {
        const { userID, onlineStatus, onlinePlatforms, lastUpdateTime } = userStatus;

        console.log('userStatusUpdated:', userID, onlineStatus, onlinePlatforms, lastUpdateTime);

        // Handle the logic after user status update here, such as updating UI or other operations
    });
});
1
Copied!

Unsubscribe from user online statuses

If you no longer need to monitor the online status of certain users, you can call the unsubscribeUsersStatus method and pass the target user IDs in the userIDs parameter (up to 100 users).

Untitled
// List of user IDs to unsubscribe
const userIDs = ['userIdA', 'userIdB'];

try {
    // Call the unsubscribeUsersStatus method
    const result = await zim.unsubscribeUsersStatus(userIDs);
// Check for users who could not be unsubscribed
if (result.errorUserList.length > 0) {
    result.errorUserList.forEach((errorUserInfo) => {
        console.log('User ID of failed unsubscription: ', errorUserInfo.userID);
        console.log('Error code of failed unsubscription: ', errorUserInfo.reason);
        });
    } else {
        console.log('Successfully unsubscribe all users');
    }
} catch (error) {
    // Catch the exception and handle the error
    console.error('An error occurred while unsubscribing:', error);
}
1
Copied!

Query user online statuses

If you only need to get the online statuses of target users once, you can call the queryUsersStatus method and pass the target user IDs (up to 200 users, excluding the current user).

Untitled
// User ID list for querying status
const userIDs = ['userIdA', 'userIdB'];

try {
    // Call the method to query user status
    const result = await zim.queryUsersStatus(userIDs);

    // Traverse the successfully queried user statuses
    result.userStatusList.forEach((userStatus) => {
        console.log('User ID:', userStatus.userID); // Target user ID
        console.log('Online Status:', userStatus.onlineStatus); // User online status
        console.log('Online Platforms:', userStatus.onlinePlatforms); // List of user online platforms
        console.log('Last Update Time:', userStatus.lastUpdateTime); // Last update time of online status
    });

    // Check for failed user queries
    result.errorUserList.forEach((errorUserInfo) => {
        console.log('Failed User ID:', errorUserInfo.userID);
        console.log('Error Code for Failed Query:', errorUserInfo.reason);
    });
} catch (error) {
    // Catch and handle errors
    console.error('Error occurred while querying user status:', error);
}
1
Copied!

Query the online status subscription list

If users want to know their own online status subscription list, they can use the querySubscribedUserStatusList method. If the config.userIDs parameter is empty, the complete subscription list will be returned, including the current status and subscription duration of the target users.

If the config.userIDs parameter is not empty, it means the user wants to check if certain users are in the subscription list. The result callback will only include the status information of users who are in the list.

Untitled
// Query configuration object
const config = {
    userIDs: ['userIdA', 'userIdB'], // If empty, query all subscribed users
};

try {
    // Call the method to query the subscribed user status list
    const result = await zim.querySubscribedUserStatusList(config);

    // Traverse the subscribed user status information
    result.userStatusSubscriptionList.forEach((subscription) => {
        console.log('Subscription expiration time:', subscription.subscribeExpiredTime); // Subscription expiration timestamp
        console.log('User status information:', subscription.userStatus); // User status information
    });
} catch (error) {
    // Catch the exception and handle the error
    console.error('An error occurred while querying the subscribed user status list:', error);
}
1
Copied!

Listen to the online status of the current user on the current device

If you want to know the online status of the current user on the current device, you can listen to the connectionStateChanged callback to get the current connection status of the user ZIMConnectionState, and determine the online status of the current user based on it.

In ZIMConnectionState, Connected means the user is online, Disconnected means the user is offline. The remaining Connecting and Reconnecting connection states can be determined as either online or offline based on your business logic.

Untitled
zim.on('connectionStateChanged', function (zim, { state, event }) {
    switch (state) {
        case 2: // Connected
            console.log('Connected');
            break;
        case 1: // Connecting:
            console.log('Connecting');
            break;
        case 3: // Reconnecting:
            console.log('Reconnecting');
            break;
        case 0: // Disconnected:
            console.log('Disconnected');
            break;
        default:
            console.log('Unknown');
            break;
    }

    console.log('Connection event:', event, state);
});
1
Copied!

Listen to the online platforms list of the current user

In the multi-login scenario, when a user logs in to a second platform, you can listen to the userStatusUpdated callback to get the current user's online platforms from the userStatus.onlinePlatforms property. You can use this information to display the user's online status on different platforms (e.g., showing that the user is online on iOS and Windows).

Note

When the userStatusUpdated callback returns the userStatus information of the current user, the onlineStatus will be unknown and lastUpdateTime will be 0, which cannot accurately reflect the online status.

Untitled
zim.on('userStatusUpdated', function (zim, userStatusList) {
    const myUserID = 'current user ID'; // Replace with the actual ID of the current user

    userStatusList.forEach((userStatus) => {
        if (userStatus.userID === myUserID) {
            // If it is the current user, onlineStatus will be unknown and cannot accurately reflect the current user's online status
            const onlineStatus = userStatus.onlineStatus;

            // List of online platforms for the current user
            const onlinePlatforms = userStatus.onlinePlatforms;

            // If it is the current user, lastUpdateTime will be 0
            const lastUpdateTime = userStatus.lastUpdateTime;

            // Handle logic for online status, online platforms, etc.
            console.log('Current user online status:', onlineStatus);
            console.log('Current user online platforms:', onlinePlatforms);
            console.log('Last status update time:', lastUpdateTime);
        }
    });
});
1
Copied!

Previous

Friend management

Next

Manage rooms

On this page

Back to top