WebKiosk 9 Documentation

Overview

WebKiosk provides a full-screen, configurable web browser that can restrict navigation, hide system UI elements, and run unattended. Both versions share core concepts but differ in platform-specific features.

Getting Started

macOS

On first launch, you will see a welcome screen. Click Open Settings to configure your kiosk. Settings can always be opened from:

• The menu bar (if visible)
• The keyboard shortcut Command + Option + P
• A Settings button in the toolbar (if configured)

When the menu bar is hidden, the shortcut Command + Option + P still works to open settings.

iPad

On first launch, you will see a welcome screen. Tap Open Settings to configure your kiosk. Once configured, settings are hidden behind a secret gesture. In Settings → Security, choose one of:

• Triple tap — Tap the screen three times quickly
• Draw a circle — Draw a circle on the screen
• Swipe with two fingers — Swipe with two fingers

Perform the gesture anywhere on the screen to open the settings panel when the app is in kiosk mode. When you finish configuring, tap Done to dismiss settings and return to the kiosk interface.

Starting Mode

Configure what the app shows when it launches or returns to home.

macOS: Local Website

Two options are available:

• Static website — Place an index.html file in the app’s Documents folder. The path is shown in Settings (e.g. ~/Library/Containers/.../Documents). Use Open Content Folder in Finder to open it.
• Apache web server — Use macOS’ built-in Apache server. The app checks http://localhost. Configure Apache to start on boot and serve from /Library/WebServer/Documents.

iPad: Local Website

Add a web.zip file containing your site. The archive must include an index.html at the root or in a subfolder. Connect the iPad to a Mac and copy web.zip into the WebKiosk app in the Files app. In Settings → General, tap Unzip content to install. The app will use the extracted content as the start page.

Online Website

Enter the default URL (e.g. https://www.example.com). The app will open this page at launch and when returning home.

macOS only: Enable Wait until the network is ready to delay loading until the network is available. Set a timeout in seconds. Hide navigation errors until the wait ends suppresses error alerts during the wait.

Idle Timer

When enabled, the app tracks user inactivity. After the configured timeout (in seconds), it can:

• Return to default home page — Navigate back to the start screen.
• Clear cookies and cache after idle time — Reset browsing data when the idle timer fires.

Toolbar

The toolbar provides navigation and custom actions. You can show or hide it, change its position, and customize its contents.

Visibility & Position

• Position — Top, Bottom, Left, or Right.
• Alignment — Start, Center, or End.
• Height — Adjust the toolbar height (30–100 px).
• Icon scale — Scale button icons (0.5–2.0).

Toolbar Items

Add, remove, and reorder items from the inline editor. Available items include:

You can also add Separators, Logo (custom image), and Space for layout.

Address Field

Enable Show URL field to display an editable address bar. You can place it at the top or bottom, enable a Go button, and choose whether the field is editable. A search field can also be shown in the toolbar when configured.

Status Zone

The status zone shows information about the current page, such as the URL and loading state.

• Position — Top or Bottom.
• Text alignment — Left, Center, or Right.
• Height & font size — Adjust appearance.
• Show security level — Display lock icon for HTTPS.
• Show loading gauge — Show a progress indicator while loading.

iPad: You can hide the iPadOS status bar (time, battery, etc.) in General settings.

Browser

Privacy & Security

• Enable JavaScript — Turn on or off for compatibility with modern sites.
• Block advertising services — Use content blocking to block domains (e.g. doubleclick.net, googlesyndication.com). Add or remove domains in the list.
• Always clear cookies at launch — Clear all cookies and cache when the app starts.

Browser ID (User Agent)

Set a custom User Agent string to improve compatibility with some websites or to identify WebKiosk traffic in analytics.

Popup Behavior

Choose how popup windows are handled:

• Block — Prevent popups.
• Redirect to main window — Load popup URLs in the main browser.
• Open Sheet — Show popups in a separate sheet/modal window.

Gestures

• macOS: Enable zoom with trackpad gestures; allow touch scrolling on blank areas.
• iPad: Enable zoom with two fingers.

Advanced (macOS)

• Launch at login — Start WebKiosk when the Mac starts.
• Web Inspector — Enable Safari’s Web Inspector for debugging.
• Virtual keyboard — Show an on-screen keyboard when text fields are focused (useful for touchscreens). Can be customized.

URL Control

Restrict which websites users can visit.

Configure the error message shown when a site is blocked.

macOS: Whitelist and blacklist can be imported or exported as JSON files for backup or deployment.

Favorites

Favorites are displayed as cards when the start screen is set to Favorites. Users tap a card to open that site.

Favorites View

• Preview style — Rounded or square cards.
• Title at bottom — Show the favorite name below the icon.
• Cards per line — Number of cards per row.
• Card size, spacing, border — Adjust layout and appearance.
• Colors — Background, card, border, and title colors.

Adding Favorites

Each favorite has:

• Name — Display label.
• URL — Full URL (e.g. https://example.com).
• Icon — Optional SF Symbol (e.g. globe, play.rectangle.fill).
• Color — Icon color.

macOS: Favorites can be imported/exported as JSON.

Security

Password Protection

Require a password to open settings. Enter a password in the field, then enable the toggle. If you try to enable it with an empty password, an alert will ask you to enter one first.

Kiosk Options

Both platforms:

• Clear cookies when returning to home page
• Clear cookies when opening favorites

macOS only:

• Hide menu bar
• Block Command+Q — Prevent quitting with the keyboard.
• Disable Apple Menu
• Disable Force Quit shortcut
• Disable Process Switching — Prevent switching to other apps.
• Disable Session Termination
• Disable Hide Application
• Force app to stay in front
• Block PDF display — Block PDFs from loading in the browser.

Some options are disabled in Trial Mode and require a license.

iPad only:

• Secret gesture — Triple tap, draw a circle, or two-finger swipe.
• Guided Access — Integrate with iPadOS Guided Access for single-app mode. Requires a supervised device and MDM profile, or manual setup in Settings → Accessibility → Guided Access.

Display

Prevent display sleep — Keep the screen on (macOS uses power management; iPad uses isIdleTimerDisabled).

Sync

Keep settings, favorites, and URL lists in sync across devices signed in with the same Apple ID.

• macOS: Enable iCloud sync in Settings → Sync. Requires a volume license for multiple kiosks.
• iPad: Enable Cloud Sync in Settings → Sync. Settings, favorites, whitelist, blacklist, and related data sync via NSUbiquitousKeyValueStore.

Ensure you are signed in to iCloud. Changes may take a few moments to appear on other devices.

Visit History (Logs)

The app keeps a log of visited URLs (up to 1000 entries). You can:

• macOS: Copy to clipboard, export as JSON, or clear logs.
• iPad: View the list and clear logs.

Technical & Advanced

macOS: Multi-Screen Content

When multiple displays are connected, you can enable Content for connected screens and set a URL to show on the secondary display(s). This is useful for dual-screen kiosks.

macOS: Local Content Path

For static local content, the app uses the sandboxed Documents folder. The exact path is shown in Settings → General. Use Open Content Folder in Finder to access it.

iPad: ZIP Structure

The web.zip file should contain an index.html as the entry point. The app searches recursively and uses the first index.html found (excluding __MACOSX). Other files (CSS, JS, images) should be in the same folder or referenced with correct relative paths.

Search Engines

When using the Search toolbar action, you can configure search engines (Google, Bing, DuckDuckGo, Yahoo, etc.) with their query URLs. The Search button opens a sheet where users enter a query, which is then sent to the selected engine.

Custom Actions

Toolbar actions can be configured with:

• Open URL — Specify the URL to open.
• Display Message — Show an alert with custom text.
• Help — Show a help message (e.g. “A staff member will arrive shortly”).
• Feedback — Open a feedback URL.

Virtual Keyboard (macOS)

When enabled, an on-screen keyboard appears when a text field in a webpage receives focus. Useful for touchscreen kiosks. You can customize the layout (normal, shift, numbers) in the keyboard customizer.

Network Wait

When loading an online URL at launch, the app can wait for the network before loading. It performs HEAD requests to the default URL and retries until the network is ready or the timeout is reached.

Mailto Links

By default, mailto: links are blocked and show an alert. This prevents users from opening the default mail client in kiosk mode.