This documentation provides information about how to set up a facebook application that utilizes the facebook platform and Userplane Webchat 2 CSXML API.

More information about the Facebook platform/API can be found at (http://developer.facebook.com).

Description of Contents

After downloading and unzipping the files, you should see the following folders:
/fb – facebook specific files
/client _ this is provided by facebook
/webmessenger _ the contents of this folder you need to modify
/apps _ all files related to the facebook application
/userplane – all files related to the userplane settings and API
/userplane – userplane base files

Inside of /fb/webmessenger/apps:
/images – related images for the facebook app
/sql – database and sql queries
/styles – css styles
ajax.php – some simple ajax function files
attachment.php – functionality for wall/message attachments in facebook
common.inc.php – global common header
config.php – configuration settings
get.php – returns an image
help.php – help page of the app
home.php – home page of the app (not used)
index.php – default page for the canvas url
invite.php – standard facebook invite page
lib.php – collection of helper functions for this app. Contains basic database
connection functions, getters, and updates.
navigate.php – navigation header of the page.
post_remove.php – some cleanup functions after a user uninstalls the app
sajax.php – simple ajax functions to manage facebook sessions
send.php – alias for share.php
share.php – allows user to send notifications. This feature is deprecated.
top.php – header file for userlist
ul.php – this is the userlist feature of webchat
wm.php – this is the webmesseger feature (not implemented).

Inside of /fb/webmessenger/userplane:
/js – contains all the javascript files associated with webmessenger
/ul – contains all the functionalities/features of userlist
/wc – contains all the files for webchat
/wm – contains all the files for webmessenger (not implemented)
cmd.php – contains the default cmd files (provided as a guide by Userplane).
config.inc.php – contains the configuration. You need to edit this file.
index.html – placeholder, ignore this file
presence.php – if you are using presence detection (ignore this file)
sajax.php – simple ajax functions to manage sessions.

User »Facebook »Your Server »Userplane

All Facebook apps require a “callback url” which is the remote path that Facebook looks for when the app is invoked on the app canvas. This is the starting point of the app and allows facebook users to interact with your server. Your server will host the references to Userplane’s communication server. Hence, you are passing along the user information through your server to Userplane’s communication servers via the Userplane API.

From the documentation on facebook, you will see that Facebook always provides unique user id and session data for every callback request to your server. Facebook (and other 3rd party providers) also provide the “facebook client” code that allows you to make simple function calls to interact with Facebook’s REST_based API. An Example of Facebook Function Calls (from /fb/webmessenger/apps/lib.php):

$userInfo = $facebook->api_client-
>users_getInfo($user,array('name','birthday','pic','sex','current
_location'));

Using the Facebook API client, we request a .getInfo and specify an array of user data to retrieve.
Complete list of user.getInfo data that can be retrieved can be found on facebook’s documentation:

http://developer.facebook.com/documentation.php?v=1.0&method=users.getInfo

Step 1: Set up Webchat Files

If necessary you can update facebook client: http://developers.facebook.com/clientlibs/facebook-platform.tar.gz the script is using php5 library. The facebook client is located at fb/client folder.
You need upload your files into the root of your chat folder. Then you need to configure webchat

See some details below: In fb/webmessenger/userplane/config.inc.php set red parameters to yours:

$strFlashcomServer = "Your flashcom server";
$strDomainID = "Your domain id";
$presenceID = "Your presenceID from Userplane";
$strPassword = "Your presence password";
$strLocale = "english";
$notify = false;
$wmURL = $baseCallBackUrl . 'userplane/wm/wm.php';
$cmdURL = $baseCallBackUrl . 'userplane/cmd.php';
$strInitialRoom = "Facebook";                
$strInstanceID = INSTANCEID;

Create tables in the Db using fb/webmessenger/apps/sql/db.sql

Step 2: Setup Facebook

1. In our example your facebook callback URL will be http://yourdomain.com/fb/webmessenger/apps/
2. Go to http://www.facebook.com/developers/
3. Press: “Set Up New Application”.
4. Fill out the form. Enter chat name and press the checkbox.
5. Press “Edit Settings”
6. Fill out the form.

In fb/webmessenger/apps/config.php set red parameters to yours:

define('API_KEY','Your Facebook Application API');
define('SECRET','Your Facebook Application SECRET');
$baseCallBackUrl = "http://yourdomain.com/fb/webmessenger/";
$canvasPageUrl = "http://apps.facebook.com/Your canvas page url/";
define('INSTANCEID', "Your instance id");
 
//Database Connection Parameters
define('DB_HOST', 'Your host');
define('DB_USER','Your user');
define('DB_PASSWORD','Your password');
define('DB_NAME','Your db name');

All portions of the facebook code lives in /fb/webmessenger/apps. However, we included the facebook client that facebook provides at the time of this writing. The facebook client files are located at /fb/client. This client file is a collection of facebook functions that simplifies the REST_based API calls to facebook. Using simple function calls, you can get the data you need without parsing XML or JSON responses.

The file you need to configure for the purpose of this example is config.php. Here you will set the parameters specific to your userplane account.

In fb/webmessenger/apps/config.php set red parameters to yours:

define('API_KEY','Your Facebook Application API');
define('SECRET','Your Facebook Application SECRET');
$baseCallBackUrl = "http://yourdomain.com/fb/webmessenger/";
$canvasPageUrl = "http://apps.facebook.com/Your canvas page url/";
define('INSTANCEID', "Your instance id");
//Database Connection Parameters
define('DB_HOST', 'Your host');
define('DB_USER','Your user');
define('DB_PASSWORD','Your password');
define('DB_NAME','Your db name');

You will notice in the latter part of the configuration file, a MySQL database connection string is required. The purpose of the database is to temporarily store user data while the user is in session. Subsequent request for user data can then be pulled by our server’s database then making the roundtrip API call to Facebook servers each (and every time) it is required. You can also experiment with session variables (stored in runtime memory) – but be cautious if your app’s userbase and concurrent users scales too quickly, you may need additional RAM to prevent your server from crashing. Also, in accordance with the Facebook terms of service (TOS), be sure to clear out any user data within 24 hours – you can easily achieve this by running a cron job to remove expired data. (The method to do that is out of scope of this documentation). In the sample, we provided the sample SQL query you can use to create the necessary tables. You can find that in

/fb/webmeseenger/apps/sql/db.sql which is listed here for your convenience:

SET SQL_MODE="NO_AUTO_VALUE_ON_ZERO";
-- Database: `userplane_facebook`
-- Table structure for table `admin_connection_list`
CREATE TABLE IF NOT EXISTS `admin_connection_list` (
`id` int(11) unsigned NOT NULL auto_increment,
`user_id` varchar(255) NOT NULL default '',
`network` varchar(255) NOT NULL default '',
`datetime` timestamp NOT NULL default CURRENT_TIMESTAMP on update
CURRENT_TIMESTAMP,
`uid` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`),
UNIQUE KEY `user_id` (`user_id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
-- Table structure for table `tbl_facebook_profile`
CREATE TABLE IF NOT EXISTS `tbl_facebook_profile` (
`id` int(11) unsigned NOT NULL auto_increment,
`user_id` int(10) unsigned NOT NULL default '0',
`user_name` varchar(100) NOT NULL default '',
`user_sex` varchar(20) NOT NULL default '',
`user_age` varchar(20) NOT NULL default '',
`user_city` varchar(100) NOT NULL default '',
`user_state` varchar(100) NOT NULL default '',
`user_country` varchar(100) NOT NULL default '',
`user_photo` varchar(200) NOT NULL default '',
`user_online` enum('Y','N') NOT NULL default 'N',
`user_datetime` datetime default NULL,
`user_session_key` varchar(255) NOT NULL default '',
`debug` int(11) NOT NULL default '0',
PRIMARY KEY (`id`),
KEY `IDX_DT` (`user_datetime`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

Hello,
Here is the direct invocation code for Userplane’s ad server associated with a Userplane Money Account. You need two variables:

- You need your DomainID
- You need your ZoneID

1. Sign up for a Userplane Money account at: http://www.userplane.com/promos/money.cfm

2. Login to your account: http://www.userplane.com/chatlite/directory/

3. Go to the “Get Started Page” at: http://www.userplane.com/chatlite/resources.cfm?roomSelection= and find your DomainID on the bottom of the page.

4. Click on the “Userplane Money” link, agree to the TOS, and submit your payment information!

Email the following info to Derek and be nice.

to: derek@userplane.com
fr: yourname@yourdomain.com

Hey Derek, I need a ZoneID setup for a Userplane Money revshare. Please send me banner code for:

( ) 728 x 90 (Leaderboard)
( ) 468 x 60 (Full)
( ) 300 x 250 (Medium Rectangle)

My DomainID is: (Enter your Domain ID from Userplane Money)
My URL is: (URL where the ads will be appearing (if Facebook, note the Facebook APP))

Thanks
YOURNAME

*note: if you are an existing free integrated client, and reside in the US, please send an email to janet@userplane.com letting her know to get approval. Upon being approved, please use the appropiate code that is provided below labeled “FOR EXISTING INTEGRATED CLIENTS”.

When your ZONE ID is sent back - place the following code on your app page:

<script language='JavaScript' type='text/javascript'>
<!--
   var awrz_rnd = Math.floor(Math.random()*99999999999);
   var awrz_protocol = location.protocol.indexOf('https')>-1?'https:':'http:';
   if (!document.phpAds_used) document.phpAds_used = ',';
   document.write ("<" + "script language='JavaScript' type='text/javascript' src='");
   document.write (awrz_protocol+"//subtracts.userplane.com/mmm/adjs.php?n=a86d710f");
 
   // Change the DOMAIN_ID and ZONE_ID below
   document.write ("&domainid=ENTER_YOUR_DOMAIN_ID_HERE");
   document.write ("&zoneid=ENTER_YOUR_ZONE_ID_HERE&target=_blank");
   document.write ("&exclude=" + document.phpAds_used);
   document.write ("&loc=" + escape(window.location));
   if (document.referrer)
      document.write ("&referer=" + escape(document.referrer));
   document.write ('&r=' + awrz_rnd);
   document.write ("&ct0=" + escape(document.phpAds_ct0));
   document.write ("'><" + "/script>");
//-->
</script>

Leaderboard (728×90)

<iframe id='af7841f1' name='af7841f1' src='http://subtracts.userplane.com/mmm/adframe.php?n=af7841f1&zoneid=ENTER_YOUR_ZONE_ID_HERE&domainid=ENTER_YOUR_DOMAIN_ID_HERE&target=_blank&refresh=30' framespacing='0' frameborder='no' scrolling='no' width='728' height='90'><a href='http://subtracts.userplane.com/mmm/adclick.php?n=af7841f1' target='_blank'><img src='http://subtracts.userplane.com/mmm/adview.php?&zoneid=ENTER_YOUR_ZONE_ID_HERE&n=af7841f1' border='0' alt=''></a></iframe>

Full (468×60)

<iframe id='af7841f1' name='af7841f1' src='http://subtracts.userplane.com/mmm/adframe.php?n=af7841f1&zoneid=ENTER_YOUR_ZONE_ID_HERE&domainid=ENTER_YOUR_DOMAIN_ID_HERE&target=_blank&refresh=30' framespacing='0' frameborder='no' scrolling='no' width='468' height='60'><a href='http://subtracts.userplane.com/mmm/adclick.php?n=af7841f1' target='_blank'><img src='http://subtracts.userplane.com/mmm/adview.php?&zoneid=ENTER_YOUR_ZONE_ID_HERE&n=af7841f1' border='0' alt=''></a></iframe>

Medium Rectangle (300×250)

<iframe id='af7841f1' name='af7841f1' src='http://subtracts.userplane.com/mmm/adframe.php?n=af7841f1&zoneid=ENTER_YOUR_ZONE_ID_HERE&domainid=ENTER_YOUR_DOMAIN_ID_HERE&target=_blank&refresh=30' framespacing='0' frameborder='no' scrolling='no' width='300' height='250'><a href='http://subtracts.userplane.com/mmm/adclick.php?n=af7841f1' target='_blank'><img src='http://subtracts.userplane.com/mmm/adview.php?&zoneid=ENTER_YOUR_ZONE_ID_HERE&n=af7841f1' border='0' alt=''></a></iframe>

Webchat (728×90)

<frameset rows="*,145" framespacing="0" frameborder="no" border="0">
	<frame src="Webchat Frame" name="Webchat_Frame" scrolling="NO" noresize>
	<frame src="http://subtracts.userplane.com/mmm/bannerstorage/ch_int_frameset.html?app=wc&zoneID=ENTER_YOUR_BANNER_ZONE_ID&textZoneID=ENTER_YOUR_TEXT_ZONE_ID&domainid=ENTER_YOUR_DOMAIN_ID_HERE" name="Ad_Frame" scrolling="NO" noresize></frameset>

Webmessenger (468×60)

<frameset rows="*,108" framespacing="0" frameborder="no" border="0">
	<frame src="Webmessenger Frame" name="Webmessenger_Frame"  scrolling="NO" noresize>
	<frame src="http://subtracts.userplane.com/mmm/bannerstorage/ch_int_frameset.html?app=wm&zoneID=ENTER_YOUR_BANNER_ZONE_ID&textZoneID=ENTER_YOUR_TEXT_ZONE_ID&domainid=ENTER_YOUR_DOMAIN_ID_HERE" name="Ad_Frame" scrolling="NO" noresize></frameset>

*upon approval

Load it up, check your stats in the admin at: http://www.userplane.com/chatlite/directory/index.cfm

Remember, Userplane loves you.