Presence state is a vital aspect of any modern application, acting as a driving factor for engagement products by showing the user's current availability. The AmitySDK supports both observing and notifying the presence of users, analogous to being online and observing users' online statuses.
AmitySDK offers specific methods that allow the logged-in user to enable, disable, or query about presence settings. When these presence settings are enabled, the user is prepared to synchronize their presence state with the server.
Users can enable or disable their presence state feature. Disabled users will be considered offline and cannot use any presence-related functionalities. Network-level settings can also affect this feature.
Presence State feature is disabled by default at both the network and user levels. Please consult with Amity Team to enable this feature on the network level.
The SDK user can invoke the enable() method within client.presence to activate their presence status.
The SDK user can invoke the disable() method within client.presence to deactivate their presence status. When disabled, the user will be unable to sync both their own heartbeat and the presence of other users in the network. This action also halts any ongoing heartbeat synchronization processes.
The SDK user can invoke the isEnabled() method within client.presence to check their presence status. This method also determines if the presence state feature is available for the app. If unavailable, isEnabled() returns false. If the feature is available, the method checks the user-level settings, which are managed through the enable() and disable() methods as previously described.
The SDK also offers functionality to query and synchronize the presence of other users, enabling the creation of a UI that displays their online status. For example, you might use a green dot to indicate whether a particular user is online or offline.
Within the SDK, a user's presence is represented by the AmityUserPresence object, which contains three properties.
| Property | Remarks |
|---|---|
The SDK enables users to query the presence state for a list of users, with a maximum limit of 220. The getUserPresence method from the AmityUserPresenceRepository class can be used to fetch a list of AmityUserPresence objects.
In addition to querying user presence, the SDK also offers a method to periodically sync the presence of other users. This functionality keeps users informed about the online status of others. One application of this feature would be to display a list of users and provide an online indicator for those who are currently online.
The SDK includes the syncUserPresence(id, viewId) method in the AmityUserPresenceRepository class to synchronize the presence of another user. This method adds the specified ID to the list of user IDs for presence synchronization, occurring periodically at set intervals. To observe the results of this process, use the getSyncingUserPresence() method. When presence information is obtained for the currently syncing user IDs, notifications are sent through the observer returned from the getSyncingUserPresence() method. For further details on observing presence, refer to the #observe-user-presence section.
For optimal use, particularly when displaying a list of users, call this method as a list item appears to synchronize the user's presence state. Conversely, utilize the unsyncUserPresence(id, viewId) method to stop synchronization when a list item is no longer visible, ensuring that the maximum sync limit is never reached.
The maximum number of user IDs that can be synced at a time is 20. If the count exceeds this limit, the SDK will log an error message to the console. To remove a user ID from the list, use the unsyncUserPresence(id:viewId:) method.
This syncUserPresence(id, viewId) method also provides an optional viewId parameter. viewId is the unique id of the view that this user id is tied to. In most of the cases, you do not need to specify any value to this parameter. viewId is useful if you want to bind same user id to multiple views in same screen. In that case, if you want to unsync presence for one view, it won't affect presence syncing for same user id in another view.
SDK will log a message in console incase of any error which occurs during syncing process.
The SDK includes the unsyncUserPresence(id, viewId) method to cease syncing the presence of a specific user ID. When a user ID is unsynced, the SDK removes it from the current list of synced IDs, and the observer returned from the getSyncingUserPresence() method will no longer provide presence information for that user. The method also features an optional viewId parameter, functioning similarly to the syncUserPresence(id, viewId) method.
The SDK also provides a convenient method to unsync all user ids which are currently being synced. This is particularly useful when you don’t care about the user ids being synced. One usecase for this is when user navigates to another screen which do not care about syncing previously synced users at all. So you can call unsyncAllUserPresence() method when the previous screen disappears.
After adding users for synchronization, the next step involves observing their presence. The SDK offers an observer via the getSyncingUserPresence() method. Whenever presence information is retrieved for users synced through syncUserPresence(id, viewId), this information is published through the observer.
Accessing User Presence:
You can access the presence information for synced users in two ways:
Through the Observer Returned from getSyncingUserPresence(): When the presence information is updated, the observer provides an array of [AmityUserPresence] for the user IDs being synced. Users need to map AmityUserPresence from this array to the view where the information is to be displayed.
Through the AmityUser Object: When presence information is fetched from the server, the lastHeartbeat timestamp is mapped to the lastHeartbeat property of the AmityUser object, if available. Users can directly access the lastHeartbeat property from the AmityUser object to determine whether a user is online or offline.
The SDK provides the getOnlineUsersCount method in the AmityUserPresenceRepository class to query the count of online users. Please note that this count does not update automatically.
The SDK provides a method getOnlineUsersSnapshot in AmityUserPresenceRepository to query list of online users in a network. The list of users can be accessed through users property which returns an array of AmityUser.
This snapshot is not auto updating & supports query of up to 1000 online users.
When this snapshot object is initialized, it fetches the snapshot of user presences of all online users in current network. Then it maps those information to AmityUser per page and provides list of AmityUser with pagination. Each page can contain max 20 users. When snapshot is returned, it will contains users for first page. You can still fetch more users if available through loadMore() method. Once more users are fetched, user can access those users through users property. You can also use canLoadMore property to determine if there are more online users which can be fetched.
The SDK also provides a way to query & sync presence of members of conversation channel. This allows you to create a UI which displays presence status of other members in the conversation channel. Example: A green dot to indicate whether other user is online or offline in conversation channel.
In SDK, channel presence is represented by AmityChannelPresence object. This object contains 3 properties.
| Property | Remarks |
|---|---|
The SDK also offers the functionality to query and synchronize the presence of members within a conversation channel. This enables the creation of a user interface that displays the presence status of other members in the channel, such as using a green dot to indicate whether a user is online or offline within a specific conversation. In the SDK, channel presence is represented by the AmityChannelPresence object, which contains three properties.
The SDK includes the syncChannelPresence(id,viewId) method in the AmityChannelPresenceRepository class to synchronize the presence of members within a conversation channel. This method adds the specified ID to the list of channel IDs whose members' presence will be synced, and this process occurs periodically at a predetermined interval. To observe the results of this syncing process, use the getSyncingChannelPresence() method. When the presence information for the currently syncing channel members is obtained, it is published through the observer returned by the getSyncingChannelPresence() method. More details can be found in the #observe-channel-presence section.
When displaying a list of conversation channels, it is advisable to use this method. The observer offers a class named AmityChannelPresence that holds the presence information for the channel's members. Likewise, the unsyncChannelPresence(id, viewId) method should be used to stop syncing the presence state when a list item is no longer visible, ensuring that the maximum sync limit is never reached.
Only syncing of Conversation channel type is supported ! The maximum number of channel IDs that can be synced at a time is 20. If the count exceeds this limit, the SDK will log an error message to the console. To remove a channel ID from the list, use the unsyncChannelPresence(id, viewId) method.
This syncChannelPresence(id, viewId) method also provides an optional viewId parameter. viewId is the unique id of the view that this user id is tied to. In most of the cases, you do not need to specify any value to this parameter. viewId is useful if you want to bind same channel id to multiple views in same screen. In that case, When you unsync channel presence in one view, it won't affect presence syncing for same channel id in another view.
SDK will log a message in console incase of any error which occurs during syncing process.
The SDK offers the unsyncChannelPresence(id, viewId) method to cease syncing the presence of a particular conversation channel. If the channel ID is unsynced, the SDK will remove it from the list of channel IDs whose members are currently being synced. Consequently, the observer returned by the getSyncingChannelPresence() method will no longer contain information about this channel. This method includes an optional viewId parameter and operates similarly to the syncChannelPresence(id, viewId) method.
The SDK includes a convenient method, unsyncAllChannelPresence(), to stop syncing all channels that are currently being monitored. This feature is particularly useful when the application no longer requires information about the channels being synced. For example, this method can be called when a user navigates to a different screen that has no dependence on the previously synced channels, allowing for an efficient transition between different parts of the application.
After adding the channels to sync, the next step is observing the user presence. The SDK provides an observer through the getSyncingChannelPresence() method. Whenever presence information is fetched for channels synced through the syncChannelPresence(id, viewId) method, that information is published through this observer.
Accessing Channel Presence:
Through the observer returned from getSyncingChannelPresence()
Whenever presence information is updated, the observer will provide an array of [AmityChannelPresence] for the channels that are being synced. Users must map AmityChannelPresence from this array to the view where this information is to be displayed
The presence heartbeat is a mechanic to signal the system whether a user is online or offline. The SDK offers two convenient methods that allow users to periodically sync or unsync their presence status with the server. When the server receives a heartbeat sync request, it records the timestamp at the time of the request, designating it as the lastHeartbeat timestamp for that user.
The SDK automatically manages the periodic syncing of this heartbeat once the startHeartbeat method is called. To cease syncing your presence with the server, the user must invoke the stopHeartbeat method.
Invoke the startHeartbeat method in client.presence to initiate the heartbeat synchronization process. This method automatically checks the user's presence settings within the network, and if enabled, begins to sync the heartbeat at specified intervals defined in the SDK. The synchronization process is handled automatically, streamlining the user's interaction with the system.
The heartbeat sync interval is determined automatically by SDK. Normally you can except heartbeat to be synced every 20-30 seconds.
Utilize the stopHeartbeat() method within client.presence to cease the heartbeat synchronization process. To restart the sync, you must invoke the startHeartbeat() method again.
userId
Id of the user
lastHeartbeat
Timestamp when that user last synced its heartbeat with the server.
isOnline
Convenient property to determine online status. User is considered online if its lastHeartbeat has been within last 60 seconds.
channelId
Id of the Channel
userPresences
AmityUserPresence object for members whose presence state has been synced
isAnyMemberOnline
If any user's (except you) lastHeartbeat has been within last 60 seconds