Presence

In real-time messaging solutions, it is often important to know whether a user is currently online or offline. For example, in instant messaging, chat applications, and online collaboration tools, users need to see the availability of their contacts. This information is typically displayed as a status message or icon next to a user's name. Presence features in Signaling SDK enable you to monitor join, leave, and status change notifications for users in a channel. Using Presence, you can:

Get a list of users currently in a channel and their temporary status data.
Get a list of channels a specified user has joined or is subscribed to.
Read, set, or remove user status.
Receive real-time event notifications when users join or leave specified channels.
Receive user status change event notifications in real time.

Understand the tech

Presence provides real-time information about the availability, and the current status of users, for effective communication and collaboration. It enables you to retrieve a list of users in a channel, or to query the list of channels for a specific user. The following figure illustrates how you integrate presence features into your app.

Prerequisites

To follow this page, you must have:

Set up the Signaling SDK reference app.

Implement presence

To implement presence,

Add the presence event listener

protected open val eventListener: RtmEventListener = object : RtmEventListener {
    override fun onPresenceEvent(eventArgs: PresenceEvent) {
        // Your Presence Event handler
        if (eventArgs.eventType == RtmConstants.RtmPresenceEventType.SNAPSHOT) {
            channelType = eventArgs.channelType
        }
        mListener?.onSignalingEvent("Presence", eventArgs)
    }
    // Other event listeners
}

Event Listeners

fun subscribe(channelName: String): Int {
    // Subscribe to a channel
    val subscribeOptions = SubscribeOptions(
        true, 
        true, // Subscribe with Presence
        true, 
        true
    ) 
    signalingEngine?.subscribe(channelName, subscribeOptions, object: ResultCallback<Void?> {
        override fun onFailure(errorInfo: ErrorInfo?) {
            notify("Subscribe failed:\n"+ errorInfo.toString())
        }
        override fun onSuccess(responseInfo: Void?) {
            isSubscribed = true
            mListener?.onSubscribeUnsubscribe(isSubscribed)
            notify("Subscribed to channel: $channelName")
        }
    })
    return 0
}

Obtain a list of users in the channel

To get a list of users in a channel, call getOnlineUsers():

fun getOnlineUsers () {
    val getOnlineUsersOptions = GetOnlineUsersOptions(true, true)
    signalingEngine?.presence?.getOnlineUsers(channelName, channelType, getOnlineUsersOptions,  object: ResultCallback<GetOnlineUsersResult?> {
        override fun onFailure(errorInfo: ErrorInfo?) {
            notify("Failed to obtain user list")
        }
        override fun onSuccess(getOnlineUsersResult: GetOnlineUsersResult?) {
            val list = getOnlineUsersResult?.userStateList
            val userList: List<String> = list?.map { it.userId } ?: emptyList()
            mListener?.onUserListUpdated(userList)
        }
    })
}

Set local user status

To set the local user status, call setState.

fun setStatus() {
    val stateItems: ArrayList<StateItem> = ArrayList()
    stateItems.add(StateItem("mood", "pumped"))
    signalingEngine?.presence?.setState(channelName, channelType, stateItems,
        object : ResultCallback<Void?> {
            override fun onSuccess(responseInfo: Void?) {
                notify("Set state success")
            }
            override fun onFailure(errorInfo: ErrorInfo) {
                notify(errorInfo.toString())
            }
        })
}

setState

Get the status of a remote user

To read the status of a remote user, call getState.

fun getState(uid: Int) {
    signalingEngine?.presence?.getState(channelName, channelType, uid.toString(),
        object : ResultCallback<UserState?> {
            override fun onSuccess(state: UserState?) {
                if (state != null) {
                    for (item in state.states) {
                        Log.i("getState $uid:", item.toString())
                    }
                }
            }
            override fun onFailure(errorInfo: ErrorInfo) {
                notify(errorInfo.toString())
            }
        })
}

getState

Test presence

This section explains how to run the Signaling reference app and test presence features. To run the project, take the following steps:

For each user in your tests:

Configure the project
1. Open the file <samples-root>/signaling-manager/src/main/res/raw/config.json
2. Replace the value for appId with the value from Agora Console.
3. Generate an RTM token using your uid.
4. Replace the value for token with the Signaling token.
5. Replace the value for uid with the the value you used to generate the token.
6. Ensure that the channelName is filled in. The channel name can be any string.
Run the reference app
1. In Android Studio, connect a physical Android device to your development machine.
2. Click Run to start the app.
3. A moment later you see the project installed on your device.
Test presence functionality:
1. Run multiple instances of the SDK quickstart example.
2. Log in to Signaling from each instance using a different user ID.
3. Subscribe to the same channel from all instances. You see a list of all users in the channel.
4. Unsubscribe a user from the channel. You see that the corresponding user ID disappears from the user list.

Reference

This section contains additional information that either supplements the content on this page or directs you to documentation that covers other aspects of this product.

You are viewing Agora Docs forBeta products and features. Switch to Docs