Configuring SnapKiosk
via MDM.

SnapKiosk reads its homepage, idle behavior, and lockscreen branding from Apple's standard Managed App Configuration. Push a single dictionary from your MDM and every iPad in your fleet picks it up — no per-device typing, no QR codes, no on-device admin steps. This page documents every key, the validation rules, and how to wire it up in the major MDMs.

1.How it works

iOS exposes MDM-delivered settings to every app via a standard UserDefaults key: com.apple.configuration.managed. When you push a Managed App Configuration profile, iOS writes the dictionary you supplied under that key — and SnapKiosk reads it at launch.

SnapKiosk uses a single dictionary with up to nine string/number/bool fields. Push it once, paired with the app install, and the kiosk arrives ready to run. If the dictionary is missing, SnapKiosk falls back to the welcome screen (where an on-device admin would type the URL manually).

2.The configuration schema

Every key SnapKiosk reads from com.apple.configuration.managed. Field names are case-sensitive.

The five lockscreen* keys are intentionally MDM-only — they're not surfaced in the on-device Settings UI because branding belongs to IT, not to the customer-facing tablet.

3.A minimal example

The smallest valid payload — just point the kiosk at a URL and accept every default.

<?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">
<plist version="1.0">
<dict>
    <key>homeURL</key>
    <string>https://kiosk.example.com</string>
</dict>
</plist>

Defaults applied: 5-minute idle reset, 30-second "Still there?" warning, attract screensaver on, SnapKiosk-blue accent on the default attract icon.

4.A complete example (with branding)

Every supported key, with reasonable production values. Push this to a fleet to get a fully-branded kiosk with the IT contact line visible to customers when something breaks.

<?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">
<plist version="1.0">
<dict>
    <!-- Core kiosk behavior -->
    <key>homeURL</key>
    <string>https://kiosk.acme.corp/check-in</string>

    <key>idleResetSeconds</key>
    <integer>180</integer>

    <key>idleWarningSeconds</key>
    <integer>20</integer>

    <key>screensaverEnabled</key>
    <true/>

    <!-- Lockscreen / attract branding -->
    <key>lockscreenTitle</key>
    <string>Welcome to Acme</string>

    <key>lockscreenSubtitle</key>
    <string>Tap anywhere to start. Need help? helpdesk@acme.corp</string>

    <key>lockscreenLogoURL</key>
    <string>https://cdn.acme.corp/branding/logo-white.png</string>

    <key>lockscreenTintHex</key>
    <string>#FF6B00</string>

    <key>lockscreenBackgroundHex</key>
    <string>#0A0F1F</string>
</dict>
</plist>

5.Console-specific notes

Each MDM has its own UI for delivering Managed App Configuration. The mechanism is identical (it ends up in com.apple.configuration.managed on the device) — only the path through the console differs.

6.Validation & rejected values

SnapKiosk validates the config at launch. If anything is structurally wrong, the kiosk falls back to either an on-device saved config or the welcome screen — whichever applies. This is deliberate: a typo in MDM shouldn't strand a fleet on a blank page.

• Missing homeURL — the entire managed config is rejected; SnapKiosk falls back to on-device or welcome.
• homeURL has no host ("https:///", "not-a-url") — rejected.
• homeURL uses an unsupported scheme (file://, javascript:, ftp://) — rejected. Only http and https are accepted.
• Empty string in any optional field — treated as "unset"; the default applies. Useful for clearing a field without having to delete the key.
• Invalid hex color ("zzzz", "#GGG", "") — silently ignored; the default color applies.
• Bogus lockscreenLogoURL — fetched anyway; if it fails, the attract screen falls back to the default tap icon. The rest of the config still applies.

7.Verifying the config arrived

Three ways to confirm a kiosk picked up the pushed config:

1. On-device — open Settings via the two-finger admin gesture. A "Managed by your IT team" banner at the top of Settings means MDM config is active and the fields are non-editable.
2. The last-load beacon — SnapKiosk writes the current URL to com.snapapps.SnapKiosk.lastLoad in standard UserDefaults on every successful page load. Any MDM that can query app preferences can read it. Details in the ASAM guide.
3. Diagnostics log — Settings → Diagnostics shows recent crashes, hangs, and CPU exceptions captured by MetricKit. A clean list with a recent timestamp means the app launched and ran. Also written to diagnostics.json in the app's Documents container.

8.Troubleshooting

The kiosk shows the welcome screen instead of my URL

The managed config didn't arrive, or it failed validation. Check, in order:

1. The app was installed via MDM (not sideloaded or App Store-installed by the user) — Managed App Configuration only attaches to MDM-delivered installs.
2. The configuration profile is scoped to the right device group.
3. The homeURL is a full https:// URL with a host — not kiosk.example.com alone, not www.-only.
4. Field names are exact, case-sensitive (homeURL, not homeUrl or HomeURL).

Settings shows my values but the lockscreen still has the SnapKiosk defaults

The branding fields are optional and silently fall back to defaults on any parse failure. Common causes:

• Hex colors missing the # are fine (we accept either), but typos in the hex (non-hex characters, wrong length) silently fail. #FF6B00 works; #FF6BX0 falls back.
• The lockscreenLogoURL must be a real, reachable image. Inspect diagnostics.json or run a test load from the iPad's browser.
• Empty strings are intentionally treated as "unset" — make sure you're pushing actual values, not blank strings.

I updated the MDM config but the iPad still shows the old values

Managed App Configuration is delivered on the next MDM check-in, not immediately. Either wait for the next regular sync window, force a sync from your console (Jamf: Update Inventory; Intune: Sync; etc.), or restart SnapKiosk on the device — the config is re-read on every app launch.

I want a single device to override the MDM config temporarily

You can't. MDM config takes precedence over the on-device saved config — this is by design, so a customer can't permanently break a managed kiosk via Settings. To change one device, change the MDM profile scoped to it.