Presence API for Java SDK
Breaking changes in v9.0.0
PubNub Java SDK version 9.0.0 unifies the codebases for Java and Kotlin 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 Java SDK.
For more details about what has changed, refer to Java/Kotlin SDK migration guide.
Presence enables you to track the online and offline status of users and devices in real time, and store custom state information. Presence provides authoritative information on:
- When a user has joined or left a channel
- Who, and how many, users are subscribed to a particular channel
- Which channel(s) an individual user is subscribed to
- Associated state information for these users
Learn more about our Presence feature here.
Here Now
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the hereNow()
function in your application.
Cache
This method has a 3 second response cache time.
Method(s)
To call Here Now
you can use the following method(s) in the Java SDK:
this.pubnub.hereNow()
.channels(Array)
.channelGroups(Arrays)
.includeState(true)
.includeUUIDs(true)
Parameter | Description |
---|---|
channels Type: Array Default: n/a | The channels to get the here now details. |
channelGroups Type: Arrays Default: n/a | The channelGroups to get the here now details. |
includeState Type: Boolean Default: false | If true , the response will include the presence states of the users for channels /channelGroups |
includeUUIDs Type: Boolean Default: true | If true , the response will include the UUIDs of the connected clients. |
async *Type: Consumer<Result> Default: n/a | Consumer of a Result of type PNHereNowResult |
Basic Usage
Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
Get a list of UUIDs subscribed to channel
Returns
The hereNow()
operation returns a PNHereNowResult
which contains the following operations:
Method | Description |
---|---|
getTotalChannels() Type: Int | Total Channels . |
getTotalOccupancy() Type: Int | Total Occupancy . |
getChannels() Type: Map <String, PNHereNowChannelData> | A map with values of PNHereNowChannelData for each channel . See PNHereNowChannelData for more details. |
PNHereNowChannelData
Method | Description |
---|---|
getChannelName() Type: String | Channel name. |
getOccupancy() Type: Int | Occupancy of the channel . |
getOccupants() Type: List <PNHereNowOccupantData> | A list of PNHereNowOccupantData , see PNHereNowOccupantData for more details. |
PNHereNowOccupantData
Method | Description |
---|---|
getUuid() Type: String | UUIDs of the user. |
getState() Type: Object | State of the user. |
Other Examples
Returning State
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
Return Occupancy Only
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
You can return only the occupancy
information for a single channel by specifying the channel and setting UUIDs
to false:
Here Now for Channel Groups
Where Now
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
You can obtain information about the current list of channels to which a UUID is subscribed to by calling the whereNow()
function in your application.
Timeout events
If the app is killed/crashes and restarted (or the page containing the PubNub instance is refreshed on the browser) within the heartbeat window no timeout event is generated.
Method(s)
To call whereNow()
you can use the following method(s) in the Java SDK:
pubnub.whereNow()
.uuid(String)
Parameter | Description |
---|---|
uuid Type: String | Uuid of the user we want to spy on. |
async *Type: Command | Execute as async . |
Basic Usage
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
Returns
The whereNow()
operation returns a PNWhereNowResult
which contains the following operations:
Method | Description |
---|---|
getChannels() Type: List <String> | The list of channels where the UUID is present. |
Other Examples
Obtain information about the current list of channels of some other UUID
User State
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
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)
Set State
this.pubnub.setPresenceState()
.channels(Array)
.channelGroups(Array)
.state(HashMap)
.uuid(String)
Parameter | Description |
---|---|
channels Type: Array | Channels to set state . |
channelGroups Type: Array | ChannelGroups to set state . |
state Type: HashMap | State to set. |
uuid Type: String | Set state for specific UUID . |
async *Type: Consumer<Result> | Consumer of a Result of type PNSetStateResult . |
Get State
this.pubnub.getPresenceState()
.channels(Arrays)
.channelGroups(Arrays)
.uuid(String)
Parameter | Description |
---|---|
channels Type: Arrays | Channel name to fetch the state . |
channelGroups Type: Arrays | ChannelGroups name to fetch the state . |
uuid Type: String | UUID |
async *Type: Consumer<Result> | Consumer of a Result of type PNGetStateResult . |
Basic Usage
Set State
Get State
Returns
The setPresenceState()
operation returns a PNSetStateResult
which contains the following operations:
Method | Description |
---|---|
getState() Type: Map <String, Object> | Map of UUIDs and the user states. |
The getPresenceState()
operation returns a PNGetStateResult
which contains the following operations:
Method | Description |
---|---|
getStateByUUID() Type: Map <String, Object> | Map of UUIDs and the user states. |
Other Examples
Set state for channels in channel group
The above code would return the following response to the client: