README

changeset 49
6d46d2518705
child 60
35a99353d907
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Thu Apr 08 15:48:32 2010 +0100
@@ -0,0 +1,98 @@
+Support chat
+============
+
+Requirements
+------------
+
+Server:
+- An XMPP server with support for:
+ - Multi-User Conferences (may be an external service, e.g. mu-conference, Palaver)
+ - BOSH (may be an external service, e.g. Punjab)
+ - SASL ANONYMOUS
+
+- A web server:
+ - To serve the scripts, stylesheets and images
+ - To redirect requests for a selected URL to the BOSH server
+
+Users:
+- A Javascript-enabled web browser
+
+Installation
+------------
+
+Upload the 'support-chat' directory to your site. In the page(s) in
+which you intend to enable the support box to be launched, add the
+following snippet of HTML to the <head> section of the page:
+
+       <script type="text/javascript" src="support-chat/js/jquery-1.4.2.min.js"></script>
+       <script type="text/javascript" src="support-chat/js/strophe.js"></script>
+       <script type="text/javascript" src="support-chat/js/xmpp_muc.js"></script>
+       <script type="text/javascript" src="support-chat/js/supportchat.js"></script>
+       <script type="text/javascript" src="support-chat/js/jquery-ui-1.8rc3.custom.min.js"></script>
+       <link rel="stylesheet" href="support-chat/ui/supportchat.css" />
+       <link rel="stylesheet" href="support-chat/ui/start/jquery-ui-1.8rc3.custom.css" />
+
+(amending the paths as necessary to point to the correct files).
+
+Configuration
+-------------
+
+On your XMPP server you need to create a new host for users to connect to. This host
+should be configured to allow SASL ANONYMOUS logins. You also need to create a host
+to hold the user-created support rooms using MUC. This will either be provided by 
+your server, or by configuring an external component.
+
+On your web server the only tricky part is setting up a proxy for the scripts on the
+site to access the BOSH server. Apache, lighttpd, nginx and other servers support this.
+There are many ways to achieve this, but one method in Apache2 would be to use its
+mod_rewrite and a configuration line similar to:
+
+       RewriteRule /bosh http://localhost:5280/http-bind/ [P]
+
+This assumes your BOSH server is on the same machine as the web server, and is serving
+BOSH at /http-bind (the default path in most servers). You should in the end be able
+to visit http://yourdomain/bosh and see the BOSH page of your server.
+
+Finally you need to configure and customise support-chat itself. Open up
+support-chat/supportchat.js in an editor, and review and modify the configuration
+options at the start of the file. Each one is described below:
+
+login_domain: This should be the XMPP hostname that is configured to allow anonymous
+              logins.
+
+bosh_url:     This should be /bosh, or the path you proxied from your web server to
+              the BOSH server.
+
+muc_server:   The XMPP hostname of the Multi-User Conference server where users shall
+              create their temporary rooms.
+
+team_rooms:   A list of pairs of assistant team names and team MUC addresses. The
+              example should give you enough guidance on how to structure the list.
+              You can define as many or as few teams as you want.
+
+send_invites: May be true or false. If false, online assistants will receive messages
+              alerting them to new queries. If true, they will receive a MUC invitation
+              to the query's room (may not work in all XMPP clients).
+
+offline_support: An XMPP address to which queries should be sent when no assistants on
+              the selected team are available. Should have offline message storage
+              in order to be sure never to lose a query.
+
+alternative_url: If the support application encounters an issue connecting to the XMPP
+              server (whether it be down, or the user's network policy or browser
+              prevents such) the user will be directed to the given URL to obtain
+              support.
+
+Usage
+-----
+Anywhere you want to provide a link to open the support interface, direct the link to
+#support-chat, for example:
+
+        <a href="#support-chat">Live Support</a>
+
+On clicking this link the user would be presented with a form to enter their query.
+
+License
+-------
+support-chat is licensed under the University of Illinois/NCSA Open Source License,
+see the LICENSE file that accompanies this project for more information.

mercurial