The Login phase

In the previous chapter we've seen how to open a connection to SmartFoxServer and have mentioned that logging in a Zone is necessary before the client can interact with the server API and other users.

In order to see the Zones available in the server and create new ones you can use the SmartFoxServer Admin Tool. In the left side bar of the tool choose Zone Configurator and a list of all Zones will be shown:

From here you can select any Zone in the list and proceed with its configuration. Please refer to the Zone Configurator documentation for usage instructions.

Logging in a Zone

To log in a Zone we must send a LoginRequest to the Server, with the following parameters:

• User name: a user name
• Password: (optional) a password
• Zone name: the name of a Zone; it must exist on the server side
• Extra parameters: (optional) an SFSObject containing extra custom data; typically this is used in conjunction with an Extension based login in order to send custom data to the server side.

Let's review the example we have seen in the overview

C#

var sfs = new SmartFox();
sfs.AddEventListener(SFSEvent.CONNECTION, OnConnection);
sfs.AddEventListener(SFSEvent.LOGIN, OnLogin);
sfs.AddEventListener(SFSEvent.LOGIN_ERROR, OnLoginError);

var cfgData = new ConfigData();
cfgData.Zone = "BasicExamples";

sfs.Connect(cfgData);

private void OnConnection(ApiEvent evt) {
    var success = (Boolean) evt.Param[EventParam.Success]!;

    if (success)
    {
        sfs.Logger.Info("Connection success");
        sfs.Send(new LoginRequest("Kermit the Frog"));
    } else {
        sfs.Logger.Info("Connection Failed: " + evt.Params[EventParam.ErrorMessage]);
    }
}


private void OnLogin(ApiEvent evt) {
    User user = (User) evt.GetParam(EventParam.User)!;
    sfs.Logger.Info("Logged in successfully as: " + user.Name);
}


private void onLoginError(ApiEvent evt) {
    sfs.Logger.Info("Login error: " + evt.Params[EventParam.ErrorMessage]);
}

By default the BasicExamples Zone allows guest users which means that any user can login with a unique name and there is no credential check performed. This is fine for just testing locally, but in a real use case we will need to check the user's name and password against a database, which we'll discuss later.

You may have noticed that in the OnLogin method we refer to a sfs.Myself object. Every client connected to the server is represented by a SFSUser object and MySelf is that which represents us, once we're connected. This is useful to access the User's state and other properties that you'll encounter when you study our tutorials.

What could go wrong?

During the login phase the Server performs a number of validations that could block the process and trigger an SFSEvent.LOGIN_ERROR event. Here's a list of the main issues that can arise:

• Missing Zone: the requested Zone name doesn't correspond to any available Zones on the server
• Zone full: the requested Zone has reached the maximum amount of Users allowed (configurable in the AdminTool's Zone Configurator module)
• Server full: the SmartFoxServer instance has reached its maximum capacity and cannot accept more Users
• Duplicate names: no two users can have the same exact name in a Zone. This is intended in case sensitive mode, so Users "Kermit" and "kERMit" can co-exist in the same Zone
• Bad words in user name: a Zone can be configured to filter bad words in user names. If this option is active an error will trigger if a user name matches the provided word list
• Banned user name: if the provided User name was banned by a moderator or administrator the client will not be able to join the Zone until the banishment expires

The Room List

In the first code example we have seen that when the login is successful the server joins the user in the requested Zone. Behind the scenes SmartFoxServer also performs a few other operations that we need to know about.

1. Auto-subscribe the default Room Groups: in the Zone Configurator you can declare a number of public Room Groups. By default there is only one Group called "default" but you can add more, if necessary. A Room Group is like a category tag: every room is tagged with a specific Group to keep them organized by category. Upon login the client will be subscribed to all the Groups specified in the Default Room Groups setting of the Zone.

2. Populate the client with the initial Room List: behind the scenes the client receives a Room List which is populated with all the Rooms contained in all subscribed Groups. This operation is done once, at login time, then only small updates will be sent to the client to maintain the Room List up to date with the Server

In the example above the Zone contains three different Room Groups called Europe, America and Asia, each containing a certain amount of Rooms. If we suppose that the Zone's default Group property is set to "Europe,America" the client Room List will be populated with the details of all Rooms in those two groups and will receive updates their state changes (e.g. a new Room is created or removed, the number of users in a certain Room have changed etc.)

You can read additional information about Groups in this document.

Custom Login

As we have mentioned earlier when we're working with an application we'll need to be able to authenticate Users via some custom server-side logic that allows us to check login and password and maybe even more parameters.

This is accomplished using a server Extension, which is custom server side code that is plugged at the Zone/Room level and activated every time a client attempt to login in the Zone.

You will learn how to implement a custom Login Extension in this tutorial. If you're not familiar with Extension development we recommend following the tutorials in their order to avoid skipping crucial information.