Nearly There Sidekick Manual

Here's our absolute minimum Quick Start Instructions which will bring up Sidekick on your Red Hat Linux server. Later on, be sure to peruse the other sections of this manual for advanced settings and features.

Now, you can go to Sidekick's home page by browsing to http://www.yourDomain.com/sidekick. Log on as “admin” with password “admin” and enter your valid license key from Nearly There. Log on as “albert” with password “albert” and go to the performer's lounge and host a show. Then, to view the show, just click on “Members Area.” (We recommend running the performer and client on separate machines. Nevertheless, with impaired performance, you can run both on the same machine.)

We have very detailed, step-by-step instructions which are readily available. Just ask us! These instructions start with a Red Hat Linux machine and walk through all the steps necessary to set up a fully functional system. Included in the set up are the installation of the following major components:

Sidekick runs on a server with the following capabilities:

Sidekick's performer program runs on a computer with the following capabilities:

Sidekick's applet client that runs on a computer with the following capabilities:

When installing Sidekick, you will only install Sidekick's server-side components. Components for the performer program and client applets are installed automatically as part of this process, so no specific attention needs to be paid to them.

Java 1.5.0 is available from Sun Microsystems. Two variations are available, a JRE (Java run-time environment) an an SDK (Software development kit). Download and install the SDK. Even though Sidekick does not require any features from the SDK, many servlet engines require the SDK for compiling JSP pages. To download, visit http://java.sun.com/j2se/1.5.0/download.html.

Sun Microsystems has published a specification for version 2.3 of their Servlet Engine. Sidekick requires an implementation that is compliant with version 2.3. We have tested our software with several implementations and even though we recommend Apache Jakarta's Tomcat, any of the following are sure to work:

Sidekick is distributed as two tar files, under the names sidekick-kit-2.4.0.tar.gz and application-sidekick-basis-2.4.0.tar.gz. The first tar contains the Sidekick binary and the second contains file that represent our sample application, the same as what is demonstrated on the http://www.nearlythere.net site. Our sample application is a good point to start your customization.

Also, in sidekick-kit-2.4.0.tar.gz, are a few other files of interest. Review the readme.txt file for the most current information. In the docs directory, SidekickManual.html -- and SidekickManual.pdf -- provide the documentation that you are now reading. Of course, sidekick-2.4.0.war represents the Sidekick system and is run within your servlet engine.

sidekick-2.4.0.war should be installed in your servlet engine. The details of this are specific to your servlet engine, but basically involve updating the servlet engine's configuration file to add a new web context, something like /sidekick. In addition, you will specify where the corresponding war file is located.

For your convenience, we have described in the next section how to install sidekick-2.4.0.war into Tomcat 5.5.17.

Our messaging server is responsible for maintaining connections with the performer and clients, as well as transferring messages, including status, chat, video and audio messages.

It is integrated into our web server software and is started automatically when Sidekick is started. One way to verify that the chat server is running is to log into Sidekick's admin area and click on Monitor. You will see a section like this:

	Chat Server
	* Up-and-running: Ok
	* Port: 2224

Another way is to look at the screen output when starting Sidekick or by looking in the log file logs/site.log. You should see a line similar to:

	Chat Server listening to port 2224

When installing Sidekick or maintaining it, you might need to periodically log onto your Linux server. When you log in, you will be presenting with a secure Linux shell. Within the shell, you can enter any commands. For example, you can enter commands to start and stop Sidekick.

The following steps allow you to log onto your server from a Windows machine:

Sidekick is started and stopped from the Linux shell. Technically, you will be starting and stopping Tomcat, the servlet engine which Sidekick runs within. Depending upon how Sidekick and Tomcat were installed, there may be more than one way to start and stop Sidekick.

To start Sidekick:

To stop Sidekick:

When you are restarting Sidekick, you will first stop it, wait a little bit, and then start it. You can determine that Sidekick has completely shut down by entering

  ps alx |grep java

and by observing only the grep java line in the output.

Note: This section assumes that you have installed Sidekick using our detailed Linux setup instructions (available upon request). These instructions add a user account "sidekick" and Sidekick is always run as this non-privileged user. Do NOT start Sidekick from root!

Most Sidekick properties can be changed in Sidekick's admin area. These properties are stored in sidekick.properties. Some infrequently changed options of Sidekick are contained within site.properties. Both sidekick.properties and site.properties are located in your application directory. This application directory is where all your customized files live. This site.properties file contains some properties that configure Sidekick including:

To configure Sidekick, we suggest you review the admin area and the site.properties file. For site.properties, you can read through it in order to understand each property and be able to enter the appropriate information or choice.

When your site generates the member's area page that has a Sidekick link on it, you will insert a link such as:

<a href="http://www.yourDomain.com/sidekick/whosLivePublic.m">
	Click for video!
</a>
<a href="http://www.yourDomain.com/sidekick/whosLivePrivate.m">
	Click for video!
</a>

When the either link is clicked on, our “who's live” page will be displayed. The first link is meant for prospects and the second link for members. Refer to the section called “Customizing launch pages” for information on customizing the displayed pages. Also, refer to Chapter 5, Restricting Access for how to modify the second link so that only members are allowed to join a show.

Sidekick uses two or three http ports for communication.

First, all standard web page traffic uses port 80. This is an Internet standard. If you have reason to change this port, you can change it in your servlet engine's configuration file. For example, with Tomcat, in server.xml search for port="80" and change it as desired.

Second, if you have secure sockets enabled, then port 443 is used. This is also an Internet standard.

And third, streaming video and chat messages are routed over port 2224. You can change this to another port by modifying the entry in site.properties.

If users are encountering access problems, it may be because our chat port has been blocked by a firewall. Selecting a different port might make sense.

When you enter our web pages from your site, you'll see our default web pages. These pages don't have your look and feel. This section describes how you can replace our pages with your own look and feel.

The following are the main pages that you can customize:

The following are the feedback pages that you can customize:

A common example follows. In the members area, you can link to the whos live page. This page will be whosLivePrivate.vm and will be contained within privateWrapper.vm. A member can join a show from this page. launchPrivate.vm will be displayed within privateWrapper.vm.

If you support allowing non-members to join a show (with no video, reduced video or still images), display whosLivePublic.vm which will be contained within publicWrapper.vm. When a non-member joins a show, launchPublic.vm will be displayed within publicWrapper.vm.

You will find copies of each of these pages in our templates directory. Sidekick expects the templates directory to be in its applicationDirectory, which is specified when Sidekick starts up (See Chapter 2, Getting Around Sidekick).

For advanced usage, where you need to display the whosLive and/or launch pages within a different context, the following four variations are available: whosLivePublic2.vm, launchPublic2.vm, whosLivePrivate2.vm and launchPrivate2.vm. These templates are backed by publicWrapper2.vm and privateWrapper2.vm.

When you want to place an html link to one of these pages, don't specify the page directly. In Sidekick, you specify commands, which the invoke the correct pages.

When you enter these links in and templates, you must use our exact syntax. For example, to link to whosLivePublic.m, you would something like:

<a href="$model.linkAnchor('whosLivePublic.m')">
	Click here
</a>

A number of the commands above are used only in special circumstances. Commands that end with 2, such as whosLivePublic2.m, provide a second page for a varied look-and-feel. Commands with page allow you to display an arbitrary page within the Sidekick system. Commands with forward let you pass the following arguments (performerId, show, service) from the url so that they can be used on the page itself.

If you have images that you wish to place on one of the vm pages, there are two ways to do this with Sidekick. The first way links in your images from outside the /sidekick context. With the second way, Sidekick manages the images themselves. You will probably find the first way easier and it will suffice for most purposes.

With the first way, you would place your images in a public directory on your web server, such as /images. To display a image on a vm page, you would then create a tag such as:

<img src="/images/banner.gif" width="546" height="34">

Using the second way, do the following:

Sidekick considers the presentation that a client observes and interacts with a service. In other words, a service comprises the levels of video, chat and audio that the client observes and interacts with. For example, prospects might be able to use text chat, but see only a reduced size video with a slow frame rate and no audio.

Sidekick provides three primary kinds of services:

Basically, you can think of public and preview as being targeted primarily for prospects and private for members.

A show will always have a private service associated with it. In addition, it can optionally have a public service.

Each show has a private service, representing the presentation presented to clients.

Public services are displayed to clients in shows which have a private service with an associated public service.

There are two variations of public services. The first is presented to prospects when there are no users in its private area. The second, called degraded, is presented to prospects when there is a user in its private area, generally a degraded presentation.

For prospects, you can display an applet with only a video stream -- no audio or text chat. Sidekick also has a “recent frame” feature, where the page will display a recent frame from the show. You can think of preview in a similar way, except that the frame is being automatically updated regularly.

With Sidekick you can have one or more areas where paying clients enter. Each of these area is uniquely configured, perhaps with different pricing and access privileges. For example, commonly a site might have one area for exclusive one-on-one sessions and another allowing for many paying sessions at the same time, with different pricings.

There are many properties that allow you to customize each service. In the Sidekick admin area, you will be able to add and change services. For example, these properties let you specify whether a public area will be allowed, the access restrictions that will be enforced, as well as the sense of exclusivity that you wish to foster.

The Still images section lets you specify one or more images to rotate through on a preset schedule, say changing once every five minutes. You can have images before a show starts, when it is live, during intermission and after a show ends. Most commonly, this applies to intermission and will display images that convey “be right back” to the client. If more than one image is specified, then the images will rotate based on the specified rotation, such as every 30 seconds. These images, which must be 320x240, are retrieved from the external directory. You can also specify images unique for each performer by putting them in the external/{loginName} directory where {loginName} is the login name of the performer. Finally, these two options can be combined, allowing you to have the rotating images appear behind a smaller video stream.

You can disable audio entirely for this service. When disabled, the audio checkbox will not appear in the performer program and clients will not see the audio applet.

To further customize the videochat applet, Sidekick provides these options:

Finally, you can display the applet in landscape or portrait mode, that is with the video to the left of the chat area or above it. This selection is made by editing the launch page specifying a different width and height.

The streaming option enables a more powerful video streaming system which increases the frame rate to up to 24 frames per second. This faster frame rate provides a more realistic experience for your clients. Our real-time implementation allows the client to view the video stream with a delay of just a few seconds, allowing the performer and client to carry on interactively.

Sidekick will automatically adjust the size of the stream according to the characteristics of the connection providing the client with the best possible viewing experience that the connection delivers. For example, between the server and the client, if the client is on a slower connection, permanently or temporarily, Sidekick will reduce the data flow. This provides the client with a continual experience at a slower frame rate. When the connection improves, Sidekick will recognize this and improve the frame rate. Likewise, Sidekick will adjust to the changing characteristics of the connection between the performer and the server.

To enable this feature, in the Sidekick admin area, select h263 for the codec and reduce the frame rate (milliseconds per frame) to 42.

We recommend 42 because Sidekick will automatically govern the data flow over each connection. It you specifically want your video stream to be at a slower rate, you can adjust this parameter. The codec parameter is set to jpeg for the compression that Sidekick uses by default. For the streaming option, the codec parameter should be set to h263.

Since you can specify whether to use the streaming option for each service, you can offer this option to only certain clients.

For performers, the minimum requirement for their machine is higher. Sidekick requires at least a 1.5G Pentium IV CPU which gives it the power to apply a sophisticated encoding algorithm to the captured video data. Our encoder algorithm is software-based so no additional hardware (such as a special capture card) is required.

For the server, additional processing power is used but the requirements depend on how many streams you will be handling simultaneously. For a busier site, a faster CPU or a dual-CPU configuration would improve performance.

Sidekick supports two video sizes:

which represents the width and height of the video in pixels. This setting can be changed under Setup/General.

By default, Sidekick uses 320 x 240, but this can be changed if you like. Changing the video size allows you to present the most appropriate size to your clients, giving them the best experience possible, balancing the size against the additional bandwidth that a larger size will require.

If you change the video size, you will also need to update these settings:

With Sidekick, your clients can control the cam! Using pan, tilt and zoom buttons, they are able to adjust the cam exactly as they like. This feature is done in software by capturing a larger size video from the cam and then streaming a portion of this video to clients. Since the video is zooming in from a larger captured size, loss of clarity is greatly reduced.

For example, the performer can set her cam to capture at 640x480. For this example, let's say that Sidekick is configured to stream at 320x240. Initially, the client will see the center portion of the captured video. As he pans around or zooms in and out, the desired portion of the captured 640x480 video will be displayed. Sidekick will automatically resize the video as necessary.

To enable, this feature, in the Sidekick admin area, for the desired service, check the checkbox "Enable PTZ Support." With this enabled, two things will change:

The performer's video will display the stream that is being sent to the client so she will know exactly what the client is doing.

Sidekick's text chat provides two features to further engage performers and clients. The first allows a client to select a color that his messages will be displayed with. The second is the use of emotives, or smilies.

When Sidekick recognizes that a user has typed an emotive, it will display this as an image to better get the user's point across. The emotives that Sidekick recognizes are:

Sidekick provides settings which allow you to tailor its operation to the characteristics of your system which will give your members the highest quality video quality and frame rate possible.

In general, you'll find that the Sidekick is self-adjusting. Sidekick attempts to monitor the stream and dynamically adjust to varying conditions such as a net slowdown or various connection speeds on different computers. Nevertheless, the best hints you can provide via these settings will translate to the best overall video presentation.

The frame rate parameter allows you to specify the desired frame rate for all the shows of a particular service. Sidekick will attempt to stream frames from each performer at this rate. If a performer's available bandwidth is too low, the frame rate might be lowered for this performer. If your performers will be operating on higher-speed connections, a setting of 200 (representing 5 frames per second) is attainable with standard Sidekick. If your performers will be primarily on low-speed connections, a setting of 1000 (representing 1 frame per second) may be all that is attainable.

If you have the Streaming Option, you can specify a frame rate up to 24 frames per second (42 milliseconds per frame) rather than up to 5 or so frames per second.

JPEG PUSH

The following section only applies to Sidekick's standard codec, jpeg which is a jpeg push technology.

Another setting provides a hint as to how large each frame should be. The size of each frame determines the quality of the image. Setting this parameter around 4000 to 7000 should provide reasonable video quality. Don't be too generous with this number unless your performers and clients are both on high-speed connections.

#
#   Specify how large a frame to allow a performer client
#   to generate.
#
#   This should be in line with expected client data rate.  
#   For example, at 1 frames/second on a 56k line, a client
#   might be able to receive one 5,000 frame per second.  
#   Even if the service is set to deliver 2 frames/second,
#   the client will only receive one frame/second.
#
#   Alternately, if set to 7,500, then on a 56k line, a client
#   might only receive a frame every 1 1/2 seconds.
#
#   If you are supporting many clients on 56k modems, a value
#   like 4,000 is reasonable.  If most of your clients are on
#   high-speed connections, a value like 8,000 is reasonable.
#
business.performer.frameSizeCeiling = 7000

A particular frame will take a certain amount of bandwidth -- you can think of a frame as a jpeg image and could range from 2500 bytes to 40000 depending on its visual quality. On the other hand, a performer's computer can only stream so many frames per second depending on its connection speed, so we may have to give up some visual quality for a quick frame rate.

Keep in mind that the bandwidth used depends on the quality of the webcam that the performer is using. Lower-quality webcams will result in more optical distortion resulting in larger frames and thus more bandwidth.

As a specific example, let's say a performer is on a high-speed connection (say DSL) and a member is on a dial-up connection, say at 56k. This member can receive perhaps 5,000 bytes per second, so setting frameSizeCeiling to 4,500 might be the best we can do. With this setting, he will receive around 1 or so frames per second. You should set millisecondsPerFrame to 1000 so that she streams one frame per second. If other members are on faster connections, the setting might be decreased to 500, providing two frames per second. This would allow each member to have an optimal experience.

Let's say in the above example, all members were on high-speed connections. Then, we might increase frameSizeCeiling to 6000 or more and a frame rate of 2 frames per second.

This discussion describes some general characteristics, but note that the settings are all interrelated: First, if the performer is capturing at too high a frame rate for a member, then the member will only be able to receive and render some of them. This governing is handled automatically by Sidekick -- having the member lose a frame periodically is considered acceptable. Second, if frameSizeCeiling is too high, meaning that a frame will take more bandwidth, this will result in frames taking longer to be received by a member, thus slowing his effective frame rate. So, we suggest you don't set the bandwidth without considering your member's connection speeds.

Sidekick allows you to have several cams which are tied together. All text messages are sent to all performers and clients in all of the shows. Audio will originate from only one performer and any clients in any show will hear it.

Normally, Sidekick has a notion of one cam per show. This feature surfaces what can be considered a supershow, perhaps thought of as a single show with multiple cams.

This feature combines all shows of a particular service. The available services can be listed in Sidekick's admin area. You can edit a service, and enable this feature, essentially combining any shows which are launched with the this service. The Audio login name field specifies from which performer the audio will originate.

The use of this feature might be as follows: You can have four or so cams all in the same studio. Shows with each of these cams are started, specifying the same service at the login screen. Clients can be presented with a whosLive page which shows a recent frame from all four cams and he can select one. The launch page can present a videochat session with one of the cams, and a recent frame from the other three can also be shown. The client can switch between them at will.

Sidekick allows you to host chat rooms. In the traditional sense, chat rooms are where many clients can converse with each other using text messages. From a Sidekick perspective, these are shows which have no performer! They provide a way for your clients to interact even if no live content is being offered, encouraging greater site loyalty.

Sidekick allows you to have any number of chat rooms running. Using Sidekick's administractive area, you can add rooms at will. The chat rooms will run continuously without any attention.

Each chat room has an associated service which allows you to specify various charactistics of the room. For example, if you wish to restrict your chat room to be for members only, you can add a restriction.

Sidekick can display recent text chat messages in the client's applet when a client joins a show. This way he will be able to understand the current conversion flow better. This feature is enabled individually for each service. Technically, if enabled, then any clients that are in a show using this service will have their chat messages saved. Also, new clients using this service will have any saved messages displayed.

When displaying the history to clients in public or private services, it takes into account the exclusivity options. So for example, if your private service is configured to not route messages from public to private, then these messages won't be displayed to new private clients.

Sidekick has several html pages which it is responsible for displaying to your clients. These pages follow into the following categories:

These pages are all located in the templates directory and have a .vm extension. They are basically plain text files that can be displayed and easily edited. They contain standard html tags plus a few special directives that Sidekick uses to insert dynamic content, such as a performer's screen name.

CoreTool is a class which the templates can access for retrieving data from Sidekick. The following is a list of calls that can be made:

Tool is a general-purpose class. The following is a list of calls that can be made:

Each client that the site passes to Sidekick for a videochat session can be identified by a clientId. If the clientId is not passed, Sidekick will ask the user for a name. Passing in a clientId means that a user will not be asked for a name and it also allows the site to control precisely what name shows up for each client.

The clientId should be unique for each client. This is important since Sidekick doesn't allow two clients in the same show to have the same name.

There are two ways to pass the clientId to Sidekick. The first way is available if you are using tokens and is passed as a parameter to the GetToken request, something like this:

http://www.yourDomain.com/sidekick/GetToken?allowance=30&clientId=fred

Passing a clientId this way ensures that the user will not be able to modify it in any way (since the second way, described next, will not be available for this client).

The second way is to pass clientId to the whosLive page, which is the first meaningful page displayed for a client. When requesting this page to be displayed for a client, pass the clientId as a parameter, for example:

<a href="$linkAnchor('whosLivePrivate.m')?clientId=fred">
	Click here
</a>

The clientId will simply be held and passed around by Sidekick. Sidekick will not have any dependencies on the string itself or perform any processing with the clientId. Also, the clientId will be passed back by Sidekick in the Begin and End of Session callouts.

On the Whos Live page, Sidekick will display a list of shows that are currently live. In addition, a recent image from the show can be displayed to provide a user with additional details about a show before launching it.

If this feature is enabled, Sidekick will make available a relatively recent frame from the show. The frame's maximum age will depend on the setting of the refreshFrequency parameter in the site.properties file. In other words, when the Whos Live page is displayed, the image displayed for a show will be anywhere from 0 seconds old to refreshFrequency old.

We suggest that you be conservative with this setting so as not to eat up unnecessary bandwidth. A setting of 60000 (60 seconds) will upload only one frame from each performer each minute. For example, even if no one is in a show, frames will be periodically uploaded to the server to satisfy this requirement.

Sidekick will automatically resize the frame to the displayed image size and cache these images for quick subsequent retrieval. Since resizing frames consumes significant CPU cycles, this is another reason why a conservative refreshFrequency setting is appropriate.

#
#   Force the performer client to upload a new frame at least 
#   with this frequency
#   - specify in milliseconds
#   - this feature is used in for voyeur shows where it is desired
#   to have a recent frame from a show on the who's live page even
#   if there are no clients
#   - also used by the server to govern the retrieval of newer frames
#
chat.show.recentFrame.enable = true
chat.show.recentFrame.refreshFrequency = 60000

On the whos live page, clients will normally see a recent frame from a show. If there is no recent frame available, Sidekick will display a graphics that says “Please standby.” For example, this might occur when a show just starts up. If you would prefer to have your own graphics, you can replace it.

When you display Sidekick pages, such as the whosLive, launch and tokenBalance pages, you may wish to change what is displayed based on application-specific arguments. You are able to add your own arguments when linking to these pages. Then within the page, you can then change the display appropriately.

For example, you may wish to pass a theme argument to whosLivePrivate so that it is displayed differently to different clients. In this case, you would designate one of the three available arguments -- arg1, arg2 or arg3, for the theme, and construct your url as follows:

	whosLivePrivate.m?arg1=night

Then, in the whosLivePrivate.vm page, you can have lines such as:

  #if($model.arg1 == 'night')
    #set($color = 'blue')
  #else
    #set($color = 'white')
  #end
  <body bgcolor="$color">

This approach provides a method for your application to dynamically customize the Sidekick pages.

When you wish to display text on a page, there may be various characters that will not be displayed correctly based on syntax. Here are two examples:

We provide two macros that deal with escaping:

	#esc(text string)
	#escJS(text string)

which can be used for escaping strings for html and javascript quoted strings, respectively.

The profile page can be the first page that a client views when entering the Sidekick system. It will accept one of two parameters: id or name. The id is used by Sidekick when a client clicks on a link on the browse page. The name can be used if you want to specify a particular performer by login name.

This chapter describes how you can restrict access to Sidekick pages and sessions to only those users whom you intend. Without these restrictions, less than scrupulous people, would be able to make the video/chat accessible to themselves and those who aren't members. This section describes a system you can enable which will ensure that only intended users and members are able to access your pages and performer shows. In addition, we discuss how to manage abusive users.

There are two places in Sidekick where you can enforce a restriction:

Sidekick has four kinds of restrictions available:

The remainder of this chapter describes these restrictions in more detail.

Access to the videochat portion of the site is via a link, probably located in your members area. This section describes a restriction you can enable which will ensure that only members are able to join your performers shows, for example, only those that arrive from the /members area of your site.

When a request is made from one server to another, the request includes information which indicates from where it originated.

Sidekick will maintain a list of addresses from which clients are accepted. This list can be specified in Sidekick's admin area. The list is stored in referrers.txt in the application directory.

In addition to the above methods of specifying referrers, Sidekick supports specifying referrers in a file named referrers.txt in the application directory. If this file exists, Sidekick include consider these referrers when deciding whether to accept or reject a client. The format of this file is either a comma-delimited list, or a referrer on each line.

The referrer restriction should be enforced on each sidekick page to which clients will be forwarded. On these pages, you should specify the referrer restriction using Sidekick's Setup/Restrictions page.

This restriction will ensure that a client will only see the whosLivePrivate page if he has been referred from a known address. For each attempt to display the whosLivePrivate page, Sidekick will verify that the referrer is as specified. If not, the user will be turned away by displaying the feedback/insufficientPrivledges.vm page. If accepted, Sidekick will also tag this client as authorized so that later Sidekick requests will know that he has been referred from a valid site.

In addition, using Sidekick's admin area, you should specify referrer for the desired service. Doing so means that when a client wishes to launch this service, Sidekick will check that he has been referred from a valid site.

Template pages can use the parmameter $model.referrer if different information is to be displayed based on from where a client arrived at Sidekick.

A token is a key that is associated with a user. This token includes the notion of how long this user is allowed in a private session and is used to limit access to certain parts of the site. Briefly, this is how it works:

Tokens are generated randomly to guarantee uniqueness. Also, tokens automatically expire after a certain length of time to further reduce the likelihood of abuse.

In order to generate a token, your site should make an http get request to /sidekick/GetToken. This request will return a token which can then be inserted into a web page. See the section called “GetToken Request” for further details on the GetToken request.

To have Sidekick restrict access to a launch or whosLive page, you will want specify the token restriction in Sidekick's admin area on the Setup/Restrictions screen for both whosLivePrivate and launchPrivate pages.

In this case, Sidekick will look for a token parameter on this page. It will check that it is valid and display the page if it is. In addition, Sidekick tags this user with this token, so when he later attempts to launch a session, the token can be consulted for validity.

To have Sidekick restrict the launching or running of a session, use Sidekick's admin area to specify the token as a restriction for a service.

Sidekick supports what are commonly referred to as dialers. These systems allow a customer to pay on a usage basis using a 900 number. Sidekick will maintain a list of authorized ip addresses and allow access to only those addresses. Specifically, Sidekick will be continuously informed as to which clients are authorized and which are not so that it can allow or deny access to clients when they request a private show.

Sidekick currently supports two systems: www.dialxs.com and www.phonecredits.com, each of which is explained below.

www.dialxs.com informs Sidekick whenever a client is newly authorized and whenever a client is no longer authorized via a http request. When a client requests to join a private show, he will only be allowed if his ip address is authorized. Likewise, when he is no longer authorized, his session will be terminated.

www.phonecredits.com maintains a file on the Sidekick server with a constantly updated list of authorized clients. Sidekick will read this file whenever a client requests to join a private show to determine if he is authorized. Likewise, when he is no longer authorized, his session will be terminated.

To have Sidekick restrict access to a launch or whosLive page, you will to specify dialer on the Setup/Restrictions screen of Sidekick's admin area.

To have Sidekick restrict the launching or running of a session, add dialer in Sidekick's admin area.

If you have a service with which you only wish an associated session to run for a certain amount of time, you can use the timer restriction to accomplish this. For example, let's say you want to provide access to your free area (the public service) for only a few minutes. Or let's say that for a payment, a client is allowed only so much private time.

To have Sidekick restrict the running of a session, add timer as a restriction in Sidekick's admin area.

There is another property, frontend.timer.expiration which lets you specify the number of seconds that a session will last.

Sidekick allows you to control abusive users ensuring that other users' experiences will be positive. In particular, a performer is able to kick off users at will. Depending on your site, Sidekick can be configured in one of several ways.

First, using the When a client enters a private session, all public sessions will be terminated field in Services, you can specify what happens when a performer kicks off a client. If checked, a client will have his session immediately terminated. If unchecked, a client will remain in the show but his messages will no longer be forwarded to the performer or other clients.

For some sites, having a client's session immediately terminated isn't very effective because he can simply rejoin the show. For these sites, allowing a client to remain in the show, that is, using a silent kickoff, is meant to slowly frustrate him, encouraging him to go away.

In addition, using IP blocking field in Setup/Chat screen, Sidekick will ban his IP address for a period of time of your choosing. This way, a client will not be able to reenter a show for the next half hour or so. Blocking IP addresses indefinitely can cause many support issues because of proxy servers -- you end up blocking access for legitimate users! Since Sidekick only blocks an address for a short period, you can control abusive users with minimal impact to legitimate users.

For advanced blocking, Sidekick will block not only the address of the client but also the several around this address. The idea is that some service providers use a bank of proxies and the client might be reconnected on a nearby proxy. For example, if that client's address is 202.22.22.50 and Block edit is set to 2, then blocked addresses will be 202.22.22.48, 202.22.22.49, 202.22.22.50, 202.22.22.51, and 202.22.22.52. If you set Block edge to 0, only the client's address will be blocked.

Sidekick allows your performers to upload images. Two ways are provided:

In addition, Sidekick allows you to manage these snapshots. In Sidekick's admin area, you can list the snapshots and edit them. For example, when initially uploaded a photo is not available. You can make a photo available so that it will show up for clients to view.

Sidekick has three pages which display these photos:

If you don't want your performers to be able to upload images, there is a property, business.snapshot.enable, that allows you to disable this feature. You can also limit the size of uploads with frontend.fileUpload.size.max.

By default, Sidekick places each uploaded image to a directory, such as:

  .../sidekick/data/performers/images/albert

where albert is the loginName of the performer. The file name will be of the form, 0.jpeg, 1.jpeg, ...

In addition, in each directory, Sidekick creates a file, directory.xml, which includes details about each image file.

When the performer program uploads an image, it uses an HTTP POST multipart request. By default, this post is handled by Sidekick and Sidekick places each uploaded image in a well-defined directory, as described above. Please be aware that if you override this behaviour, Sidekick will not be able to display these images on the profile, gallery and galleryDetail pages since it will have no knowledge of them!

If you would like control over these files, you can override the request. In site.properties, the properties:

  business.snapshot.url.override = true
  business.snapshot.url = http://www.yourDomain.com/yourHandler

are used to specify your request handler. The request will arrive with the loginName and password of the performer, and a description. The form names are the same, that is, loginName, password, and description. The image data will be contained in a separate part. Another parameter, source is set to client if the request originates from the performer program, and to lounge if from Sidekick's web page.

If overriding the default POST behavior, for consistency, Sidekick will also use your url when a performer uploads images using the Sidekick web page in the performer's lounge.

Sidekick includes a number of features that allow it to adapt to your local region. In general, there are four aspects of Sidekick that can be localized:

Before going into detail into these three areas, we should point out that Sidekick's text chat supports many different languages. In fact, all European and asian languages are supported. The right-to-left languages, such as hebrew, are currently not supported.

The Performer Program will automatically detect the region the machine is running on and configure itself appropriately. If Sidekick includes language support for this region then all text will be displayed in this language. If not, English is displayed.

The Administrative area is always displayed in English. You can still enter information, such as screen names and other details, in the language of your choice. Note that the overall character encoding is used to enter and display the page, so it must be set appropriately.

The Client Applet will automatically detect the region for which the browser is configured. If Sidekick includes language support for this region then all text will be displayed in this language. If not, English is displayed.

Using the Setup/General menu in Sidekick's administrative area, you can set the character encoding to either ISO-8859-1 or UTF-8. ISO-8859-1 is a character set that includes English and most european languages and is suitable for these parts of the world. For asian languages, use UTF-8. The following areas are effected by the character encoding:

To configure Java for a specific language, it depends on the vesion of Java. For Java 1.4.2, you would look in the jre/lib directory and copy the desired one, such as font.properties.zh, to font.properties. For Java 1.5, you don't have to do anything.

To configure Windows for a specific language, bring up the Control Panel and then click on Regions and Languages.

To configure your browser for a specific language, select the Options menu choice and select the desired language.

Sidekick allows you to have certain parts of the web site displayed using the https protocol instead of the normal non-secure http protocol. These parts include the login screen and the administrative screens since these contain sensitive information.

Note: This feature is provided, but we would expect it to be utilized in only the most sensitive of environments.

The first thing to do is check that your server has activated secure sockets. This involves enabling a section in your servlet engine's xml configuration file. For example, with Resin, in resin.conf, the entry looks like:

<http port='443'>
  <ssl>true</ssl>
  <key-store-type>jks</key-store-type>
  <key-store-file>
    /home/sidekick/sidekick/keystore/private.keystore
  </key-store-file>
  <key-store-password>whatever</key-store-password>
</http>

and for Tomcat, in server.xml, the entry looks like:

<Connector className="org.apache.catalina.connector.http.HttpConnector"
  port="443" minProcessors="5" maxProcessors="75"
  enableLookups="true"
  acceptCount="10" debug="0" scheme="https" secure="true">
  <Factory className="org.apache.catalina.net.SSLServerSocketFactory"
    keystoreFile="/home/sidekick/keystore/private.keystore"
    keystorePass="whatever"
    clientAuth="false" protocol="TLS"/>
</Connector>

If you are using Apache as your web server, Apache will be configured with a module called mod_jk to communication with Tomcat. In this case, the lines will look like:

<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
    port="8009" minProcessors="5" maxProcessors="75"
    acceptCount="10" debug="0"/>
</Connector>

And second, in Sidekick's admin area, configure Sidekick by checking the Construct pages and links for secure sockets checkbox.

Sidekick can spool a show's chat and video to disk for later administrative review. This feature is intended to provide the administrator with the capability to review a performer's interactions, perhaps for training purposes.

If this feature is enabled, key events about a show are written to disk, including all chat messages and their origin; and when clients joined or left the show. In addition, video frames are written to disk.

Sidekick provides a web-based viewing capability. Simply log as a administrator, and click on Reports/Show Archives.

To enable this feature, go to Setup/Chat and check the Enable archives checkbox.

The Archives Capture Frequency field is set to how often frames should be saved. Since saving frames can consume considerable disk space, a high value such as 30000 (30 seconds) might provide all the information you need, yet consume less resources. The Archives Purge field is used to limit how long archives remain before being deleted by Sidekick.

For some sites, it is desirable to keep a show on 24 hours a day, regardless of whether a performer is in front of the cam. In this case, if there is an Internet glitch or, perhaps the Sidekick server was restarted, then the current show will terminate. With this option, the performer program will detect this and periodically attempt to launch a new show.

See the Setup/Chat screen to change this setting.

In the client applet, the video will stream continually. Since a user might become distracted or walk away from his computer, the streaming video may end up being unseen. Sidekick provides an option that allows the system to turn off the video if there has been no activity by the user for some period of time. Activity, in this case, means that the user has sent a chat message or clicked somewhere on the screen. If the video has been suspended by Sidekick, it will immediately restart when the user clicks on the screen or sends a text message.

When a performer is ending a private session, she might need some time to ready herself before her video is again streamed. Sidekick provides an option so that it will automatically change to Intermission when the last paying client leaves her show. Then, when she is ready, she can click on “Return to Show.”

See the Setup/Chat screen to change this setting.

Sidekick allows you differentiate clients by groupings that you choose. Each group will have a unique name, such as “premier” or “regular.” Each client's group will be displayed to performers next to each client's name. With this information, a performer might know to focus on particular clients more than others.

You can pass a group parameter to the whosLive requests. For example, your whosLive link for a client might look like:

<a href="http://www.yourDomain.com/sidekick/whosLivePrivate.m?group=premier">

For the performer side, when this client (e.g., John) is displayed in her audience list, he will show up something like this:

	John (premier>

Also, all clients of the same group will be shown in the same color to the performer.

In addition, if there is no explicit group specified, Sidekick will attempt to resolve the group by the client's ip address. In the site.properties file, you can specify a list of ip addresses, each with an associated group. Sidekick will compare the client's ip address to each ip address in this list (wildcards are allowed) until a match is found. If no match is found, the group remains unspecified.

When you enter one of the following in your browser:

Sidekick will normally display its home page, which allows an administrator or performer to log in and work with Sidekick. Some Sidekick installations want to suppress this page in order to eliminate Sidekick branding from their site -- even though a client won't see this page unless they modify the URL in their browser.

Using Sidekick's admin screens, you can check the Hide Sidekick home page checkbox. Then Sidekick will display a simple form asking for a login and a password (instead of the usual home page).

In addition, if you feel that you would like to customize this simple form, you can create a file named login.vm in the templates directory. To understand the required html tags for this new page, use View Source in your browser on the login/password page that Sidekick includes.

Sidekick can be deployed to handle the video of a pay per view or per per minute web site. Sidekick surfaces features in a number of areas so that it can be utilized in a pay per view environment. With this option, you can easily build out a pay per view web site by designing your web site and simply calling into Sidekick.

Here are the key components that Sidekick adds to make this possible:

Sidekick is able to integrate with commonly used billing services such as proBilling, ibill, ccbill and others. We have sample scripts available. Please inquire for which services sample scripts are currently available.

Your site will ask a user which purchase option is desired, such as 10 minutes for $15, 15 minutes for $20, etc, and will contact a billing service for approval. Upon approval, you will request from Sidekick a token using GetToken. See the Chapter 8, Pay Per View Option for further details.

Sidekick will return a token, such as "FPO2IHeP7i". This token is then passed when the client is forwarded for videochat to Sidekick, with a link such as "whosLivePrivate.m?token=FPO2IHeP7i".

Sidekick will allow the user to join any show or shows that he wishes, as long as there is remaining time. Should he be in a show when time runs out, he will be kicked out, and sent to a specific url. This url is specified as a <param> to <applet> in the launchPrivate.vm page, for example:

  #set($url = "/place_quickBuy_page_here.html")
  <param name="quickBuyURL" value="$model.encodeUrl($url)">

Sidekick will also record the sessions the client had, which allows an administrator to generate timesheet reports. The administrator can use the report to divide up the revenue amongst performers. The performer can view her activity as well.

Sidekick tracks how much time each paying customer spends with each performer. As an administrator, you can view a report, over a date range, of a list of performers, each with their total time and a percentage of the grand total. This report allows you to proportion earnings according to activity.

In addition, a performer can view a report of her activity over a date range.

Sidekick allows each performer to have a different rate. Sidekick will manage the time that a client has with each performer. For example, if a client is with a higher priced performer, his time will run out sooner.

In order to utilize this feature, go to Sidekick's administrative section, and click on "Display rates." The nominal rate specifies the base rate. This would commonly be set to the typical rate that is charged on the site. You can change the nominal rate as desired; as well, for each performer, you can override their rate.

When a token is requested using GetToken, the requested time can be thought of as based on the nominal rate. Sidekick will allow a client this much time if he is with performers that charge the nominal rate. If he is with a performer at a higher or lower rate, his time will run out that much quicker or slower, respectively.

The administrator's "Timesheet" report breaks out each performer's time and revenue by the rate that it was set. This way, you'll be able to pay each performer their fair share, based on their rate.

To enhance the whosLive page, each show can have displayed its associated performer's rate, such as “$4.99/minute.”

Sidekick maintains information about each active token including the amount of private time remaining. In order to display a page with these details, Sidekick provides a command, tokenBalance.m, which will display the balance using the template tokenBalance.vm.

Normally, the balance is shown using the token associated with the current session. However, if a token parameter is passed, then the balance if the requested token is displayed.