Coding handler

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 "Hanlders" folder. The HTTP  path to the handler we have specified in the previous step via admin console. Let's take a closer look at the content of handler file:

 <?php

 
$uid = $_REQUEST['uid'];
//TODO find user by encrypted user id
//get user profile, friend list, block list
 
?>
<auth result="OK">
<user>
  <uid>$uid</uid>
  <userID>$uid</userID>
  <userName><![CDATA[David]]></userName>
  <smallAvatar><![CDATA[./photos/david_small.png]]></smallAvatar>
  <bigAvatar><![CDATA[./photos/david_big.png]]></bigAvatar>
  <age>23</age>
  <gender>Male</gender>
  <country>UK</country>
  <about>Hello :) I am David</about>
  <xStatus><![CDATA[Hello]]></xStatus>
</user>
<friends>
  <friend>
    <userID>2</userID>
    <userName><![CDATA[Martin]]></userName>
    <smallAvatar><![CDATA[./photos/martin_small.png]]></smallAvatar>
    <xStatus>Hello :)</xStatus>
    <lastOnlineTime>Last time online: 10 Feb, 2010</lastOnlineTime>
  </friend>
</friends>
<blocks>
  <id>5</id>
  <id>9</id>
  <id>10</id>
</blocks>
</auth>
 

 

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

<Auth> section

<auth result="OK"> Returned if authentication passed successfully prior to user info xml.
< auth result="FAIL" msg="Authorization Error"/ > Returned if authentication failed and corresponding message is shown to end user.

<User> section

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

uid Global encrypted user identifier used for the system requests only. Do not change it.Allowed characters: a-zA-Z-0-9
userID Global user identifier used for the communication between chat system and website.Allowed characters: a-zA-Z-0-9
userName Name of the user displayed at front-end.
smallAvatar User's thumbnail image URL which is shown on tabs to the left. The recommended image size is 60x60 pixels
bigAvatar Url to the user's main photo file. The recommended image size is 400x300 pixels
xStatus Applies for Friends list widget and displays user's status.

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 all friends of the current user with corresponding profile information:
userID Global user identifier used for the communication between chat system and website.
userName Name of the user displayed at front-end.
smallAvatar User's thumbnail image URL which is shown on tabs to the left. The recommended image size is 60x60 pixels
xStatus Applies for Friends list widget and displays user's status.
lastOnlineTime Indicates the last time a user was seen on the website.

<Block> section

This node lists IDs of the users who are blocked by the current user.

 

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 step #2 of "JS and Presence pixel setup" paragraph where we have embedded presence code with random UID parameter  - " z5messenger.uid = '2010'; " The value of this parameter has passed through streaming media server and arrived via GET method to handler. In our sample we read query string and assign " $uid " variable with the value of " $_REQUEST['uid']; ".

For the simplicity sake, the same variable ($uid) is set for both xml nodes: < uid > and < userID >. 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://your-domain.com/messenger7/handlers/profile.hanlder.php?uid=2010

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 streaming media server receives correct response.

In order to reduce the number of requests sent to your website during authentication Site Messenger makes only one request to handler when the page with presence code is loaded for the first time. The next page with presence pixel embedded will get profile data from the cache stored on media server side.

This can make troubleshooting a bit complicated when integration is in progress and handler incurs multiple changes. Add the following line in presence code instructing media server to call handler each time a new page is loaded - z5messenger.Refresh(); . Remove this line when integration is over to increase performance:

z5messenger.uid = '2010';

z5messenger.Refresh();

z5messenger.StartPresence();