logo
In-app Chat
SDK Error Codes
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
ZIMUserStatusSubscribeConfig config = ZIMUserStatusSubscribeConfig();
config.subscriptionDuration = 60; // Subscription duration in minutes, valid range is 1 to 43200 (30 days)

// Call the subscribeUsersStatus method
ZIM.getInstance()?.subscribeUsersStatus(["userIdA","userIdB"], config).then((ZIMUsersStatusSubscribedResult result) {
    for(ZIMErrorUserInfo errorUserInfo in result.errorUserList){
        errorUserInfo.userID;   // User ID failed to subscribe
        errorUserInfo.reason;   // Failure reason
    }
}).catchError((onError){

});
1
Copied!

Event notification

Subsequently, the online status changes of the target users within the specified subscriptionDuration will be returned through the onUserStatusUpdated event callback registered by the ZIMEventHandler 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
ZIMEventHandler.onUserStatusUpdated = (ZIM zim, List<ZIMUserStatus> userStatusList){
    for (ZIMUserStatus userStatus in userStatusList) {
        userStatus.userID;            // Target user ID
        userStatus.onlineStatus;      // Target user's online status
        userStatus.onlinePlatforms;   // User online platforms list 
        userStatus.lastUpdateTime;    // Last update time of online status
    }
};
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
ZIM.getInstance()?.unsubscribeUsersStatus(["userIdA","userIdB"]).then((ZIMUsersStatusUnsubscribedResult result) {
    for(ZIMErrorUserInfo errorUserInfo in result.errorUserList){
        errorUserInfo.userID;   // User ID failed to be unsubscribed
        errorUserInfo.reason;   // Failure reason
    }
}).catchError((onError){

});
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
ZIM.getInstance()?.queryUsersStatus(["userIdA","userIdB"]).then((ZIMUsersStatusQueriedResult result) {
    for (ZIMUserStatus userStatus in result.userStatusList) {
      userStatus.userID;          // Target user ID
      userStatus.onlineStatus;    // User online status
      userStatus.onlinePlatforms; // User online platform list
      userStatus.lastUpdateTime;  // Last update time of online status
    }
    for (ZIMErrorUserInfo errorUserInfo in result.errorUserList){
      errorUserInfo.userID; // User ID failed to be queried
      errorUserInfo.reason; // Failure reason
    }
}).catchError((onError){

});
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
ZIMSubscribedUserStatusQueryConfig queryConfig = ZIMSubscribedUserStatusQueryConfig();
queryConfig.userIDs = ["userIdA","userIdB"];
// Query target user IDs (up to 200 users per query)
// When userIDs is empty, the method will get the complete subscription table information
// When userIDs is not empty, the method will check whether the target users are in the subscription list
// If the users exist, the result callback will present the user's status information
// If the user does not exist, the result callback will not include any relevant information
ZIM.getInstance()?.querySubscribedUserStatusList(queryConfig).then((ZIMSubscribedUserStatusListQueriedResult result) {

}).catchError((onError){

});
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 onConnectionStateChanged 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
ZIMEventHandler.onConnectionStateChanged = (ZIM zim, ZIMConnectionState state,
    ZIMConnectionEvent event, Map extendedData){
    switch (state) {
        case ZIMConnectionState.connected:
            break;
        case ZIMConnectionState.connecting:
            break;
        case ZIMConnectionState.reconnecting:
            break;
        case ZIMConnectionState.disconnected:
            break;
        default:
            break;
    }
};
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 onUserStatusUpdated 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 onUserStatusUpdated 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
ZIMEventHandler.onUserStatusUpdated = (ZIM zim, List<ZIMUserStatus> userStatusList){
    for (ZIMUserStatus userStatus in userStatusList) {
        if (userStatus.userID == "myUserID"){
            userStatus.onlineStatus;        // If it is the current user, onlineStatus will be unknown and cannot accurately reflect the current user's online status
            userStatus.onlinePlatforms;     // List of online platforms for the current user

            userStatus.lastUpdateTime;      // If it is the current user, lastUpdateTime will be 0
       }
    }
};
1
Copied!

Previous

Friend management

Next

Manage rooms