Presence API for Kotlin SDK
Breaking changes in v9.0.0
PubNub Kotlin SDK version 9.0.0 unifies the codebases for Kotlin and Java SDKs, introduces a new way of instantiating the PubNub client, and changes asynchronous API callbacks and emitted status events. These changes can impact applications built with previous versions (< 9.0.0 ) of the Kotlin SDK.
For more details about what has changed, refer to Java/Kotlin SDK migration guide.
Presence lets you track who is online or offline and store custom state information. Presence shows:
- When a user has joined or left a channel
- How many users are subscribed to a particular channel (occupancy)
- Which channels a user or device is subscribed to
- Presence state associated with these users
Learn more about our Presence feature in the Presence overview.
Request execution
Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously.
You must invoke the .sync() or .async() method on the Endpoint to execute the request, or the operation will not be performed.
1val channel = pubnub.channel("channelName")
2
3channel.publish("This SDK rules!").async { result ->
4 result.onFailure { exception ->
5 // Handle error
6 }.onSuccess { value ->
7 // Handle successful method result
8 }
9}
Here now
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
For information on how to receive presence events and what those events are, refer to Presence Events.
This method returns information about the current state of a channel, including a list of unique user IDs (universally unique identifiers, UUIDs) currently subscribed to the channel and the total occupancy count of the channel.
Cache
This method has a 3-second response cache time.
Method(s)
To call Here Now you can use the following methods in the Kotlin SDK:
1pubnub.hereNow(
2 channels: List<String>,
3 channelGroups: List<String>,
4 includeState: Boolean,
5 includeUUIDs: Boolean,
6 limit: Int,
7 offset: Int?
8).async { result -> }
channels#- The
channelsto get the 'here now' details of. channelGroups#- The
channelGroupsto get the 'here now' details of. Wildcards are not supported. includeState#- If
true, the response will include the presence states of the users forchannels/channelGroups. includeUUIDs#- If true, the response will include the
UUIDsof the connected clients. limit#- Maximum number of occupants to return per channel. Valid range:
0-1000. The server enforces the maximum of1000and rejects values outside this range. Use0to get occupancy counts without user details (whenlimit=0, the server omits UUIDs entirely). offset#- Zero-based starting index for pagination. Returns occupants starting from this position in the list. Must be
>= 0. Requireslimit > 0. Server rejects negative values. Use withlimitto paginate through large occupant lists.
Sample code
Get a list of UUIDs subscribed to channel
1
Returns
The hereNow() operation returns a PNHereNowResult? which contains the following operations:
totalChannels#- Total channels
totalOccupancy#- Total occupancy
channels#- A map with values of
PNHereNowChannelDatafor each channel. See PNHereNowChannelData for more details.
PNHereNowChannelData
channelName#- Channel name
occupancy#- Occupancy of the channel
occupants#- A list of
PNHereNowOccupantData, see PNHereNowOccupantData for more details.
PNHereNowOccupantData
Other examples
Returning state
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
For information on how to receive presence events and what those events are, refer to Presence Events.
1
Example response:
1.async { result: Result<PNHereNowResult> ->
2 result.onSuccess { res: PNHereNowResult ->
3 res.channels.values.forEach { channelData ->
4 channelData.channelName // ch1
5 channelData.occupancy // 3
6 channelData.occupants.forEach { o ->
7 o.uuid // some_uuid, returned by default
8 o.state // {"data":{"isTyping":true}}, requested
9 }
10 }
11 }.onFailure { e ->
12 // handle error
13 e.message
14 e.statusCode
15 e.pubnubError
Return occupancy only
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
For information on how to receive presence events and what those events are, refer to Presence Events.
You can return only the occupancy information for a single channel by specifying the channel and setting UUIDs to false:
1
Example response:
1.async { result: Result<PNHereNowResult> ->
2 result.onSuccess { res: PNHereNowResult ->
3 res.channels.values.forEach { channelData ->
4 channelData.channelName // ch1
5 channelData.occupancy // 3
6 }
7 }.onFailure { e ->
8 // handle error
9 e.message
10 e.statusCode
11 e.pubnubError
12 }
13}
Here now for channel groups
1
Example response:
1.async { result: Result<PNHereNowResult> ->
2 result.onSuccess { res: PNHereNowResult ->
3 res.totalOccupancy
4 }.onFailure { e ->
5 // handle error
6 e.message
7 e.statusCode
8 e.pubnubError
9 }
10}
Where now
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
For information on how to receive presence events and what those events are, refer to Presence Events.
This method returns the list of channels a UUID is subscribed to.
Timeout events
If the app restarts (or the page refreshes) within the heartbeat window, no timeout event is generated.
Method(s)
To call whereNow() you can use the following method(s) in the Kotlin SDK:
1pubnub.whereNow(
2 uuid: String
3).async { result -> }
uuid#- UUID of the user to get its current channel subscriptions.
Sample code
You simply need to define the uuid and the callback function to be used to send the data to as in the example below.
Get a list of channels a UUID is subscribed to
1
Returns
The whereNow() operation returns a PNWhereNowResult? which contains the following operations:
channels#- List of channels where the
uuidis present.
Other examples
Obtain information about the current list of channels of some other UUID
1
User state
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
For information on how to receive presence events and what those events are, refer to Presence Events.
Clients can set a dynamic custom state (score, game state, location) for their users on one or more channels and store it on a channel as long as the user stays subscribed.
The state is not persisted, and when the client disconnects, the state data is lost. For more information, refer to Presence State.
Presence state format
Presence state must be expressed as a JsonObject. When calling setState, be sure to supply an initialized JsonObject or POJO which can be serialized to a JsonObject.
Method(s)
To set the state, call setPresenceState() you can use the following method(s) in the Kotlin SDK:
Set state
1pubnub.setPresenceState(
2 channels: List<String>,
3 channelGroups: List<String>,
4 state: Any,
5 uuid: String
6).async { result -> }
Get state
1pubnub.getPresenceState(
2 channels: List<String>,
3 channelGroups: List<String>,
4 uuid: String
5).async { result -> }
To get the state, call getPresenceState() you can use the following method(s) in the Kotlin SDK:
Sample code
1
Returns
The setPresenceState() operation returns a PNSetStateResult? which contains the following operations:
state#- The actual state object
The getPresenceState() operation returns a PNSetStateResult? which contains the following operations:
stateByUUID#- Map of UUIDs and the user states.
Other examples
Set state for channels in channel group
1
Get state for UUID
1