Presence
In your chat app, you might want to graphically show up-to-date information on all users present on a given channel, showing if they are online, offline, active, or away.
Unity Chat SDK provides methods and options to determine user's presence on the channel level. To do that, Unity Chat SDK uses the PubNub Presence API. It provides a set of convenience methods for checking which channels a given user is subscribed to. Importantly, you can stream presence events and always get real-time information about the user's channel presence. You can also set dynamic custom state for users on one or more channels. This custom state persists on a channel as long as the user stays subscribed. Some examples of custom states are to add your score, game state, or location in an application if it changes frequently.
Channel presence
These methods let you monitor who is subscribed to a given channel ("present" on that channel).
Requires Presence
All channel presence methods in this section require that Presence is enabled for your app's keyset in the Admin Portal.
You can retrieve similar information for presence with different methods by calling them on the User
, Channel
, or Chat
object. Depending on the chosen method, you must provide a different input information set.
Return channels where user is present
You can return a list of channels where a given user is present with:
WherePresent()
called on theUser
objectWherePresent()
called on theChat
object.
Both of these methods have the same name and give the same output. The only difference is that you call a given method either on the Chat
or the User
object. Depending on the object, you either have to specify the ID of the user whose presence you want to check or not because it's already known.
Method signature
These methods take the following parameters:
-
WherePresent()
(on theUser
object)user.WherePresent()
-
WherePresent()
(on theChat
object)chat.WherePresent(
string userId
)
Input
Parameter | Type | Required in the User object method | Required in the Chat object method | Default | Description |
---|---|---|---|---|---|
userId | string | No | Yes | n/a | Unique identifier (up to 92 UTF-8 characters) of the user whose presence you want to check. |
Output
This method returns a List<string>
with all channel IDs on which the given user is present.
Basic usage
Get a list of channels on which the support_agent_15
user is present.
-
WherePresent()
(on theUser
object)if (!chat.TryGetUser("support_agent_15`", out var user))
{
Console.WriteLine("Couldn't find user!");
return;
};
var channelIds = user.WherePresent() -
WherePresent()
(on theChat
object)// reference the "chat" object and invoke the "wherePresent()" method.
var channelIds = chat.WherePresent("support_agent_15")
Check user's channel presence
You can return information if the user is present on a specified channel with:
IsPresentOn()
called on theUser
objectIsUserPresent()
called on theChannel
object.IsPresent()
called on theChat
object.
All of these methods give the same output. The only difference is that you call a given method on the User
, Channel
, or Chat
object. Depending on the object, you have to specify the ID of the user whose presence you want to check, the channel ID where you want to check user's presence, or both user and channel IDs.
Method signature
These methods take the following parameters:
-
IsPresentOn()
(on theUser
object)user.IsPresentOn(
string channelId
) -
IsUserPresent()
(on theChannel
object)channel.IsUserPresent(
string userId
) -
IsPresent()
(on theChat
object)chat.IsPresent(
string userId,
string channelId
)
Input
Parameter | Type | Required in the User object method | Required in the Channel object method | Required in the Chat object method | Default | Description |
---|---|---|---|---|---|---|
userId | string | No | Yes | Yes | n/a | Unique ID (up to 92 UTF-8 characters) of the user whose presence you want to check. |
channelId | string | Yes | No | Yes | n/a | Unique identifier of the channel where you want to check the user's presence. |
Output
Returns information on whether a given user is present on a specified channel (true
) or not (false
).
Basic usage
Find out if the support_agent_15
user is present on the support
channel.
-
IsPresentOn()
(on theUser
object)if (!chat.TryGetUser("support_agent_15`", out var user))
{
Console.WriteLine("Couldn't find user!");
return;
};
var isPresentOn = user.IsPresentOn("support") -
IsUserPresent()
(on theChannel
object)if (!chat.TryGetChannel("support", out var channel))
{
Console.WriteLine("Couldn't find channel!");
return;
};
var isPresent = channel.IsUserPresent("support_agent_15") -
IsPresent()
(on theChat
object)var isPresent = chat.IsPresent("support_agent_15", "support")
Return all users present on channel
You can return a list of users present on the given channel with:
WhoIsPresent()
called on theChannel
objectWhoIsPresent()
called on theChat
object.
Both of these methods have the same name and give the same output. The only difference is that you call a given method either on the Chat
or the Channel
object. Depending on the object, you either have to specify the ID of the channel where you want to check all present users or not because it's already known.
Method signature
These methods take the following parameters:
-
WhoIsPresent()
(on theChannel
object)channel.WhoIsPresent()
-
WhoIsPresent()
(on theChat
object)chat.WhoIsPresent(
string channelId
)
Input
Parameter | Type | Required in the Channel object method | Required in the Chat object method | Default | Description |
---|---|---|---|---|---|
channelId | string | No | Yes | n/a | Unique identifier of the channel where you want to check all present users. |
Output
This method returns a List<string>
with all user IDs on the channel.
Basic usage
Get a list of users that are present on the support
channel.
-
WhoIsPresent()
(on theChannel
object)if (!chat.TryGetChannel("support", out var channel))
{
Console.WriteLine("Couldn't find channel!");
return;
};
var userIds = channel.WhoIsPresent() -
WhoIsPresent()
(on theChat
object)var userIds = chat.WhoIsPresent("support")
Get presence updates
Get up-to-date information about the real-time presence of users in the specified channel by subscribing to PubNub Presence events. The OnPresenceUpdate
event lets you constantly track who connects to or disconnects from the channel and visually represent that in your chat app through some status, like offline
, online
, active
, away
, or any other.
Event signature
Action<List<string>> OnPresenceUpdate;
Event handler signature
void EventHandler(List<string> users)
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
users | List<string> | Yes | n/a | List of user IDs. |
Basic usage
Get user presence updates on support
channel.
if (!chat.TryGetChannel("support", out var channel))
{
Console.WriteLine("Couldn't find channel!");
return;
};
channel.OnPresenceUpdate += OnPresenceUpdateHandler; // or use lambda
void OnPresenceUpdateHandler(List<string> users)
{
Console.WriteLine($"Users present: {string.Join(", ", users)}");
}