UserIDs and Friends

UserIDs

In Photon, a player is identified using a unique UserID.

You can subscribe to a Photon channel using the same UserID from multiple clients.
You will receive the same messages on each client.
Also all clients connected with the same UserID will be subscribed to the same channels and have the same friends at any given time.

Unique UserIDs

Generally, UserIDs are not intended to be displayed.
Unlike usernames, displaynames or nicknames.
A UserID does not have to be human-readable or very human-friendly.
So you could, for instance, use a GUID as a UserID.

The advantages of keeping a unique UserID per player:

• You preserve your data between game sessions and across multiple devices.
  You can rejoin rooms and resume playing where you stopped.
• You can become known to all players you meet and easily identifiable by everyone.
  You can play with your friends, send them invitations and challenges, make online parties, form teams and guilds, etc.
  You can add user profiles (e.g. experience, statistics, achievements, levels, etc.) and make games more challenging (also using tournaments and leaderboards).
• You could make use of another service to bind Photon UserID to an external unique identifier.
  For instance, Photon UserID could be set to Facebook ID, Google ID, Steam ID, PlayFab ID, etc.
• You can prohibit malicious users from connecting to your applications by keeping a blocklist of their UserIDs and making use of
  Custom Authentication.

Setting UserIDs

Once authenticated, a Photon client will keep the same UserID until disconnected.
The UserID for a client can be set in three ways:

1. Client sends its UserID before connecting by setting AuthenticationValues.UserId.
   This option is useful when you do not use Custom Authentication and want to set a UserID.
2. An external authentication provider returns the UserID on successful authentication. See Custom Authentication. It will override any value sent by the client.
3. Photon Server will assign GUIDs as IDs for users that did not get UserIDs using 1 or 2. So even anonymous users will have UserIDs.

Users List in Public Channels

If you want the client to have more control over the list of the users inside a public channel you can make use of MaxSubscribers and PublishSubscribers.
By design, both options should be used to subscribe to a single channel at a time and not multiple ones.

MaxSubscribers

By default, public channels can have an unlimited number of subscribers.
For some use cases, that number needs to be limited.

Photon Chat public channels can set a limit to the number of subscribers when created.
We call this limit "MaxSubscribers".
Knowing that a public channel is created when the first user subscribes to it, this means that, MaxSubscribers will be set by the first user who subscribes to the channel.

C#

chatClient.Subscribe("theFiftyClan", creationOptions: new ChannelCreationOptions { MaxSubscribers = 50 });

If the client sets MaxSubscribers to 0, the public channel will have the default behaviour of unlimited subscribers.

To know the MaxSubscribers per channel use the channel class's property/field with the same name, e.g. in C# SDKs: ChatChannel.MaxSubscribers.

PublishSubscribers

By default, the Photon Chat client does not keep track of the users inside a public channel.
It can only cache the list of the senders of the received messages by channel.

For some use cases, the chat client needs to have the list of the currently subscribed users at any given time.
This feature, we call it "PublishSubscribers", can be enabled per channel during channel creation.
Knowing that a public channel is created when the first user subscribes to it, this means that, "PublishSubscribers" can be activated by the first user who subscribes to the channel.

C#

chatClient.Subscribe("specialChannel", creationOptions: new ChannelCreationOptions { PublishSubscribers = true });

The client will know if the subscription went successfully or not via an event.
You can be notified about this using the same callback used for normal public channels:

C#

IChatClientListener.OnSubscribed(string[] channels, bool[] results)

When PublishSubscribers is enabled inside a public channel, a client who subscribes to it will receive the list of previously subscribed users.
Also, whenever a user unsubscribes from the same channel or a new user subscribes to it, the client will be notified using an event.
These two mechanisms, the initial list of subscribers and future events of subscribers list changes, constitute the PublishSubscribers feature.
They allow the client to always have an up-to-date list of subscribers per public channel.

To know if a public channel has PublishSubscribers enabled, use the channel class's property/field with the same name, e.g. in C# SDKs: ChatChannel.PublishSubscribers.
To get the list of subscribers of a public channel, use the channel class's property/field with the same name, e.g. in C# SDKs: ChatChannel.Subscribers.

To be notified with subscribers list changes, subscribe to the callbacks:

C#

IChatClientListener.OnUserSubscribed(string channel, string user)

and

C#

IChatClientListener.OnUserUnsubscribed(string channel, string user)

MaxSubscribers can also be used in parallel with PublishSubscribers.

C#

chatClient.Subscribe("evenMoreSpecialChannel", creationOptions: new ChannelCreationOptions { PublishSubscribers = true, MaxSubscribers = 16 })

However, when combined, MaxSubscribers will be capped to 1000.
This means that when PublishSubscribers is enabled, the client can set MaxSubscribers to a value between 0 and 1000.
If the client sets MaxSubscribers to 0, the public channel will have MaxSubscribers set to 1000.

Friends

Photon Chat keeps your friends list in memory as long as you are connected.
However this list is not persisted between sessions.
You may need an external service for that.

Adding and Removing Friends

You can add friends on Photon Chat and subscribe to his/her status updates.
If you do so, you will receive an event every time that same friend changes his/her status or goes offline.

Adding friends will result in receiving an initial status per friend and will trigger the respective callback.

You can add or remove up to 512 friends at once.

To add friends to Photon Chat:

C#

chatClient.AddFriends(friendsUserIds);

When you no longer need to listen to those events you could remove that friend and unsubscribe from his/her status updates.

To remove friends from Photon Chat:

C#

chatClient.RemoveFriends(friendsUserIds);

To receive status updates from your friends you should implement:

C#

void IChatClientListener.OnStatusUpdate(string user, int status, bool gotMessage, object message);

Updating Status

You can update your status on Photon Chat and broadcast this to all your friends.

Here is how to do it:

C#

chatClient.SetOnlineStatus(statusCode);

You can find a list of predefined online status codes in ChatUserStatus class.
If you set your online status to ChatUserStatus.Invisible then all your friend will see you as ChatUserStatus.Offline instead.
You are free to add custom ones not available on that list and used by your application.

By design, Photon Chat does not implicitly broadcast ChatUserStatus.Online or any other status when you connect.
That is why you need to explicitly set yourself to online as soon as you are connected if you want to have this behaviour.

Also by design, if you did not explicitly set your status to ChatUserStatus.Invisible or ChatUserStatus.Offline, your friends will know when you are disconnected from Photon Chat.
They will receive a status update with status set to ChatUserStatus.Offline.

Optionally you can add a message with the updated status code.
The message will not be sent in case of the two special status codes ChatUserStatus.Offline and ChatUserStatus.Invisible.

In this case use the overload method that takes two parameters:

C#

chatClient.SetOnlineStatus(statusCode, statusMessage);

You could use the status update feature to exchange any type of data (that Photon can serialize) with your friends.
It is not limited to strings only.