The desktop presence system has three components: AIR app, DPXML API, presence back-end.

AIR Application: The AIR app is the customizable application that your users will download from you or from Userplane and install. You will create this using our applicaiton builder system. Once you have built your app you can distribute it to your users however you like. In order for users to run the app they will need to have Adobe AIR 1.0 running on their machine. (to download Adobe AIR please visit http://get.adobe.com/AIR)

DPXML API: The desktop application will communicate with you via your DPXML API. This component is where the desktop apps will send their HTTP GET requests for events such as a user logging in or periodically so you can send back notifications and alerts.

Presence Back-end: The Userplane presence back-end is the component responsible for tracking which users are logged in and can accept IM’s. The presence system will work with your Webmessenger application to automatically direct IM’s to your desktop users.

1. Place the DPXML file API on your server. You can put this file anywhere you want as long as the desktop presence applications can get to it freely. Send the full URL to your DPXML API to support@userplane.com so we can add it to your account.
   
2. Build application installer. Login to the apps admin then use the Desktop Installer Builder to create your custom branded executable.
   
3. Configure the API file to handle the login and customer preferences requests.
   
4. Install the application, start testing and make custom notifications!
   
5. If you are using the free, ad-based version of Desktop, please follow the instructions below in order to place text ads in your desktop notifications.
6. If you choose a PAID package, please include your contact information, billing address, and credit card or Paypal information. If you do not wish to include this information in an email, please make sure you leave a valid phone number so our accounting department can contact you to set up your billing cycle. For a FREE package, only your contact information will be needed.
   
   

If you are running free Desktop, then you must place text ads in an iframe as shown in the example. Please visit our Ads page for more information.

All of the applications you distribute to your users will communicate with you via one main API. This API is very simple, the apps send HTTP GET requests and you respond with XML. In the sample docs there is a file named DPXML that is a template for how to handle these requests (find the file for your site language and upload it to your server). You can customize the way the API responds to create custom alerts, customize the menu items and to tell the app to download new sounds and icons.

customer preferences: when a user launches the desktop app it will send a request for the preferences to your XML interface. Check below for the required an optional responses. In the DPXML sample files there is also some example code to use as a template.

http://www.yourSite.com/pathTo/DPXML.php?
    encrypted_userID=hw0I04Rh7q2tCzeHdMAhAPmG3r1tmltm9cqS1F4AhBqXhm/Yf0rQp2Ftvu0Y4vnx
   &sessionID=VP9kHfak01OVMno7

login: this request will include the username and password that the user enters in the desktop application. You will need to authenticate them, then send back their encrypted user ID and session ID. On all future requests the desktop app will send the encrypted user ID and the session ID so you can send targeted alerts.

http://www.yourSite.com/pathTo/DPXML.php?
    function=login
   &username=userA
   &password=Pa55w0Rd

verify: this request happens when the user clicks the verify button on the preferences window. It is meant for you to use to verify that the username and password are correct before they save the info.

http://www.yourSite.com/pathTo/DPXML.php?
    function=verify
   &username=userA
   &password=Pa55w0Rd

Once you have it on your server send support@userplane.om the URL to this file. It will need to be in a publicly accessible location since it will be receiving requests from every user logging in through the desktop applicaiton.

This request is sent when a user initially launches the desktop presence application and then again on the interval set by <customer_preference_interval>. After the user is logged in the encrypted user ID and session ID will be sent in this request. All time intervals below are in seconds. The update tag enables you to specify the latest version of your desktop application, which will allow it to auto-update if the current version is less than the version in the version tag. The download url tag is used to specify the location of the latest version. When the Desktop app updates, it will simply prompt the user if a new version is available. This allows you to keep all clients up to date simply by making changes to your XML responses.

This is the call that you will use to generate alerts for your users after they are logged in.

Sample Request sent when the desktop app launches (before the user has logged in):
http://www.yourSite.com/pathTo/DPXML.php?

Sample Request from logged in user:
http://www.yourSite.com/pathTo/DPXML.php?encrypted_userID=hw0I04Rh7q2tCzeHdMAhAPmG3r1tmltm9cqS1F4AhBqXhm/Yf0rQp2Ftvu0Y4vnx&sessionID=VP9kHfak01OVMno7

<desktoppresence>
  <update>
    <version>2008_10_03_01</version>
    <download_url>http://www.website.com/dp.air</download_url>
  </update>
  <urls>
    <password>http://www.yourSite.com/lostpasswordpage.php</password>
    <login>http://www.yourSite.com/pathTo/DPXML.php?function=login&amp;</login>
    <verify>http://www.yourSite.com/pathTo/DPXML.php?function=verify&amp;</verify>
    <state>http://www.yourSite.com/pathTo/stateHandler.php</state>
    <im>http://www.yoursite.com/pathTo/wm.php</im>
  </urls>			
  <configuration>
    <customer_preference_interval>10</customer_preference_interval> 
    <idle_timeout>120</idle_timeout>
  </configuration>
  <resources>
    <icons>
      <icon type="default">http://www.yourSite.com/pathTo/default.png</icon>
      <icon type="disconnected">http://www.yourSite.com/pathTo/disconnected.png</icon>
    </icons>
  </resources>
  <debug>false</debug>
  <gui>
    <welcome_screen>
      <image>http://www.yourSite.com/pathTo/welcome.png</image>
      <text>[[enter text or HTML]]</text>
      <eula>[[enter URL to your EULA if applicable]]</eula>
    </welcome_screen>
    <preferences>
      <header>http://www.yourSite.com/pathTo/header.png</header>
      <foreground_color>363796</foreground_color>
      <background_color>e2e2e2</background_color>
    </preferences>
    <notifications>
      <titlebar>
        <title>YourSocialNetworking Website Desktop</title>
        <close_button>
          <normal>http://www.yourSite.com/pathTo/normal.png</normal>
          <hover>http://www.yourSite.com/pathTo/hover.png</hover>
          <pressed>http://www.yourSite.com/pathTo/pressed.png</pressed>
        </close_button>
      </titlebar>
      <window_border>363796</window_border>						
    </notifications>
  </gui>
</desktoppresence>

password - the page that users will be sent to if they click the forgotten password link.

login - the URL that the login request is sent to. By default this is sent to the same URL with the function=login in the query string to differentiate it.

verify - the URL that the verify request is sent to. By default this is sent to the same URL with the function=verify on the query string to differentiate it.

state - a URL that you will use to keep track of user status. You should pass the encrypted_userID initially in the URL so you can identify the user when these requests are sent. There are three requests that are sent to this URL:

• User becomes idle: http://www.yoursite.com/userplane/stateHandler.cfm?state=idle

• User becomes available: http://www.yoursite.com/userplane/stateHandler.cfm?state=available

• User logs out: http://www.yoursite.com/userplane/stateHandler.cfm?state=logout
  
  

im - a URL that points to your wm file. This is the URL that will be opened by the desktop app when a user receives an IM from a Web user. The wm file will be passed the encryptedUserID as well as the targetUserID in the query string.

Sent when a user logs in, the users name and password are sent in the clear. If the users is authenticated you set the sessionID and the encrypted user ID. You must pass back an encrypted userID.

Sample Login Request:
http://www.yourSite.com/pathTo/DPXML.php?function=login&username=userA&password=Pa55w0Rd

On successful login return the following XML document:

<login>
  <sessionid>VP9kHfak01OVMno7</sessionid>
  <encrypted_userid>hw0I04Rh7q2tCzeHdMAhAPmG3r1tmltm9cqS1F4AhBqXhm/Yf0rQp2Ftvu0Y4vnx</encrypted_userid>
</login>

<events>		
  <notifications duration="10">
    <notification>
      <body background="#ffffff" image="URL"></body>
    </notification>
  </notifications>	
</events>

For example, if you want to send back an alert to the user right when they login your response might look like:

<login>
  <sessionid>VP9kHfak01OVMno7</sessionid>
  <encrypted_userid>hw0I04Rh7q2tCzeHdMAhAPmG3r1tmltm9cqS1F4AhBqXhm/Yf0rQp2Ftvu0Y4vnx</encrypted_userid>
<events>		
  <notifications duration="10">
    <notification>
      <body image="someBackgroundImage.jpg">Hello!  Welcome back.</body>
    </notification>
  </notifications>	
</events>
</login>

On unsuccessful login you will return the following XML document:

<error>
  <id>123456</id>
  <message>Your account is no longer valid, please visit www.yourSite.com to reactivate.</message>
<error>

This will contains some error code you want to assign (your internal error code if you have one), and a human readable message for your user. This may be related to a FAQ entry you have on your site for troubleshooting or might just let them know their account is not valid for example.

Sent when a user clicks the verify button on the preferences screen of the desktop application.

Sample Verify Request:
http://www.yourSite.com/pathTo/DPXML.php?function=verify&username=userA&password=Pa55w0Rd

On successful login return the following XML document:

<success/>

On unsuccessful login you will return the following XML document:

<error>
  <id>123456</id>
  <message>Your account could not be verified.</message>
<error>

This will contains some error code you want to assign (your internal error code if you have one), and a human readable message for your user. This may be related to a FAQ entry you have on your site for troubleshooting or might just let them know their username and password did not match.

The right-click menu has default actions for connect/disconnect, status and preferences. You also have the ability with the API to add your own menu items. Some examples of custom menu items could be the users inbox or a list of their friends that are online.

The taskbar node contains a <menu> node, and the <menu> node contains one or more <item> nodes.

The order in which the items appear in the XML determines the order in which the menu items appear in the menu.

The menu is split into 3 sections:

[— before items —]
CONNECT ITEM
DISCONNECT ITEM
STATUS ITEM
PREFERENCES ITEM
[— after items —]


before items: if an item has before=”true” it will come before the default menu items.

Sample:

<taskbar>
  <menu>
    <item before="true" type="browser">
      <title>I go before the default items</title>
    </item>
  </menu>
</taskbar>

after items: if an item has before=”false” it will come after the default items.

Sample:

<taskbar>
  <menu>
    <item before="false" type="browser">
      <title>I go after the core</title>
    </item>
  </menu>
</taskbar>

type attribute: items have a “type” attribute which specifies what action is performed when the user selects the item. The following types are defined.

• •browser - Invokes a web browser. The url to go to is specified in a url child node.
• •options - Opens the options window.

Sample:

<taskbar>
  <menu>
    <item before="true" type="browser">
      <title>About</title>
      <url>http://www.userplane.com/about</url>
    </item>
  </menu>
</taskbar>

The notifications support full HTML / JS / CSS within the <body>. You can think of the notification windows as tiny web browsers, point them to another page via an iframe or put the HTML directly in the alert XML, just keep in mind that the width is fixed at 250 px. (The notification body is rendered via WebKit, for more information on this open source browser you can check the Webkit project site).

Sample:

<events>		
  <notifications>
    <notification duration="10" titlebar="true">
      <body>Some Body</body>
    </notification>
  </notifications>
</events>

duration: The number of seconds the notification will stay open. If omitted, the notification will last a default of 10 seconds. If specified and greater than 0 the notification will last for that many seconds. If 0 the notification has no duration and must be manually dismissed by the user by either clicking the close button or by clicking on a url in the notification body.

titlebar: Determines if the notification has a titlebar with a close button. if this is set to false the user will have no way to close the notification, so make sure that you are setting some duration if you are sending notifications without a titlebar..

If you want your users to download a new icon or a new sound for a notificaiton you will need to specify those assets via the resources section in the customer preferences XML response. This section will need to be at the same level as the <urls> and <configuration>.

• •sounds: These will contain the URL‘s to the MP3 files you want to use in notifications. The app will download the file and associate it with the type you specify. Then when you want to use the sound in a notification you will just need to specify the type and it will know to use the file that was already downloaded.
  
  
  • Audio Format Supported: MP3
    
    
• •icons: These will contain the URL‘s to the images you want to use for notifications. The app will download the file and associate it with the type you specify. Then when you want to use the icon for a notification you will just need to specify the type and it will know to use the image that was already downloaded. You will need to specify an icon to use for the default (user not yet logged in) and connected (once user is logged in) states, but you are free to add any additional types you like.
  
  
  • Image Formats Supported: PNG and JPG
    
    

Sample:

<resources> 
  <sounds>
    <sound type="mail">http://www.yourSite.com/pathTo/newMail.mp3</sound>
  </sounds>
  <icons> 
    <icon type="mail">http://www.yourSite.com/pathTo/mailIcon.png</icon>
  </icons>
</resources>

(shows how to specify a new icon and sound to be used for mail notifications)

In order to use a resource you have specified in a notification it’s as simple as referencing the type in your notification XML.

Sample:

<notification duration="10" titlebar="true">
  <icon>resources:mail</icon>
  <sound>resources:mail</sound>
  <body>
    SOME BODY...
  </body>
</notification>

Below are a few examples of some notification you may send out to users. These need to go within the <events> section in either the customer preferences XML response or within the <events> section of the login XML response.

<event>
  <notifications>
    <notification duration="10" titlebar="true">
      <body bgcolor="#999999" image="URL" link="#cc3500" background="http://public.userplane.com/assets/alertBackground.png">
        <a href="http://www.yourSite.com/viewProfile.php?userID=1236854">Edit Profile</a>
      </body>
    </notification>
  </notifications>
</event>

<event>
  <notifications>
    <notification duration="10" titlebar="true">
      <body bgcolor="#cccccc" image="URL" link="#000333">
        <b>Welcome - There are 12345 other users online!</b>  
        Click <a href="http://www.yourSite.com/pathTo/onlineUsers.php">here</a> to see the list of online users.    
      </body>
    </notification>
  </notifications>
</event>

<event>
  <notifications>
    <notification duration="10" titlebar="true">
      <sound>resources:mail</sound>
      <icon>resources:mail</icon>
      <body bgcolor="#cccccc" image="URL" link="#000333">
        <b>New Message Received!</b></br>
        <a href="http://www.yourSite.com/pathTo/mail.php">Inbox</a>  
      </body>
    </notification>
  </notifications>
</event>

In order to use the desktop app you will need to send the URL to your DPXML API to support@userplane.com. Once we have this URL your desktop app will be able to connect to your API. When your users download the desktop application and install it it will send a request to us to find the path to your API and then will send all of the subsequent requests to you.

In order for the desktop app to work with the Userplane Webmessenger you will also need to make sure that your desktop presence domainID matches the domainID you are using for the Webmessenger. This is necessary so that when users from your site try to IM desktop users the presence back-end will be able to forward these IM’s to the desktop app. If you are not sure which domain you are using or have multiple domains setup contact support@userplane.com and we can help you sort it out.