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
- A supervised iPad enrolled in your MDM (needed for Single App Mode).
- Kioskys bought in volume in Apple Business Manager (a paid app, assigned to your devices or users) and installed by the MDM as a managed app: the configuration is delivered only to managed apps.
- The app's Bundle ID: app.consulenza.kioskys (the same for everyone, you do not need to change it).
Keys
| Key | Type | Values | What it does |
|---|---|---|---|
kioskURL | string | address | The kiosk site. Without a scheme https:// is added (http:// for IPs and local network). |
autoStartSeconds | integer | 0, or 3–120 | Seconds of the start countdown. 0 = no settings screen, the kiosk starts immediately. Default 10. |
settingsPIN | string | 4–8 digits | PIN protecting the settings. The user cannot change or remove it. Write it as a string to keep leading zeros. |
allowUserConfiguration | boolean | true / false | false = the settings screen is read-only. Default true. |
allowedHosts | array of strings | host names | Extra domains the page may navigate to (for example an external login). Host names only, no scheme or path. |
allowCamera | boolean | true / false | Grants the camera to the pages of the configured site. Default true. |
allowLocation | boolean | true / false | Grants the location. If false, navigator.geolocation answers "denied". Default true. |
staleReloadMinutes | integer | 0–1440 | Minutes in the background after which the page reloads on return. 0 = never. Default 0 (off). |
orientation | string | auto, portrait, landscape | Orientation lock (portrait and landscape also allow the 180° flip). Default auto. |
energySaverEnabled | boolean | true / false | Energy Saver: after the set minutes without touches the screen dims to energySaverBrightness (default 5%); a touch restores 100%. Default true. |
energySaverMinutes | integer | 1–120 | Minutes without touches before dimming. Default 5. |
deviceName | string | 1–80 characters | Device name, visible to pages as window.Kioskys.deviceName. |
openingHours | dictionary | mon … sun, daily | Opening 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. |
closedMessage | string | up to 200 characters | Text shown on the closed screen. |
idleResetSeconds | integer | 0, or 10–3600 | After this many seconds without touches (or key presses) the kiosk returns to its first page. 0 = off. Default off. |
idleResetClearData | boolean | true / false | Also clear cookies and website data when it resets. Default true. |
playlist | array of dictionaries | type, url, seconds, muted | Playlist 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. |
closedBrightness | integer | 0–100 | Screen brightness while closed (percent). Default 5. |
closedMedia | dictionary | type, url | A 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. |
bridgeEnabled | boolean | true / false | The JavaScript bridge (window.Kioskys.scan, beep). Default true. |
disablePageZoom | boolean | true / false | Blocks page zoom: pinch, double-tap and the page's own viewport. Default true. |
scannerCamera | string | front, back | Camera used by Kioskys.scan(). Default front. |
energySaverBrightness | integer | 0–100 | Screen brightness (percent) while the Energy Saver has dimmed the screen. Default 5. Raise it if you use a screensaver. |
screensaverEnabled | boolean | true / false | Screensaver: 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). |
screensaverMedia | dictionary | type, url | The 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). |
customCSS | string | up to 100,000 characters | CSS 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. |
customJS | string | up to 100,000 characters | JavaScript 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
- Numbers and booleans sent as strings ("10", "true") are accepted. Invalid values are ignored and reported, they never break the app.
- The settingsPIN is in clear text inside the profile (administrators of the MDM can see it). The app does not store it on the device.
- Changes made in the MDM are applied while the app is open; a new address reloads the page.
- The app reports its status in com.apple.feedback.managed (version, address, page loaded, camera and location permission state, configuration issues).
- Kioskys keeps the iPad awake while it is in the foreground. To stop people leaving the app, use Single App Mode.
- Five quick taps in the top-left corner of the screen open the settings again (read-only if allowUserConfiguration is false; a settingsPIN, if set, is asked first).
- The same keys also work without an MDM: the QR setup page turns them into a QR code that copies the settings to an iPad. What an MDM sets always wins and the user cannot change it.
Ready-made files
The profiles already carry the Bundle ID app.consulenza.kioskys. Regenerate their UUIDs (uuidgen) before use.
- App configuration (all keys)
- Single App Mode profile (MDM locks the iPad on Kioskys)
- Autonomous Single App Mode profile (the app locks itself)
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>