Login Handlers

Handler is the most important element in integration process. As per diagram represented in "How site authorization works" section handler generates xml formatted response with all information on the user requesting application. The archive you downloaded from support area contains sample handler file which can be found in "Handlers" folder. The HTTP path to the handler we have specified in the previous step via admin console. Now let's go back to admin console and "Integration section":

Here we have 3 available modes to authorize a user:

Auto Login	If enabled, the chat calls authorization handler and if user is logged in on the main site he/she enters the chat automatically.
Chat Login	Enables/Disables chat authorization. I.e. a user will be offered to enter his username and password on the chat login screen.
Guest Mode	Indicates if non registered users (guests) can enter the chat.

For each of the modes chat server calls its own handler

Auto Login	yourdomain/chat71/handlers/auto.login.handler.php?uid=2012
Chat Auth	yourdomain/chat71/handlers/chat.login.handler.php?login=David&password=123
Guest Mode	yourdomain/chat71/handlers/guest.login.handler.php?userName=David

Auto Login and Chat Auth modes have identical xml response. It doesn't matter what scripting language or methods to generate xml you use the only requirement is the correct xml structure as the one demonstrated below:

<location>London, UK</location>

<level>regular</level>

<profileUrl>http://yourdomain/profile/David</profileUrl>

</userData>

</login>

The XML result consists of 4 sections auth,user, friends and blocks.

<Auth> Section

<login result="OK">	Returned if authentication passed successfully prior to user info xml.
<login result="FAIL" error="error_authentication_failed"/>	Returned if authentication failed and corresponding message is shown to end user.

<userData> Section

This section is required and always should contain data. If requested user has no photo you just should return default no photo image. Please refer to the table below for nodes description:

id	Global user identifier used for the communication between chat system and website.
name	Name of the user displayed at front-end.
gender	Gender of the user displayed at front-end.
location	Location of the user displayed at front-end.
age	Age of the user displayed at front-end.
photo	Url to the user's main photo file. The recommended image size is 200x150 pixels
thumbnail	User's thumbnail image URL which is shown on tabs to the left. The recommended image size is 38x38 pixels
details	Brief user's introduction.
level	Applicable with Limitations plugin installed only, otherwise return "regular".
profileUrl	It opens new browser window when a user clicks "Full profile" link in user's profile.

It's required to return a value for Photo and Thumbnail parameters. If a user doesn't have profile image you should return default "no photo" image.

Flash player has strict security policy allowing to load resources from the domain it is being initially called from only. If you load profile images from the 3 rd party domain place crossdomain.xml file into the root allowing for flash player connections.

<Friends> Section

This section contains id, name and thumbnail of the current user's friends with corresponding profile information. See Friends/block list integration section of the manual for more details.

<Block> Section

This node lists id, name and thumbnail of the users who are blocked by the current user. See Friends/block list integration section of the manual for more details.

In current "Basic integration" section we are setting up very static authentication model without database connections and sophisticated security mechanism which are covered in-depth in "Advanced integration" section.

Recall "Adding chat to your website" paragraph where we have passed random UID as '2012' parameter for popup and embedded modes:

z5chat.uid = "2012";

The value of this parameter has passed through chat server and arrived via GET method to handler.

Before moving forward to final step we need to make sure our handler returns correct xml response. The most common way to verify output xml is to call handler directly in browser, like this:

http://yourdomain/chat71/handlers/auto.login.handler.php?uid=2012

If you look at source of the page you should see the following:

By taking this step we ensure that authentication has passed successfully and chat server receives correct response.