Kioskys

MDM documentation

Kioskys supports Managed App Configuration. Your MDM delivers a plist of keys to the app; any key you set wins over what the user typed, and the user cannot change it. All keys are optional.

What you need

Keys

KeyTypeValuesWhat it does
kioskURLstringaddressThe kiosk site. Without a scheme https:// is added (http:// for IPs and local network).
autoStartSecondsinteger0, or 3–120Seconds of the start countdown. 0 = no settings screen, the kiosk starts immediately. Default 10.
settingsPINstring4–8 digitsPIN protecting the settings. The user cannot change or remove it. Write it as a string to keep leading zeros.
allowUserConfigurationbooleantrue / falsefalse = the settings screen is read-only. Default true.
allowedHostsarray of stringshost namesExtra domains the page may navigate to (for example an external login). Host names only, no scheme or path.
allowCamerabooleantrue / falseGrants the camera to the pages of the configured site. Default true.
allowLocationbooleantrue / falseGrants the location. If false, navigator.geolocation answers "denied". Default true.
staleReloadMinutesinteger0–1440Minutes in the background after which the page reloads on return. 0 = never. Default 0 (off).
orientationstringauto, portrait, landscapeOrientation lock (portrait and landscape also allow the 180° flip). Default auto.
energySaverEnabledbooleantrue / falseEnergy Saver: after the set minutes without touches the screen dims to energySaverBrightness (default 5%); a touch restores 100%. Default true.
energySaverMinutesinteger1–120Minutes without touches before dimming. Default 5.
deviceNamestring1–80 charactersDevice name, visible to pages as window.Kioskys.deviceName.
openingHoursdictionarymon … sun, dailyOpening hours. Each day is "HH:mm-HH:mm", "24h" or "closed"; days not listed are closed unless daily is given. An empty dictionary = always open. Closing earlier than opening means open past midnight.
closedMessagestringup to 200 charactersText shown on the closed screen.
idleResetSecondsinteger0, or 10–3600After this many seconds without touches (or key presses) the kiosk returns to its first page. 0 = off. Default off.
idleResetClearDatabooleantrue / falseAlso clear cookies and website data when it resets. Default true.
playlistarray of dictionariestype, url, seconds, mutedPlaylist mode: pages, photos and videos shown in turn, in a loop (up to 50). type: page, image or video; seconds: 3–3600 (0 for a video = until it ends); muted: true silences a video. Photos and videos are downloaded and saved on the iPad, so they play with no delay. Replaces kioskURL. An empty array = classic kiosk.
closedBrightnessinteger0–100Screen brightness while closed (percent). Default 5.
closedMediadictionarytype, urlA photo or video shown while closed: {type: image or video, url}. It is downloaded and saved on the iPad; a video repeats. An empty dictionary = the standard closed screen.
bridgeEnabledbooleantrue / falseThe JavaScript bridge (window.Kioskys.scan, beep). Default true.
disablePageZoombooleantrue / falseBlocks page zoom: pinch, double-tap and the page's own viewport. Default true.
scannerCamerastringfront, backCamera used by Kioskys.scan(). Default front.
energySaverBrightnessinteger0–100Screen brightness (percent) while the Energy Saver has dimmed the screen. Default 5. Raise it if you use a screensaver.
screensaverEnabledbooleantrue / falseScreensaver: while the Energy Saver has dimmed the screen, a photo or video is shown instead of the kiosk; a touch brings the kiosk back. It has no timer or brightness of its own. Default off (it turns on by itself if you send screensaverMedia without this key).
screensaverMediadictionarytype, urlThe screensaver's photo or video: {type: image or video, url}. It is downloaded and saved on the iPad; a video repeats, without sound. An empty dictionary = no content (the screensaver does not start).
customCSSstringup to 100,000 charactersCSS added to every page of the kiosk site (and of the domains in allowedHosts), not to third-party pages the site redirects to. It applies before the page appears.
customJSstringup to 100,000 charactersJavaScript run on every page of the kiosk site (and of the domains in allowedHosts) once loaded; window.Kioskys is available. Errors go to the page console. With customJS your MDM decides what runs in the kiosk: write it like your own site's code.

Good to know

Ready-made files

The profiles already carry the Bundle ID app.consulenza.kioskys. Regenerate their UUIDs (uuidgen) before use.

Example configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
  Kioskys - Managed App Configuration
  Paste this dictionary into the "App Configuration" field of your MDM, for the app with the Bundle ID
  app.consulenza.kioskys. All keys are optional: keep only the ones you need.
  A key that is present wins over what the user set by hand, and the user cannot change it.
-->
<plist version="1.0">
<dict>
	<!-- Kiosk address. Without a scheme https:// is added (http:// for IPs and local network). -->
	<key>kioskURL</key>
	<string>https://example.org/kiosk</string>

	<!-- Seconds of the start countdown: 0 = no settings screen, the kiosk starts immediately; otherwise 3-120. -->
	<key>autoStartSeconds</key>
	<integer>0</integer>

	<!-- PIN protecting the settings (string of 4-8 digits). The user cannot change or remove it.
	     Note: it is in clear text inside the profile (MDM administrators can see it). It is not stored on the device. -->
	<key>settingsPIN</key>
	<string>4821</string>

	<!-- false = the settings screen is read-only (no local changes). Default: true. -->
	<key>allowUserConfiguration</key>
	<true/>

	<!-- Extra domains the page may navigate to (e.g. an external login). Host names only, no https:// and no paths. -->
	<key>allowedHosts</key>
	<array>
		<string>login.example.com</string>
	</array>

	<!-- Camera and location granted to the pages of the configured site. Default: true. -->
	<key>allowCamera</key>
	<true/>
	<key>allowLocation</key>
	<true/>

	<!-- Minutes in the background after which the page reloads on return (0 = never). Default: 0. -->
	<key>staleReloadMinutes</key>
	<integer>0</integer>

	<!-- Screen orientation lock: auto (free), portrait or landscape.
	     Portrait and landscape also allow the 180-degree flip. Default: auto. -->
	<key>orientation</key>
	<string>landscape</string>

	<!-- Energy Saver: after energySaverMinutes without touches the brightness drops to energySaverBrightness (default 5%); a touch restores 100%.
	     Default: on, 5 minutes. Minutes: 1 to 120. Brightness: 0 to 100. -->
	<key>energySaverEnabled</key>
	<true/>
	<key>energySaverMinutes</key>
	<integer>5</integer>
	<key>energySaverBrightness</key>
	<integer>30</integer>

	<!-- Device name, visible to pages as window.Kioskys.deviceName (max 80 characters). -->
	<key>deviceName</key>
	<string>Warehouse iPad 1</string>
	<!-- Opening hours: mon..sun (or daily) as "HH:mm-HH:mm", "24h" or "closed". Days not listed are closed unless daily is given.
	     An empty dictionary means always open. Outside the hours the kiosk shows a closed screen at minimum brightness. -->
	<key>openingHours</key>
	<dict>
		<key>daily</key>
		<string>08:00-20:00</string>
		<key>sun</key>
		<string>closed</string>
	</dict>
	<key>closedMessage</key>
	<string>We are closed. See you tomorrow!</string>
	<!-- Closed screen: brightness in percent (default 5) and an optional photo or video that is downloaded and saved on the iPad.
	     Use <dict/> for the standard closed screen (moon and message). -->
	<key>closedBrightness</key>
	<integer>40</integer>
	<key>closedMedia</key>
	<dict>
		<key>type</key><string>image</string>
		<key>url</key><string>https://example.org/closed.jpg</string>
	</dict>
	<!-- Inactivity reset: after this many seconds without touches the kiosk returns to its first page (0 = off; 10-3600). -->
	<key>idleResetSeconds</key>
	<integer>120</integer>
	<key>idleResetClearData</key>
	<true/>
	<!-- Playlist: pages, photos and videos shown in turn, in a loop (up to 50). It replaces kioskURL when present; an empty array = no playlist.
	     seconds: 3-3600; for a video 0 means "until it ends". -->
	<key>playlist</key>
	<array>
		<dict>
			<key>type</key><string>page</string>
			<key>url</key><string>https://example.org/menu</string>
			<key>seconds</key><integer>30</integer>
		</dict>
		<dict>
			<key>type</key><string>image</string>
			<key>url</key><string>https://example.org/offer.jpg</string>
			<key>seconds</key><integer>10</integer>
		</dict>
		<dict>
			<key>type</key><string>video</string>
			<key>url</key><string>https://example.org/promo.mp4</string>
			<key>seconds</key><integer>0</integer>
			<key>muted</key><true/>
		</dict>
	</array>
	<!-- JavaScript bridge (window.Kioskys.scan / beep) and the camera used for scanning: front or back. -->
	<key>bridgeEnabled</key>
	<true/>
	<!-- Blocks page zoom: pinch, double-tap and the page's own viewport. Default: true. -->
	<key>disablePageZoom</key>
	<true/>
	<key>scannerCamera</key>
	<string>front</string>
	<!-- Screensaver: while the Energy Saver has dimmed the screen (energySaverMinutes/energySaverBrightness) this photo or video is shown; a touch brings the kiosk back. It has no timer of its own. -->
	<key>screensaverEnabled</key>
	<true/>
	<key>screensaverMedia</key>
	<dict>
		<key>type</key><string>video</string>
		<key>url</key><string>https://example.org/screensaver.mp4</string>
	</dict>
	<!-- Custom CSS and JavaScript, applied to the pages of the kiosk site (not to third-party pages). Up to 100000 characters each. -->
	<key>customCSS</key>
	<string>.cookie-banner { display: none !important; }</string>
	<key>customJS</key>
	<string>document.documentElement.classList.add('kiosk');</string>
</dict>
</plist>