By John Fronckowiak
April 30, 2008
Computers are hierarchical. We have a desktop and hierarchical files which have to mean everything. - Ted Nelson
Introduction to Userplane
In conjunction with the release of Adobe AIR, AOL's Userplane introduced its latest version of Desktop based on the new Adobe technology. If you already have an existing online community, you can use the AIR implementation of Userplane Desktop, and rebrand it to serve your community. In other words, web sites and developers can build their own customized desktop application, after Userplane has done all the heavy lifting for them, so their users can receive individualized alerts, systems updates, and IM notification without being logged into the site.
Userplane Applications Overview
Userplane provides free social networking tools for web developers. These tools include:
- Userplane Webchat 2 - Provides a turn-key solution for real-time voice and video chat rooms
- Userplane Webmessenger 2 - A web-based instant messenger application with presence and buddylist capabilities
- Userplane Webrecorder - Enables users to record and play back audio/video messages
- Userplane Feeds - Provides integrated content and search functionality within your site; currently, embedded Truveo Video Search is supported, with MapQuest and Relegence (real-time news feeds) coming soon!
Developers can choose to integrate these applications into their sites, using their own user database and authentication, with or without advertising. Developers can deploy Userplane applications for free, supported by integrated advertising. Developers can also choose a model without advertising; however, setup and monthly licensing fees are required to use the Userplane widgets in this configuration. With the integrated Userplane model, applications can also be custom branded. Although these applications can increase the social networking opportunities for the users of your web site, they require users to be actively logged into your web site through their web browser.
Introducing Userplane Desktop
Userplane Desktop is the enhancing component of the Userplane application suite. Desktop allows users to participate in your community even when they're not logged into your web site. Shown in Figure 1, Userplane Desktop can provide a tether to your community when users aren't actively engaged in their web browser on your site. Userplane Desktop is the perfect platform for social network developers who want to take advantage of extending their community beyond their web site, but don't have the resources to develop an application from scratch. With Userplane Desktop, developers simply need to provide the necessary customizations and integration with their site's user authentication.
Figure 1. Userplane Desktop login
Adobe AIR Technology
Userplane Desktop is built using Adobe AIR technology. Adobe AIR provides a runtime environment that supports cross-platform, rich Internet applications. AIR is supported on Windows, Mac OS X, and Linux. AIR has been in development and testing for over a year, with version 1.0 released at the end of February 2008. To run an AIR application, users must have the Adobe AIR runtime client installed.
Requirements
The requirements for using Userplane Desktop need to be discussed from the viewpoint of the Userplane Desktop clients, who host the social networking group, and the users, who will actually install the Userplane Desktop application on their computer. The requirements for the Userplane Desktop clients are:
- Although this might seem obvious, the client needs a community they want to support, including a database or other mechanism for supporting user authentication.
- The desktop presence server-side component supports authentication and configuration of the customized Userplane Desktop installation. The desktop presence component can be hosted using Active Server Pages (ASP), Cold Fusion, or PHP.
- Userplane Webmessenger can be integrated with Userplane Desktop; this requires that Webmessenger already be deployed on the client's web site.
The requirements for Userplane Desktop users are:
- The Adobe AIR runtime environment must be installed; users can obtain Adobe AIR at http://get.adobe.com/air.
- The custom-built Userplane Desktop application must be installed by the user. The client must provide a link for the user to download the Userplane Desktop application.
What Does It Cost?
The entire Userplane suite is supported in free and paid models. The free model is subsidized through advertising, which must be included in the notifications and components that are displayed in Userplane Desktop. In the paid model, pricing is based on the total number of simultaneous users you will support per month. The fee is based on the peak number of users per month, ranging between $25 and $100 per 1,000 connected users per month. A setup fee of $500 is also required. There is no long-term commitment; all paid applications are on a month-to-month model. Discounts are applied if more than one Userplane application is deployed under the paid model. You can find the current pricing, and also order Userplane Desktop, at http://www.userplane.com/desktop/pricing.cfm.
Implementing Userplane Desktop
If you have never used any of the Userplane applications, you might want to consider first deploying Userplane Webmessenger, because it will allow messaging between users actively participating on your web site and those using Userplane Desktop. This will also help you establish a Userplane account for your site.
Userplane Signup
To begin using Userplane Desktop, you'll need to place an order at the Userplane Desktop site, as shown in Figure 2.
Figure 2. Userplane Desktop order site
If you want to learn more about how to integrate Userplane Webmessenger and Userplane Webchat into a WordPress blog site, read my AOL Developer Network blog posts: Userplane Administration, Integrate Userplane Webmessenger with WordPress - Part 1, and Integrate Userplane Webmessenger with WordPress - Part 2.
Before you can configure Userplane Desktop, you need to send an e-mail message to support@userplane.com with the following information:
- You must state that you are deploying Userplane Desktop
- Site or Company Name
- Technical Contact Information
- Business Contact Information
- Desired Usage Plan: Free or Paid (see Pricing Page for more information)
- Web site URL: (e.g., www.yoursite.com>)
Here is the e-mail message I received from Userplane Support (I've omitted the sensitive stuff like user names and passwords):
Here is the info that you will need to finish your integration. The meaning of each is explained in the docs. Please wait up to 4 hours from receipt of this email to begin using our applications, as DNS and server changes require time to propagate. domainID: macdevblog.com XML Path: CSXML Path: http://www.macdevblog.com/wp-content/plugins/upl_wc/CSXML.php WMXML Path: http://www.macdevblog.com/wp-content/plugins/upl_wm/WMXML.php WRXML Path: http://www.macdevblog.com/wp-content/plugins/upl_wr/WRXML.php FlashCom server: flashcom.macdevblog.userplane.com Presence Information: ID: *** GUID: ****************************** Password: ********* DomainID: macdevblog.com Apps Inspector: This is your interface with the flashcom server. It will show any active instances of the applications running as well as any and all errors being returned by your XML interface. http://apps.userplane.com/inspector.html host: flashcom.macdevblog.userplane.com username: ********* password: ********* Apps Admin: Used to check usage history, get updates on new features as well as download any documentation that you need. http://apps.userplane.com/login.cfm username: ********* password: ********* (Failure to properly display ad code will result in disconnection) NOTE: Maximum connection to our applications will be set to 2 until you have added ads and notified us. Here are your AdZoneIDs for advertisement placement: Webchat:**** Minichat:**** Webmessenger:**** Userlist:**** Webrecorder:**** Text:***
You will need the "Presence Information" from the e-mail message to log in into the Desktop Presence Admin site. I've highlighted this section in bold above.
Installation
Now you are ready to deploy the Userplane Desktop DPXML API on your web server. The DPXML API is the location where the Userplane Desktop application will send HTTP GET requests for authentication, or periodically so you can send back notifications and alerts. As I mentioned earlier, the DPXML API is supported for ASP, ColdFusion, and PHP. For the remainder of this article I will focus on the PHP version of the API, while I integrate DPXML with WordPress for authentication. PHP is the natural choice because that is how WordPress is implemented. However, the techniques I describe here are essentially the same, minus syntax differences, for Active Server Pages and ColdFusion. Your choice of DPXML API implementations will be influenced by many factors, including: the server-side languages supported by your web server, your web server itself, and even the language used to support your social networking web site.
You first step will be to download and install the DPXML API on your web server. You can download the various DPXML API implementations at http://wiki.userplane.com/docs/downloads/desktop_presence.zip. After your download and unzip the file you will see a directory for each API implementation. You will need to install the files from the directory of your chosen implementation in an accessible location on your web server. I simply created a userplane directory on my web server, and installed the files there. For the PHP implementation there are two files: DPXML.php and presence.php. You can copy these files to your web server now; however, you will implement configuration and authentication modifications in DPXML.php, so you will need to make sure any changes are reflected in the file on your web server.
After you've deployed the DPXML API on your web server, you need to send a message to support@userplane.com with your presence Domain ID and the URL of the DPXML file, so it can be added to your account. You can continue working on the configuration while you await a response.
DPXML.php Listing
I will be discussing sections of DPXML.php; I've provided my final implementation in Listing 1.
Listing 1. DPXML.php
1 <?php
2 //header( "Content-Type: text/xml; charset=utf-8" );
3
4 //echo( "<!-- COPYRIGHT Userplane 2004
(http://www.userplane.com) -->" );
5 //echo( "<!-- DP version 1.0.0 -->" );
6 include('authenticate.php');
7 include('presence.php');
8
9 $presencePassword = "**YOUR PASSWORD**"; //set this to your
8-character presence password, this is the same as your
general userplane account password and different than the users password that will be sent in the login request
10
11 $strPresenceID = isset($_GET['domainID']) ?
$_GET['domainID'] : null; //this will be your numeric
presence ID that corresponds with the Webmessenger
domainID.
12 $strVersion = isset($_GET['version']) ? $_GET['version'] :
null;
13
14 $strEncryptedUserId = isset($_GET['encrypted_userid']) ?
$_GET['encrypted_userid'] : null;
15 $strSessionID = isset($_GET['sessionid']) ? _GET['sessionid'] : null;
16
17 $strFunction = isset($_GET['function']) ? $_GET['function']
: null;
18
19 if( $strFunction == null )
20 { ?>
21 <desktoppresence>
22
23 <urls>
24 <password>http://www.macdevblog.com/wp-
login.php?action=lostpassword</password>
25 <login>http://www.macdevblog.com/userplane/DPXML.php?function=log
in</login>
26 <verify>http://www.macdevblog.com/userplane/DPXML.php?function=ve
rify</verify>
27 <state>http://www.macdevblog.com/userplane/stateHandler.php</stat
e>
28
29 <im>http://www.macdevblog.com/wp-content/plugins/upl_wm/
wm.php</im>
30 </urls>
31
32 <configuration>
33 <customer_preference_interval>10</customer_preference_interval>
34 <idle_timeout>120</idle_timeout>
35 </configuration>
36 <debug>false</debug>
37
38 <gui>
39
40 <welcome_screen>
41 <image>http://www.macdevblog.com/userplane/MacDevBlogLogo.jpg
</image>
42 <text>Welcome!</text>
43 <eula></eula>
44 </welcome_screen>
45
46 <preferences>
47 <header>http://www.macdevblog.com/userplane/MacDevBlogLogo.jpg
</header>
48 <foreground_color>363796</foreground_color>
49 <background_color>e2e2e2</background_color>
50 </preferences>
51
52 <notifications>
53 <titlebar>
54 <title>YourSocialNetworking Website Desktop</title>
55 <close_button>
56 <normal>http://www.yourSite.com/pathTo/normal.png</normal>
57 <hover>http://www.yourSite.com/pathTo/hover.png</hover>
58 <pressed>http://www.yourSite.com/pathTo/pressed.png</pressed>
59 </close_button>
60 </titlebar>
61 <window_border>363796</window_border>
62 </notifications>
63
64 </gui>
65 <taskbar>
66 <menu>
67 <item before="true" type="browser">
68 <title>About MacDevBlog!</title>
69 <url>http://www.macdevblog.com/about</url>
70 </item>
71 </menu>
72 </taskbar>
73 </desktoppresence>
74 <?php
75 }
76 else if( $strFunction == "login" )
77 {
78
79 $strUserName = isset($_GET['username']) ?
$_GET['username'] : null;
80 $strPassword = isset($_GET['password']) ?
$_GET['password'] : null;
81
82 $strUserID = authenticate($strUserName,$strPassword); //set to the user
numeric userID once they have been verified. This will need to be an
integer to work with the presence system.
83 if(strUserID != "") {
84 $bVerified = "true";
85 } else {
86 $bVerified = "false";
87 }
88
89 $strSessionID = ""; //set this to the users web
sessionID if you are creating one for them. This will
be passed back in all future requests along with the
encrypted userID.
90
91 $strEncryptedUserID =
up_getEncrypted($presencePassword, $strUserID);
92
93
94 if ( $bVerified == "true")
95 {
96 ?>
97 <login>
98 <sessionid><?php echo($strSessionID);
?></sessionid>
99 <encrypted_userid><?php
echo($strEncryptedUserID); ?></encrypted_userid>
100
101
102 <?php
103
104 /* Sample code for events node. Optional events you can send
back when a user logs in. */
105
106 ?>
107 <events>
108 <notifications>
109 <notification duration="5" titlebar="false">
110 <body bgcolor="#999999" image="URL"
link="#cc3500" background="http://public.userplane.com/assets/Picture 1.png"
text="#cc3500"></body>
111 </notification>
112 </notifications>
113 </events>
114
115
116
117 </login>
118 <?php
119 }
120 else
121 {
122 ?>
123 <error>
124 <id></id>
125 <message>Login Error - Retry</message>
126 </error>
127
128 <?php
129 }
130 }
131 else if( $strFunction == "verify" )
132 {
133 $strUserName = isset($_GET['username']) ?
$_GET['username'] : null;
134 $strPassword = isset($_GET['password']) ?
$_GET['password'] : null;
135
136 $strUserID = authenticate($strUserName,$strPassword);
//set to the user numeric userID once they have been
verified. This will need to be an integer to work with the
presence system.
137 if($strUserID != "") {
138 $bVerified = "true";
139 } else {
140 $bVerified = "false";
141 }
142
143 if ( $bVerified == "true")
144 {
145 ?><success/><?php
146 }
147 else
148 {
149 ?>
150 <error>
151 <id></id>
152 <message>Login Error - Retry</message>
153 </error>
154 <?php
155 }
156 }
157 ?>
158
Configuration
The basic configuration of DPXML.php includes:
- Setting the presence password (line 9). This should be sent to the password you received in the earlier e-mail message.
- Set the login, verify, and lost password URLs (lines 24-27). The login and verify URLs point back to DPXML.php, calling the respective functions. In this example, the lost password URL points back to the WordPress blog lost password page.
- Set up the Webmessenger integration (line 29). This should point to the URL of your wm.php file.
- Finally, I configured the login and welcome screens to display my logo (lines 41 and 47). You can also configure the foreground and background colors of the login screen on lines 48-49.
Integrated Authentication
The DPXML API is called when authenticating users. The login function (lines 76-130) is called when a user actually connects. The verify function (lines 131-156) is called to check that a username and password is correct. Clicking on the Verify button, shown in Figure 1, calls the verify function. Both of these functions need to integrate with any authentication mechanisms used by your social networking site. In my example, I am integrating with the authentication scheme provided by WordPress. The WordPress database contains a table called wp_users, which contains usernames and MD5-encrypted passwords. Lines 79-80 in the login function retrieve the username and password. This information is passed to the PHP implementation of the authenticate function, shown in Listing 2.
Listing 2. authenticate.php
1 <?php
2 include('../wp-config.php');
3
4 function authenticate($username,$password) {
5 $conn = mysql_connect(DB_HOST, DB_USER, DB_PASSWORD);
6 mysql_select_db(DB_NAME);
7
8 $query = "SELECT ID, user_pass FROM wp_users WHERE
user_login = '".$username."'";
9 $result = mysql_query($query);
10
11 $row = mysql_fetch_array($result, MYSQL_ASSOC);
12
13 mysql_close($conn);
14
15 if($row['user_pass'] == md5($password)) {
16 return $row['ID'];
17 } else {
18 return "";
19 }
20 }
21
22 ?>
The authenticate function simply connects to the WordPress database, queries the wp_users table, and compares the encrypted passwords for a match. If a match is found, the ID of the user is returned; otherwise, an empty string is returned. Note the inclusion of the wp-config.php file, which contains the DB_HOST, DB_USER, DB_PASSWORD, and DB_NAME definitions. The value returned by the authenticate function is assigned to $strUserID in the login function. If the login was successful the <success/> XML is returned; otherwise, an error message is returned in the <error> XML.
Deploying the Userplane Desktop Application
After you have configured and integrated authentication, you are ready to create the custom Userplane Desktop Adobe AIR application. Before you perform this step, make sure you have received a response from support@userplane.com from your earlier message about installing the DPXML API files. You must log in to the Userplane Integrated Administration page at http://apps.userplane.com/login.cfm using your username and presence password. On the Userplane Integrated Administration page, shown in Figure 3, click the Desktop Presence Admin link.
Figure 3. The Userplane Integrated Administration page
The Desktop Installer Generator page is then displayed, as shown in Figure 4. You can customize the installer name, display name, thumbnails, and application icon. Click the Generate Installer button to generate your custom Adobe AIR application.
Figure 4. The Desktop Installer Generator page
Provide your users with the link at the top of the page; this is where they can download your custom Userplane Desktop installation. If they have the Adobe AIR runtime client installed, this file will install your custom Userplane Desktop application.
Notifications and Menu Items
A key component of the DPXML API is the ability to provide notifications and custom menu items. Notifications can occur when there are updates to your site, when there are messages from other users, on login, or at other events. The notification XML is detailed in the Userplane Desktop documentation at http://wiki.userplane.com/docs/doku.php?id=desktop_presence.
You can also add custom menu items that are displayed when the user right-clicks the application icon while it is running. Lines 65-72 of the DPXML.php file show the XML required to support an About menu item that links to the About page on my WordPress blog. The new menu item is shown in Figure 5.
Figure 5. Adding an About menu item
TMZ.com - A Sample Userplane Desktop Deployment
TMZ.com (Thirty Mile Zone) is a celebrity gossip and news web site, the result of collaboration between AOL and Telepictures Productions, a division of Warner Bros. TMZ.com has implemented Userplane Desktop. Figure 6 shows the TMZ.com custom login dialog box. Figure 7 shows a custom notification dialog box; note the small advertising at the bottom.
Figure 6. TMZ.com custom login
Figure 7. TMZ.com notification
Conclusion
The Userplane Desktop application is an ideal mechanism for social networking sites to provide a tether to their users while they are not actively participating on their web site. In this article I've provided developers with an introduction to deploying Userplane Desktop. All of the heavy lifting in building a desktop application is provided by Userplane Desktop; developers can instead focus on what they know best: developing and supporting the application back end. With APIs for the most popular server-side languages (ASP, ColdFusion, and PHP), Userplane Desktop provides developers with the tools they need to integrate into their existing infrastructures.
Resources
If you're interested in deploying Userplane Desktop for your web site, the following resources will be helpful: