Userplane Webchat 2 is a distributed system with multiple components, some hosted and controlled by Userplane, some hosted and controlled by you.

The Webchat 2 suite features the Webchat application as well as the Minichat application. Here is a brief overview of the system:

Pieces hosted by Userplane:

• Flash SWF: There are multiple SWF files in Webchat. Each has a purpose. Most of them are the user interface presented to the end user and some are hidden. These files do all the communication with the Flash Communication Server.
  
  
• Flash Communication Server: This piece is a combination of Macromedia’s technology and custom server-side scripting written by Userplane. A communication message comes from the Flash SWF, the Flash Communication Server figures out where that message needs to go, then sends it the destination SWF.
  
  
• XML: When the Flash Communication Server needs to retrieve information from or send information to your app server, it does this through XML. XML is a standard way to share data between 2 locations and/or languages. It is accessed just like HTML and looks remarkably like HTML in all aspects. Because of that, you will be able to create this interface just like you would create a dynamic HTML page, using whatever backend technology you like. Userplane will provide you the XML schema to use for interacting with our backend.

Pieces hosted by you:

• HTML: The HTML is hosted by you and will need to be implemented using some sort of programming language like ASP.NET, ColdFusion, PHP, or Perl. Userplane will provide examples of this HTML for you to get started with and in the case of some programming languages, will also provide some include files. When the HTML wants to display a component of the Webchat, it loads the Flash SWF from a Userplane server.
  
  
• XML Interface: When the Flash Communication Server needs to retrieve information from or send information to your website, it does this through an XML interface. Userplane will provide you with a simple XML schema to use for interacting with our backend. You simply fill in the blanks using your favorite web based programming language. (HTTP based requests that return XML. XML provides a standard way for 2 systems to share data in a format that pretty much everyone understands. In the case of this Userlist we use XML for Flash Communication Server to send and receive vital data and events to and from your website)
  
  
• Database: This is your database. Your XML interface will communicate with your database to insert, update and select the appropriate data.

Please follow the steps outlined here to successfully integrate Webchat with your website:

1. Upload Sample Files

• Place the CSXML [.asp, .aspx, .php or .cfm] file on your server in a public location. In this same directory, you should also upload the other files from the Userplane folder. This would include the CMD, FLASHOBJECT, EXPRESSINSTALL, MC, and WC files. If you are using another web language besides the four types listed, you may modify the sample files to work with your web server. Our flashcom servers only care about receiving properly formed XML from you, so it does not matter which web language you use.

2. Upload the crossdomain.xml File

• Place the CROSSDOMAIN.XML file in the web root of your server. This file will allow images from your site to load into the flash application from our flashcom network. This file does not need to be modified.

3. Modify WC Sample:

• Add the code necessary for this file to access your data source. At the very minimum, you will need to edit the WC file.
  
  
• The WC file is the page which actually calls the flash SWF from our flashcom network, which is the Webchat application. You can load this page any way you wish, but the most common method is to use a javascript popup window command as seen in the INDEX sample file. You could embed WC in a web page if you wish, too.
  
  
• Inside the WC file are variables which will identify you as a customer and the session GUID of the logged in user attempting to use Webchat. In the WC file, you must change the values of the following three variables (found at the top of the file):
  
  
  • •strFlashcomServer (by default it is set as flashcom.yourcompany.userplane.com)
  • •strDomainID (by default it is set as yourdomain.com)
  • •strSessionGUID (by default it is set to the placeholder “aaaaa”)
    
    
• You need to substitute your actual domain name with the “yourcompany” and “yourdomain” place holder as shown in the WC file.
  
  
• For example, if your website is named www.mywebsite.com, the value for strFlashcomServer would be “flashcom.mywebsite.userplane.com”. The value of strDomainID would be “mywebsite.com”. Finally, strSessionGUID must refer to an actual session GUID that is created on your end to track user sessions.
  
  
• Understand that the application will not be functional until you send us the information we request in step 7, and we set up our servers to recognize your site. You would most likely want to place or link your database queries in the WC file to retrieve whatever information you wanted to present to our app for display purposes.
  
  
• You will also notice that there are three optional declarations, strKey, strInitialRoom, and strInstanceID, which you can assign values from your database or hard code into the page.
  
  
  • strKey can be used for advanced authentication or simply to pass additional data.
  • strInitialRoom is used if you want to set the initial room that the user enters in the WC file instead of the CSXML api file.
  • strInstanceID is used to set up a completely separate running instance of webchat. Please see the section discussing the Webchat Application Hierarchy below. You may also go to our WC page for a more in-depth discussion on how to modify the flash and javascript parameters for this file.

4. Modify the CMD Sample:

• You may also edit the CMD file. This file is used when your html needs to let the Flash Communication Server (and subsequently other components) know of an event. If you look at the comments in the code you will see some variables to set. Some of these relate to variables sent in the start up email and would be indentical to the ones set in the WC file, such as strFlashcomServer, strDomainID, strSessionGUID, and the optional strKey. Additionally, you will notice a strEvent variable. This is where you specify which event occurred. The two possible events are discussed here:
  
  
  • User.ForceReload:
  • Use this whenever user information changes that required the getUser XML function to be called again. This would include buddy list additions or deletions, display name changes, buddy viewable only preferences changes, etc. You only need to specify the user for this function to be called properly, the strParameter value is irrelevant to the command.
    
    
  • Preferences.Refresh:
  • Use this to have the server request a new getDomainPreferences from your site. Only an admin user (specified in getUser) is allowed to run this function. Note that the CSXML file can simply be configured to perform an automated refresh of this call based on the time interval you set using the domainPrefReloadInterval tag.
    
    
• You would place the cmd component in the HTML of a page when any values in the getUser XML function call change for that user. It will force the FCS server to reload that data.

5. Modify the CSXML Sample

• You may also edit the CSXML file, and you can test the basic functions using our XML tester, most importantly the getDomainPreferences and getUser functions. You will need to dynamically create the getUser XML for each user based on the information sent with the HTTP request from our XML server, this request looks like this:
  
  

http://www.domain.com/userplane/CSXML.php?function=getUser&domainID=yourdomain.com&sessionGUID=userA

• This step is simply for you to see what the returned XML looks like when you make changes to the CSXML file. It is not a mandatory step, but it is useful. To get the functionality and appearance you desire, it is essential that you modify the CSXML API file.

6. Configure Minichat Settings

• If you wish to also use our Minichat application, you would want to modify the MC file, which is the file which calls the Minichat SWF. Additionally, there is a <minichat> tagged section of the CSXML file where you can also make changes to Minichat functionality. Please see the Minichat section at the bottom of this page for more information. The manadatory variables of the MC file are the same as for the WC file:
  
  
  • •strFlashcomServer (by default it is set as flashcom.yourcompany.userplane.com)
  • •strDomainID (by default it is set as yourdomain.com)
  • •strSessionGUID (by default it is set to the placeholder “aaaaa”)
    
    
• Take note that the strKey, strInstanceID, and strInitialRoom variables are also optional. Also take note that the strUpdateRedirectURL variable should not be altered. It is used if the end user has an older version of Adobe Flash. The EXPRESSINSTALL file mentioned earlier is used to update that person’s Flash player, and will then redirect back to the MC file automatically. You may visit the Minichat page for an in-depth discussion of how to modify this file.

7. Email Support for Account Creation

• Once you have built and tested your XML interface, you will email the following information to support@userplane.com:
  
  
  1. The account name, which would most likely be “yourdomain.com”, but can be whatever company name or account name you wish.
  2. (optional) The name of the server that hosts your images (watermark and user photos which you may load into the Webchat application). This is only necessary if you don’t want to use crossdomain.xml mentioned in step 2.
  3. The public URL to the CSXML file described in this document. This is the most important information we will need.
  4. The Initial package sizes for each app you are licensing. You would choose either the free integrated ad-based Webchat, or a paid package.
  5. 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.
     
     
• Userplane will then set up your Flash Communication Server and our DNS system to work with your site. This step can take up to 1-2 business days.

8. Verify Settings in your WC File

• Once your server has been set up, you will receive an email with your account information. Check the WC file to ensure the FlashCom server info we sent you matches the three main variables mentioned in step two above.

9. Implement Ad Code

If you are a free integrated customer, you will need to set up ads in a frame beneath the application. Please refer to the “Setup Ads” section below for instructions on how to set up your ads. Or you may go directly to our Ads page to see how to implement ads there.

Once your account has been set up, you will receive information on how to log into the Apps Inspector. The Apps Inspector is what integrated customers use to see what happens “behind the scenes” and to troubleshoot technical issues.

• flashcom.accountName.userplane.com
  • -domainID
    • -instanceID
  • -domainID
    • -instanceID
    • -instanceID
  • -domainID

Every Userplane account has it’s own flashcom server that we configure. The server name will include your account name in the form “flashcom.accountName.userplane.com”. The same flashcom server will be used for every site or environment that you want to use with the Webchat.

Since you will probably want to have more than one site or environment running on your account we allow you to setup separate domainID’s that allow you to use multiple sites on the same server all using different settings and connecting to different user DB’s etc. In order to get a domainID setup on your account we need to know the full path to the CSXML API that you want to use with the domainID.

It is also possible to create a separate instance of a domainID by using the instanceID parameter when you load a Webchat. This will create a separate application on the server, so users in one instance cannot see or interact with each other even though they are both using the same domainID. Both of these instances will share the same API since they are both using the same domainID.

The domainID and the instanceID info is sent in all of the API requests to your CSXML file, so it’s possible for you to customize the settings for a Webchat based on the instanceID that is being used as well. Instances are useful if you wish to keep user loads low. Webchat performs best when there are 60 or less users per room, and 200 or less users per instance. If an instance ever reaches 285 users, the application is designed to split, or “spawn”, into separate running applications. This is done to enhance performance, but it can be avoided simply by judicious use of instanceIDs to keep per-instance usage more manageable.

In the WC action list (described below) there is a js command called InstantCommunicator.StartConversation. This function would only work through Webchat if you had also installed the Webmessenger (1:1 messaging) application on your site. For a Webmessenger IM to open successfully through Webchat the following values need to be the same across both apps: domainID, sessionGUID, and instanceID. See the WC page for more details.

If you are going to be using the free ad supported version or revenue share you will need to set up our Ad Frames

Once your flashcom server has been configured you will receive the following info back from Userplane:

domainID: This specifies to our application server the URL to your CSXML file. This will be assigned by Userplane and will correspond to the domain that you are running Webchat on. You can have multiple domainID’s that point to individual CSXML files thus allowing for many totally separate applications of the Webchat if you wish. This makes it easy to deploy the application across many different properties on the same account.

FlashCom server name: This is the flashcom server you are connecting to. You will have one server per account and can have many domainID’s all running on the same flashcom server. This is declared in the WC file as described in the Steps to Integration section above.

Apps Inspector Login: 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. You may also read about using the Apps Inspector.

Apps Admin Login: Used to check usage history, test XML calls, and get updates on new features as well as download any documentation that you need.

You can modify the WC, CMD, and CSXML files to alter the functionality of your integrated Webchat application. The main configuration file is CSXML, but there are several aspects of functionality which can be modified by changing the WC and CMD files. The Minichat component is modified by altering the tags in the MC file, but there is also a small <minichat> tagged section of the CSXML file which contains Minichat variables as well.

By modifying the CSXML API file, you can dramatically alter the appearance and functionality of Userplane Webchat. This is the most important file for configuring your Webchat to look and behave as you wish.

Minichat is an optional component of the Webchat 2 suite. It is a more compact version of the regular Webchat application and allows users to observe or participate in conversations taking place in one of the Webchat rooms. The two files required for Minichat functionality are the MC and the CSXML files. Most of the functionality of the Minichat is determined by modifying javascript values in the MC file, but there is a small section marked <minichat> in the CSXML file that also affects the Minichat. Please visit the Minichat page for more information on how to integrate this application.