Presence API for Python-Asyncio SDK
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 here_now()
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 Python SDK:
pubnub.here_now() \
.channels(String|List|Tuple) \
.channel_groups(String|List|Tuple) \
.include_state(Boolean) \
.include_uuids(Boolean)
Parameter | Description |
---|---|
channels Type: String | List | Tuple Default: n/a | The channels to get the here now details. |
channel_groups Type: String | List | Tuple Default: n/a | The channel groups to get the here now details. |
include_state Type: Boolean Default: False | If True , the response will include the presence states of the users for channels/channelGroups. |
include_uuids Type: Boolean Default: True | If True , the response will include the UUIDs of the connected clients. |
Basic Usage
Get a list of UUIDs subscribed to channel
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.
import asyncio
import os
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub_asyncio import PubNubAsyncio
from pubnub.exceptions import PubNubException
async def get_here_now(pubnub: PubNubAsyncio):
try:
# Get a list of UUIDs subscribed to channels
envelope = await pubnub.here_now() \
.channels(['cool_channel1', 'cool_channel2']) \
.include_uuids(True) \
.future()
show all 46 linesReturns
The here_now()
operation returns a PNHereNowResult
which contains the following fields:
Field | Type | Description |
---|---|---|
total_channels | Int | Total channels . |
total_occupancy | Int | Total occupancy |
channels | Dictionary | A Dictionary with values of PNHereNowChannelData for each channel. |
PNHereNowChannelData:
Field | Type | Description |
---|---|---|
channel_name | String | channel name. |
occupancy | Int | occupancy of the channel . |
occupants | List | A list of PNHereNowOccupantData . |
PNHereNowOccupantData:
Field | Type | Description |
---|---|---|
uuid | String | uuid of the user. |
state | Dictionary | state of the user. |
Returning State
Requires Presence
This method requires that the Presence add-on is enabled for your key in the Admin Portal.
envelope = await pubnub.here_now() \
.channels("my_channel") \
.include_uuids(True) \
.include_state(True) \
.future()
Example Response
{
total_channels: 1,
channels: [{
channel_name: "my_channel",
occupancy: 1,
occupants: [{
uuid: "myUuid1"
state: {
"abcd": {
"age": 15
}
}
}]
}],
total_occupancy: 1
show all 16 linesReturn 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
:
envelope = await pubnub.here_now() \
.channels("my_channel") \
.include_uuids(False) \
.include_state(False) \
.future()
Example Response
{
total_channels: 1,
channels: [{
channel_name: "my_channel",
occupancy: 3,
occupants: []
}],
total_occupancy: 3
}
Here Now for Channel Groups
envelope = await pubnub.here_now() \
.channel_groups(['cg1', 'cg2', 'cg3']) \
.include_uuids(True) \
.include_state(True) \
.future()
Example Response
{
total_channels: 1,
channels: [
{
channel_name: "my_channel",
occupancy: 1,
occupants: [{
uuid: "143r34f34t34fq34q34q3",
state: None
}]
},
{
occupancy: 1,
occupants: [{
uuid: "123123234t234f34fq3dq",
show all 35 linesWhere 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 where_now()
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 where_now()
you can use the following method(s) in the Python SDK:
pubnub.where_now() \
.uuid(String)
Parameter | Description |
---|---|
uuid Type: String | uuid to get info on. |
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
envelope = await pubnub.where_now() \
.future()
Returns
The where_now()
operation returns a PNWhereNowResult
which contains the following fields:
Field | Type | Description |
---|---|---|
channels | List | The list of channels where the UUID is present. |
Other Examples
Obtain information about the current list of channels of some other UUID
envelope = await pubnub.where_now() \
.uuid('some-other-uuid') \
.future()
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 dict
. When calling set_state
, be sure to supply an initialized dict
which can be serialized.
Method(s)
Set State
pubnub.set_state() \
.channels(String|List|Tuple) \
.channel_groups(String|List|Tuple) \
.state(Dictionary)
Parameter | Description |
---|---|
channels Type: String | List | Tuple | channels to set state . |
channel_groups Type: String | List | Tuple | channel groups to set state . |
state Type: Dictionary | state to set. |
Get State
pubnub.get_state() \
.channels(String|List|Tuple) \
.channel_groups(String|List|Tuple) \
.uuid(String)
Parameter | Description |
---|---|
channels Type: String | List | Tuple | channels to get state . |
channel_groups Type: String | List | Tuple | channel groups to get state . |
uuid Type: String | uuid to get state from. |
Basic Usage
Set State
my_state = {
'age': 20
}
envelope = await pubnub.set_state() \
.channels(['ch1', 'ch2', 'ch3']) \
.state(my_state) \
.future()
Get State
envelope = await pubnub.get_state() \
.channels(['ch1', 'ch2', 'ch3']) \
.uuid('such_uuid') \
.future()
Returns
The set_state() operation returns a PNSetStateResult which contains the following fields
Field | Type | Description |
---|---|---|
state | Dictionary | Dictionary of UUIDs and the user states. |
The get_state() operation returns a PNGetStateResult which contains the following fields
Field | Type | Description |
---|---|---|
channels | Dictionary | Dictionary of channels and the user states. |
Other Examples
Set state for channels in channel group
my_state = {
'age': 20
}
envelope = await pubnub.set_state().channel_groups(['gr1', 'gr2', 'gr3']).state(my_state).future()
The above code would return the following response to the client:
{
first : "Robert",
last : "Plant",
age : 59,
region : "UK"
}