• Examples (iOS)
• Examples (Java/Android)
• Examples (C++)
Server API Documentation


» The login phase

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

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

Zone  Config Tool

From here you can double click (or select and click the edit button) any Zone name and proceed with the configuration of the Zone settings. Please refer to the Zone Configurator documentation for usage instructions.

» Default vs custom login

Before we proceed to show the basic code for the login request we need to point our attention to one very important setting in the Zone called Use custom login, which is found right after the Zone name in the Zone Configurator.

The value of this parameter (which is by default set to off) determines which controller will receive and handle the login request.

» Logging in a Zone

The login phase is always initiated from the client side by sending a LoginRequest to the Server. This requires several parameters:

Logging in a Zone requires just a few lines of code: in essence you just need to register the SmartFox class instance to receive the SFSEvent.LOGIN and SFSEvent.LOGIN_ERROR events and proceed with the request.

var sfs:SmartFox = new SmartFox();
sfs.addEventListener(SFSEvent.LOGIN, onLogin);
sfs.addEventListener(SFSEvent.LOGIN_ERROR, onLoginError);

// This code is executed after the connection
sfs.send( new LoginRequest("", "", "SimpleChat") );
public function onLogin(evt:SFSEvent):void
	trace("Login success: " + evt.params.user.name);

public function onLoginError(evt:SFSEvent):void
	trace("Login failed: " + evt.params.errorMessage);

In the above ActionScript 3 example we use a default login (handled by the System Controller) and pass an empty string as the user name thus obtaining an auto-generated guest name.

When you load the external configuration file there is no need to pass the Zone name to the LoginRequest constructor, the API will get it automatically.

Here's another LoginRequest snippet:

sfs.send( new LoginRequest("Fozzie") );

In this case we send our user name, no password, and by not specifying the Zone name the system will use the one loaded from the configuration file.

» What could go wrong?

During the login phase the Server performs a number of validations that could block the process and cause the SFSEvent.LOGIN_ERROR event to be fired. Let's see in brief which problems could arise.

» 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" and you can add more, if necessary. A Room Group is nothing more than a string id that it is used to organize Rooms in different categories called Room Groups.
    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 about any "interesting" changes (e.g. a new Room is created or another one is removed, etc).

You can read additional informations about Groups in this document.

» Custom login

One very common use case in the login process is to write an Extension that handles the user credentials and checks them against your database. In order to do so you will need a few preliminary steps.

  1. Setup a database connection. You can follow this tutorial on how to configure SFS2X to communicate with your DB.
  2. Prepare a simple Extension that will execute the validation of the user name and password. We provide an in-depth overview of the Extensions and a login how-to tutorial.
  3. Turn on the Use custom login setting in the Zone Configurator and setup your Extension.