Presence
Updated
Shows how to use the Agora Chat SDK to implement presence in your project.
The presence feature enables users to publicly display their online presence status and quickly determine the status of other users. Users can also customize their presence status, which adds fun and diversity to real-time chatting.
The following illustration shows the implementation of creating a custom presence status and how various presence statues look in a contact list:
Understand the tech
The Chat SDK provides the ChatPresence, ChatPresenceManager, and ChatPresenceEventListener classes for presence management, which allows you to implement the following features:
Prerequisites
Before proceeding, ensure that your environment meets the following requirements:
- You have initialized the Chat SDK. For details, see SDK quickstart.
- You understand the API call frequency limit as described in Limitations.
- You have activated the presence feature in Agora Console.
Implementation
This section introduces how to implement presence functionalities in your project.
Subscribe to the presence status of one or more users
By default, you do not subscribe to any users. To subscribe to the presence statuses of the specified users, you can call subscribe. Whenever the specified users update their presence statuses, the onPresenceStatusChanged callback is triggered, notifying you about the updated statuses asynchronously.
The following code sample shows how to subscribe to the presence status of one or more users:
// memberIds: The ID list of users to whom you subscribe.
// expiry: The subscription duration in seconds.
ChatClient.getInstance()
.presenceManager.subscribe(memberIds, expiry)
.then((result) => {
console.log("success: ", result);
})
.catch((error) => {
console.log("fail: ", error);
});You can subscribe to a maximum of 100 users at each call. The total subscriptions of each user cannot exceed 3,000. Once the number of subscriptions exceed the limit, the subsequent subscriptions with longer durations succeed and replace the existing subscriptions with shorter durations.The subscription duration can be a maximum of 30 days. When the subscription to a user expires, you need to subscribe to this user once again. If you subscribe to a user again before the current subscription expires, the duration is reset.
Publish a custom presence status
You can call publishPresence to publish a custom status. Whenever your presence status updates, the users who subscribe to you receive the onPresenceStatusChanged callback.
The following code sample shows how to publish a custom status:
// description: The custom presence status.
ChatClient.getInstance()
.presenceManager.publishPresence(description)
.then((result) => {
console.log("success: ", result);
})
.catch((error) => {
console.log("fail: ", error);
});Listen for presence status updates
Refer to the following code sample to listen for presence status updates:
// Inherits and implements the ChatPresenceEventListener class.
class ChatPresenceEvent implements ChatPresenceEventListener {
// Occurs when the presence statuses of the subscriptions update.
onPresenceStatusChanged(list: ChatPresence[]): void {
console.log(`onPresenceStatusChanged:`, list.length, list);
}
}
// Removes the presence status listener.
ChatClient.getInstance().presenceManager.removeAllPresenceListener();
// Adds the presence status listener.
ChatClient.getInstance().presenceManager.addPresenceListener(
new ChatPresenceEvent()
);Unsubscribe from the presence status of one or more users
You can call unSubscribe to unsubscribe from the presence statuses of the specified users, as shown in the following code sample:
// memberIds: The ID list of users from whom you unsubscribe.
ChatClient.getInstance()
.presenceManager.unSubscribe(memberIds)
.then((result) => {
console.log("success: ", result);
})
.catch((error) => {
console.log("fail: ", error);
});Retrieve the list of subscriptions
You can call fetchSubscribedMembers to retrieve the list of your subscriptions in a paginated list, as shown in the following code sample:
// pageNum: The page from which to start retrieving subscriptions.
// pageSize: The maximum number of subscriptions to retrieve per page. The range is [1, 50].
ChatClient.getInstance()
.presenceManager.fetchSubscribedMembers(pageNum, pageSize)
.then((result) => {
console.log("success: ", result);
})
.catch((error) => {
console.log("fail: ", error);
});Retrieve the presence status of one or more users
You can call fetchPresenceStatus to retrieve the current presence statuses of the specified users without the need to subscribe to them, as shown in the following code sample:
// memberIds: The ID list of users whose presence status you retrieve.
// You can pass in up to 100 user IDs.
ChatClient.getInstance()
.presenceManager.fetchPresenceStatus(memberIds)
.then((result) => {
console.log("success: ", result);
})
.catch((error) => {
console.log("fail: ", error);
});