Presence API for PubNub C# SDK
Presence enables you to track the online and offline status of users and devices in real time, as well as 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 add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
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.
Method(s)
To call Here Now
you can use the following method(s) in the C# V4 SDK:
pubnub.HereNow().Channels(Array).ChannelGroups(Array).IncludeState(bool).IncludeUUIDs(bool).QueryParam(Dictionary<string,object>)
Parameter Type Required Description Channels
Array Optional The Channels
to get thehere now
details.ChannelGroups
Array Optional The ChannelGroups
to get thehere now
details.IncludeState
bool Optional If true
, the response will include the presence states of the users forChannels
/ChannelGroups
.IncludeUUIDs
bool Optional If true
, the response will include theUUIDs
of the connected clients.QueryParam
Dictionary<string, object> Optional Dictionary object
to pass name/value pairs as querystring
params with PubNub URL request for debug purpose.Async
PNCallback Deprecated PNCallback
of typePNHereNowResult
.Execute
PNCallback Yes PNCallback
of typePNHereNowResult
.ExecuteAsync
None Optional Returns PNResult<PNHereNowResult>
.
Basic Usage
Get a list of UUIDs subscribed to channel:
PNResult<PNHereNowResult> herenowResponse = await pubnub.HereNow()
// tailor the next two lines to example
.Channels(new string[] {
"coolChannel",
"coolChannel2"
})
.IncludeUUIDs(true)
.ExecuteAsync();
PNHereNowResult herenowResult = herenowResponse.Result;
PNStatus status = herenowResponse.Status;
if (status.Error)
{
// handle error
return;
}
if (herenowResult != null && herenowResult.Channels != null && herenowResult.Channels.Count > 0)
{
foreach (KeyValuePair<string, PNHereNowChannelData> kvp in herenowResult.Channels)
{
PNHereNowChannelData channelData = kvp.Value;
Console.WriteLine("---");
Console.WriteLine("channel:" + channelData.ChannelName);
Console.WriteLine("occupancy:" + channelData.Occupancy);
Console.WriteLine("Occupants:");
if (channelData.Occupants != null && channelData.Occupants.Count > 0)
{
for (int index = 0; index < channelData.Occupants.Count; index++)
{
PNHereNowOccupantData occupant = channelData.Occupants[index];
Console.WriteLine(string.Format("uuid: {0}", occupant.Uuid));
Console.WriteLine(string.Format("state:{0}", (occupant.State != null) ?
pubnub.JsonPluggableLibrary.SerializeToJsonString(occupant.State) : ""));
}
}
}
}
Returns
The HereNow()
operation returns a PNResult<PNHereNowResult>
which contains the following properties:
Property Name | Type | Description |
---|---|---|
Result | PNHereNowResult | Returns a PNHereNowResult object. |
Status | PNStatus | Returns a PNStatus object. |
PNHereNowResult
contains the following properties:
Property Name | Type | Description |
---|---|---|
TotalChannels | int | Total Channels . |
TotalOccupancy | int | Total Occupancy . |
Channels | Dictionary<string, PNHereNowChannelData> | A map with values of PNHereNowChannelData for each channel . See PNHereNowChannelData for more details. |
PNHereNowChannelData
Property Name | Type | Description |
---|---|---|
ChannelName | string | Channel name. |
Occupancy | int | Occupancy of the channel . |
Occupants | List | A list of PNHereNowOccupantData , see PNHereNowOccupantData for more details. |
PNHereNowOccupantData
Property Name | Type | Description |
---|---|---|
Uuid | string | UUIDs of the user. |
State | object | State of the user. |
Other Examples
Get a list of UUIDs subscribed to channel synchronously:
pubnub.HereNow() // tailor the next two lines to example .Channels(new string[] { "coolChannel", "coolChannel2" }) .IncludeUUIDs(true) .Execute(new PNHereNowResultEx( (result, status) => { if (status.Error) { // handle error return; } if (result.Channels != null && result.Channels.Count > 0) { foreach (KeyValuePair<string, PNHereNowChannelData> kvp in result.Channels) { PNHereNowChannelData channelData = kvp.Value; Console.WriteLine("---"); Console.WriteLine("channel:" + channelData.ChannelName); Console.WriteLine("occupancy:" + channelData.Occupancy); Console.WriteLine("Occupants:"); if (channelData.Occupants != null && channelData.Occupants.Count > 0) { for (int index = 0; index < channelData.Occupants.Count; index++) { PNHereNowOccupantData occupant = channelData.Occupants[index]; Console.WriteLine(string.Format("uuid: {0}", occupant.Uuid)); Console.WriteLine(string.Format("state:{1}", (occupant.State != null) ? pubnub.JsonPluggableLibrary.SerializeToJsonString(occupant.State) : "")); } } } } } ));
- Returning State: Requires Presence add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-PNResult<PNHereNowResult> herenowResponse = await pubnub.HereNow() .Channels(new string[] { // who is present on those channels? "my_channel" }) .IncludeState(true) // include state with request (false by default) .IncludeUUIDs(true) // if false, only shows occupancy count .ExecuteAsync(); PNHereNowResult herenowResult = herenowResponse.Result; PNStatus status = herenowResponse.Status; //handle it
{ "status" : 200, "message" : "OK", "service" : "Presence", "uuids" : [ { "uuid" : "myUUID0" }, { "state" : { "abcd" : { "age" : 15 } }, "uuid" : "myUUID1" }, { "uuid" : "b9eb408c-bcec-4d34-b4c4-fabec057ad0d" }, { "state" : { "abcd" : { "age" : 15 } }, "uuid" : "myUUID2" }, { "state" : { "abcd" : { "age" : 24 } }, "uuid" : "myUUID9" } ], "occupancy" : 5 }
- Return Occupancy Only: Requires Presence add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return only the
occupancy
information for a single channel by specifying the channel and settingUUIDs
to false:PNResult<PNHereNowResult> herenowResponse = await pubnub.HereNow() .Channels(new string[] { // who is present on those channels? "my_channel" }) .IncludeState(false) // include state with request (false by default) .IncludeUUIDs(false) // if false, only shows occupancy count .ExecuteAsync(); PNHereNowResult herenowResult = herenowResponse.Result; PNStatus status = herenowResponse.Status; //handle it
{ "status": 200, "message": "OK", "payload": { "channels": { "81d8d989-b95f-443c-a726-04fac323b331": { "uuids": [ "70fc1140-22b5-4abc-85b2-ff8c17b24d59" ], "occupancy": 1 }, "81b7a746-d153-49e2-ab70-3037a75cec7e": { "uuids": [ "91363e7f-584b-49cc-822c-52c2c01e5928" ], "occupancy": 1 }, "c068d15e-772a-4bcd-aa27-f920b7a4eaa8": { "uuids": [ "ccfac1dd-b3a5-4afd-9fd9-db11aeb65395" ], "occupancy": 1 } }, "total_channels": 3, "total_occupancy": 3 }, "service": "Presence" }
- Returning UUIDs and occupancy for all channels: Requires Presence add-onRequires that the Presence add-on is enabled with Global Here Now checked for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return the list of
UUIDs
andoccupancy
for allchannels
by omitting the channel:PNResult<PNHereNowResult> herenowResponse = await pubnub.HereNow() .Channels(new string[] { // who is present on those channels? "my_channel" }) .IncludeState(false) // include state with request (false by default) .IncludeUUIDs(true) // if false, only shows occupancy count .ExecuteAsync(); PNHereNowResult herenowResult = herenowResponse.Result; PNStatus status = herenowResponse.Status; //handle it
{ "total_channels" : 2, "total_occupancy" : 3, "channels" : { "lobby" : { "occupancy" : 1, "uuids" : [ "dara01" ] }, "game01" : { "occupancy" : 2, "uuids" : [ "jason01", "jason02" ] } } }
- Return Occupancy for all channels: Requires Presence add-onRequires that the Presence add-on is enabled with Global Here Now checked for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return only the
occupancy
information(Global Here Now)
by omitting thechannel name
PNResult<PNHereNowResult> herenowResponse = await pubnub.HereNow() .IncludeState(true) // include state with request (false by default) .IncludeUUIDs(true) // if false, only shows occupancy count .ExecuteAsync(); PNHereNowResult herenowResult = herenowResponse.Result; PNStatus status = herenowResponse.Status; //handle it
{ "status": 200, "message": "OK", "payload": { "channels": { "81d8d989-b95f-443c-a726-04fac323b331": { "uuids": [ "70fc1140-22b5-4abc-85b2-ff8c17b24d59" ], "occupancy": 1 }, "81b7a746-d153-49e2-ab70-3037a75cec7e": { "uuids": [ "91363e7f-584b-49cc-822c-52c2c01e5928" ], "occupancy": 1 }, "c068d15e-772a-4bcd-aa27-f920b7a4eaa8": { "uuids": [ "ccfac1dd-b3a5-4afd-9fd9-db11aeb65395" ], "occupancy": 1 } }, "total_channels": 3, "total_occupancy": 3 }, "service": "Presence" }
-
PNResult<PNHereNowResult> herenowResponse = await pubnub.HereNow() .ChannelGroups(new string[] { // who is present on channel groups? "cg1", "cg1", "cg3" }) .IncludeState(true) // include state with request (false by default) .IncludeUUIDs(true) // if false, only shows occupancy count .ExecuteAsync(); PNHereNowResult herenowResult = herenowResponse.Result; PNStatus status = herenowResponse.Status; //handle it
{ occupancy : 4, uuids : ['123123234t234f34fq3dq', '143r34f34t34fq34q34q3', '23f34d3f4rq34r34rq23q', 'w34tcw45t45tcw435tww3'] }
Where Now
Requires Presence add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
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.
Note
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 C# V4 SDK:
pubnub.Uuid(string).QueryParam(Dictionary<string,object>).WhereNow()
Parameter Type Required Description Uuid
string Optional Uuid
.QueryParam
Dictionary<string, object> Optional Dictionary object
to pass name/value pairs as querystring
params with PubNub URL request for debug purpose.Async
Command Deprecated PNCallback
of typePNWhereNowResult
.Execute
Command Yes PNCallback
of typePNWhereNowResult
.ExecuteAsync
None Optional Returns PNResult<PNWhereNowResult>
.
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:
PNResult<PNWhereNowResult> wherenowResponse = await pubnub.WhereNow()
.ExecuteAsync();
PNWhereNowResult wherenowResult = wherenowResponse.Result;
PNStatus status = wherenowResponse.Status;
// returns a pojo with channels
// channel groups which I am part of.
Returns
The WhereNow()
operation returns a PNResult<PNWhereNowResult>
which contain the following properties:
Property Name | Type | Description |
---|---|---|
Result | PNWhereNowResult | Returns a PNWhereNowResult object. |
Status | PNStatus | Returns a PNStatus object. |
PNWhereNowResult
contains the following properties:
Property Name | Type | Description |
---|---|---|
Channels | List | The list of channels where the UUID is present. |
Other Examples
Get a list of channels synchronously:
pubnub.WhereNow() .Execute(new PNWhereNowResultExt( (result, status) => { // returns a pojo with channels // channel groups which I am part of. } ));
Obtain information about the current list of channels of some other UUID
PNResult<PNWhereNowResult> wherenowResponse = await pubnub.WhereNow() .Uuid("some-other-uuid") // uuid of the user we want to spy on. .ExecuteAsync(); PNWhereNowResult wherenowResult = wherenowResponse.Result; PNStatus status = wherenowResponse.Status; // returns a pojo with channels // channel groups which "some-other-uuid" part of.ere_now_example_1
User State
Requires Presence add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
The state API is used to set/get key/value pairs specific to a subscriber Uuid
.
State information is supplied as a Generic Dictionary object(Dictionary<string, object>) of key/value pairs.
Method(s)
-
pubnub.SetPresenceState().Channels(Array).ChannelGroups(Array).State(Dictionary<string, object>).Uuid(string).QueryParam(Dictionary<string,object>)
Parameter Type Required Description Channels
Array Optional Channels
to setstate
.ChannelGroups
Array Optional ChannelGroups
to setstate
.State
Dictionary<string, object> Optional State
to set.Uuid
string Optional Uuid
QueryParam
Dictionary<string, object> Optional Dictionary object
to pass name/value pairs as querystring
params with PubNub URL request for debug purpose.Async
PNCallback Deprecated PNCallback
of typePNSetStateResult
.Execute
PNCallback Yes PNCallback
of typePNSetStateResult
.ExecuteAsync
None Optional Returns PNResult<PNSetStateResult>
. -
pubnub.GetPresenceState().Channels(Array).ChannelGroups(Array).Uuid(string).QueryParam(Dictionary<string,object>)
Parameter Type Required Description Channels
Array Optional Channel
name to fetch thestate
.ChannelGroups
Array Optional ChannelGroups
name to fetch thestate
.Uuid
string Optional Uuid
QueryParam
Dictionary<string, object> Optional Dictionary object
to pass name/value pairs as querystring
params with PubNub URL request for debug purpose.Async
PNCallback Deprecated PNCallback
of typePNGetStateResult
.Execute
PNCallback Yes PNCallback
of typePNGetStateResult
.ExecuteAsync
None Optional Returns PNResult <PNGetStateResult>
.
Basic Usage
Dictionary<string, object> myState = new Dictionary<string, object>();
myState.Add("age", 20);
PNResult<PNSetStateResult> setstateResponse = await pubnub.SetPresenceState()
.Channels(new string[] {
"ch1",
"ch2",
"ch3"
})
.State(myState)
.ExecuteAsync();
PNSetStateResult setstateResult = setstateResponse.Result;
PNStatus status = setstateResponse.Status;
// handle set state response
PNResult<NGetStateResult> getstateResponse = await pubnub.GetPresenceState()
.Channels(new string[] {
// channels to fetch state for
"ch1",
"ch2",
"ch3"
})
.ChannelGroups(new string[] {
// channel groups to fetch state for
"cg1",
"cg2",
"cg3"
})
.Uuid("suchUUID") // uuid of user to fetch, or for own uuid
.ExecuteAsync();
PNGetStateResult getstateResult = getstateResponse.Result;
PNStatus status = getstateResponse.Status;
// handle response
Returns
The SetPresenceState()
operation returns a PNResult<PNSetStateResult>
which contains the following properties:
Property Name | Type | Description |
---|---|---|
Result | PNGetStateResult | Returns a PNSetStateResult object. |
Status | PNStatus | Returns a PNStatus object. |
PNSetStateResult
contains the following property:
Property Name | Type | Description |
---|---|---|
State | Dictionary<string, object> | Dictionary of UUIDs and the user states. |
The GetPresenceState()
operation returns a PNResult<PNGetStateResult>
which contains the following properties:
Property Name | Type | Description |
---|---|---|
Result | PNGetStateResult | Returns a PNGetStateResult object. |
Status | PNStatus | Returns a PNStatus object. |
PNGetStateResult
contains the following property:
Property Name | Type | Description |
---|---|---|
StateByUUID | Dictionary<string, object> | Dictionary of UUIDs and the user states. |
Other Examples
-
Dictionary<string, object> myState = new Dictionary<string, object>(); myState.Add("age", 20); pubnub.SetPresenceState() .Channels(new string[] { "ch1", "ch2", "ch3" }) .State(myState) .Execute(new PNSetStateResultExt( (result, status) => { // handle set state response } ));
-
pubnub.GetPresenceState() .Channels(new string[] { // channels to fetch state for "ch1", "ch2", "ch3" }) .ChannelGroups(new string[] { // channel groups to fetch state for "cg1", "cg2", "cg3" }) .Uuid("suchUUID") // uuid of user to fetch, or for own uuid .Execute(new PNGetStateResultExt( (result, status) => { // handle response } ));
Set state for channels in channel group:
Dictionary<string, object> myState = new Dictionary<string, object>(); myState.Add("age", 20); PNResult<PNSetStateResult> setstateResponse = await pubnub.SetPresenceState() .ChannelGroups(new string[] { // apply on those channel groups "cg1", "cg2", "cg3" }) .Channels(new string[] { // apply on those channels "ch1", "ch2", "ch3" }) .State(myState) // the new state .ExecuteAsync(); PNSetStateResult setstateResult = setstateResponse.Result; PNStatus status = setstateResponse.Status; // on new state for those channels
The above code would return the following response to the client:
{ first : "Robert", last : "Plant", age : 59, region : "UK" }