webXkiosk

Copyright 2004-2006, NC State University
Refer to the Info dialog for license information.

Authors:
Hua Ying Ling - Code, design, and implementation.
Everette Gray Allen - Concept, direction, testing and documentation.
Doug Steigerwald - Preferences interface, sheets, video embed, and bug fixes.

Email:
help@ncsu.edu

URL:
Installer - http://www.ncsu.edu/mac/downloads/webXkiosk.zip
Source - http://www.ncsu.edu/mac/downloads/webXkiosk.src.zip
License - http://www.ncsu.edu/mac/software/license.html

Introduction
webXkiosk is a full screen, web kiosk application with security, web screen saver, video embed and some "universal access" features. This application can be used to create public information and/or web kiosks. webXkiosk is meant to be deployed in a secured environment where it has replaced the Finder for a standard or managed user. See deployment tips below for suggestions on how to build a web kiosk. This free software is released under a BSD type License and the source code is available upon request.

Requirements
MacOS X 10.3. webXkiosk may work on earlier versions of MacOS X as long as Apple's WebKit frameworks (install Safari to get these) are installed but has not been tested. There is no version for MacOS 9 and there never will be.
There never will be a port to any other operating system.

Install
Run the installer and let it do the work. The installer should:
1) Put webXkiosk.app in /Applications
2) Put edu.ncsu.webXkiosk.plist into /Libarary/Preferences
3) Create the folder /Libarary/Application Support/webXkiosk
4) Put NCSULicense.txt, authors.html, and webXkiosk.html into /Libarary/Application Support/webXkiosk

Features
Starting with version 1.5 a few features were added to support certain tasks in the restricted kiosk environment.

* NaviLinks - Note navilinks changed between 1.5.0 and 1.5.5 to fix bug by replacing the .button file scheme with the url type described here. NaviLinks is a feature of webXkiosk where the url of form navi: is trapped when clicked and used to simulate pushing a tool bar button. Currently these are back, forward, home, larger, smaller, startover, reload, and print. Example the url navi//print (properly written with the : of course) will do the same thing when clicked in a web page as pushing the print button on the toolbar. We provide this to get around some anoying bugs in WebKit where some common javascript functions (like window.print) are not supported in public frameworks (ie works in safari but not in webkit apps). A navilinks test page is available at http://www.ncsu.edu/mac/software/navilinks.html.

* Printing - there are now 3 preferences which control printing a) Allow Printing - if this is on then pages can be printed if not no other setting matter there will be no printing , b) Show Print Button - shows or hides the print button in the tool bar, c) Show Print Panel - either puts up a standard Apple print dialog if on or prints directly to the printer if off.

* Embed Video - since Quicktime, Real Media and Windows Media video (and other motions graphics) files usually download a file and use a helper to to display even if there are plug-ins to handle the content we need a way to display them in the secured, full screen, webXkiosk environment. The simple answer is to have everyone embed their content but we can not depend on other folks to "be good" and write embed tags. Instead this options is provided which will register with the webkit for the mime types, take the url, wrap it in our own embed tags and display it. Currently the preferences panel allows 240x180, 320x240, 640x480, or fill the available screen (max) and scales the content to display with a controler. NOTE: the correct plug-in must be installed in /Library/Internet Plug-Ins for this feature to work.

Configuration
The preferences file is at /Library/Preferences/edu.ncsu.webXkiosk.plist. There is now a GUI interface to edit this file. Press the command key and k key, then enter the password (hellokiosk is the default password you should change this!) and click Preferences button to get to this sheet. One can continue to edit the file with a plist editor, the defaults tool, or an text editor like TextEdit or BBEdit. The names of the keys explain what the key does for the most part. The options are:

defaultURL - this is the start page for the kiosk. Can use http or file urls

embedVideo - set to true will attempt display with controllers any Quicktime, RealMedia, or WindowsMedia files which would normally download.
    This depends on having the correct plug-ins installed
embedVideoSize - sets the size for the video embed to display at to either 240x180, 320x240, 640x480, or max (which fills the available screen).

hotKeys - a dictionary which assigns function keys to the following features
   ContrastDown - f5 - Decreases the monitor contrast.
   ContrastUp - f6 - Increases the monitor contrast.
   DecreaseFontSize - f7 - Decreases the size of the browser display font.
   IncreaseFontSize - f8 - Increases the size of the browser display font.
   SwitchBlackAndWhite - f9 - Toggles the Universal Access White on Black.
   ZoomIn - f10 - Turns on Universal Access Zoom and zooms in by steps.
   ZoomOut - f11- Turns on Universal Access Zoom and zooms out by steps.
Note: we have selected keys that are usually mapped on desktop machines but testing on laptops has shown that the apple assigned keys may override our key mapping.

password - this string is used as the password to quit or logout. The key
   combination to get the password dialog is Command k. The default password is hellokiosk and it should be changed!

screenSaver - This dictionary contains the keys for the built-in application screen saver. See Deployment tips to learn about using client pull to make it easy to vary the display time and content of pages delivered like impressions on a web banner.
   displayTime - seconds to display each url. Set to 0 to never change
   pageList - a list of http urls to display as the screen saver. This will
       display any type of file that a webkit will display including those
       handled by internet plug-ins as long as they are displayed in-line not
       with a helper application. This includes quicktime and flash among
       others so a series of movies or animations can be delivered as the
       screen saver.
   timeout - inactive minutes to wait before showing the first url. Set to 0
       will never activate the screen saver.

showButton - this dictionary contains true or false settings which control the display of the widgets in the kiosk button bar.
   back - true will display a back navigation button.
    home - true will display a home navigation button. Pressing the home button will cause the defaultURL to display.
   forward - true will display a forward navigation button.
   info - true will display an info button which brings up a sheet dialog that lists the machine name, hardware address of the active network interface, ip number of the active network interface, and any text files which are in /Libarary/Application Support/webXkiosk/. If there is more than one text file they will be appended to the window alphabetically by name.
   larger - true will display a increase font size button.
   print - true will display a print navigation button. Pressing this button will print the view area on screen to the printer either directly or showing a print dialog box depending on the value of the showPrintPanel key
   progress - true will display a progress bar.
   reload - true will display a button to reload the current page.
   search - true will display a page search widget. Clicking the < or > on either end of the search field will find the previous or next occurrence of the search term.
   back - true will display a back navigation button.
   smaller - true will display a decrease font size button.
   startover - true will display a start over button which when pressed will
       a) return kiosk to the url in the defaultURL setting, b) clear all caches, c) clear all histories which dims the back and forward buttons, d) reset all font, contrast, zoom and white on black changes. This is really a flush all or reset to defaults button.
   stop - true will display a button to stop loading he current page.
   url - true will display a sheet dialog which allows the user to type a url.
    urlstring - true will display a selectable text string of the url to the current page starting in the lower left of the button bar.

showPrintPanel - true allows the print dialog to display so users can select printer, copies, etc. false shows no print dialog and prints directly to the default printer.

startOverTimneout - minutes to reload the defaultURL if idle. This works like the user had pushed the Start Over button in that it will a) return kiosk to the url in the defaultURL setting, b) clear all caches, c) clear all histories which dims the back and forward buttons, d) reset all font, contrast, zoom and white on black changes.

showToolbar - true will display the tool bar false hides it regardless of other configuration.

Known Issues

1) The password is stored in the clear in the preferences file.

2) If the screen saver function is used with client pull urls and the pull interval is less than 30 seconds seems to trip a bug in one of the WebKit frameworks after about 8 hours. To avoid the crash reporter screen issue the following command in the Terminal:
defaults write com.apple.CrashReporter DialogType none
If you are cloning unattened kiosk systems make sure a copy of com.apple.CrashReporter.plist is in ~/Library/Preferences for the user who is autologin.

3) Pop-up windows do not work. There is no pop-up blocker in webXkiosk but by nature of taking over the entire screen the pop-ups have no where to display. A nasty side effect is that some new window and resize window calls will reduce and skew the size and location of the viewable area. We make some attempt to repair this after leaving screen saver or when pressing the Start Over button but some times only a quit and relaunch of webXkiosk will fix the problem.

4) A small rectangle "flash" will occur in the lower left corner of the screen when the screen saver activates. This is cosmetic and can not be avoided.

5) Some javascript functions do not seem to work in WebKit applications. Of note window.print does not work.

Deployment tips

I)   A kiosk environment with 10.3
Many of the features in webXkiosk are taken from those suggested by Apple in developer tech. note 2062 (http://developer.apple.com/technotes/tn2002/tn2062.html). This is especially true of the security aspects where we use the SystemUIMode APIs. An important configuration which must be made outside webXkiosk for security is to replace the Finder using the defaults system (See section II below). The authors have deployed 20+ kiosk for about 2 years now using earlier versions of this software. Our environment is set up as follows.
a) Format and install MacOS X 10.3 with customization. Uncheck everything except the languages you want and the BSD subsystem.
b) Create an initial administrative account, call it what you like but we use kioskadmin. Make a password that is secure (min. 5 letters, 2 numbers and a punctuation kind of thing). Also create an standard or managed account , we call ours kiosk. Do give the standard account a password.
c) Do all software updates.
d) As the admin remove everything you can from applications except terminal.
e) Make sure you install any Internet Plug-ins you want. We add a pdf and word plug-in as we have content in these formats. Remember webXkiosk owns the screen for security reasons so if it is not displayed in-line the user will never see it.
f) Install webXkiosk from http//www.ncsu.edu/mac/software/webXkiosk.html.
g) Edit /Libarary/Preferences/edu.ncsu.webXkiosk.plist to change the password, defaultURL, and pageList to suite your site.
h) Set a default printer if you are supporting print. Remember to do this from kiosk as well as the admin. account.
i) Replace the finder for kiosk as while logged in as kiosk using terminal with:
defaults write com.apple.loginwindow Finder /Applications/webXkiosk.app
Optionally while you are in the terminal you should secure the dock from kiosk with the unix command:
chmod -R o-rwx /System/Library/CoreServices/Dock.app
j) set the machine to autologin as kiosk
k) Set the open firmware password per http://developer.apple.com/technotes/tn2002/tn2062.html#Section4
l) Reboot and test.
m) When the configuration is correct we suggest cloning using asr, disk utility, or a third party tool like Carbon Copy Cloner or NetRestore (www.bombich.com).

II) Replace Finder for Single User
According to Apple Developer Technical Note 2062 (http://developer.apple.com/technotes/tn2002/tn2062.html) the Finder can be replaced for a single user by opening the terminal and typing
defaults write com.apple.loginwindow Finder /Applications/webXkiosk.app
It might be possible to do this system wide but we would not recommend it.

III) Remote Management
If you have several kiosk we suggest you enable one or two ways to manage them without visiting each one.   We use ssh and Apple Remote Desktop (ARD). Both these services need to be enabled in the Sharing system preferences before imaging. In the past we have used Timbuktu, NetOctopus and VNC as well so choose what you like and works best in your environment.

IV) Screen Saver Banners
We have run "banner ads" on the kiosk screen savers for lab closings, etc. by using the netscape client pull feature supported by the webkit. Any web page can be made to client pull by adding the following line to the html code:
META HTTP-EQUIV="Refresh" CONTENT="30; URL=whatever.html " Note don't forget to enclose this in <>. This code would pull the relative url whatever.html from the server the current page came from in 30 seconds.

EGA 10222004