Managed App Configuration for MDM Settings
In this article
Managed App Configuration allows users to configure app settings remotely through Mobile Device Management (or MDM).
While Managed App Configuration is increasingly supported by MDM providers, it is not a feature included in every MDM solution. We currently do all testing in-house with SimpleMDM and Jamf Pro. To determine if Managed App Configuration is supported by your MDM provider, you’ll need to contact them directly.
To use Managed App Configuration, the app must be installed and managed through the MDM. This requires the use of license codes purchased through Apple Business Manager. It is not possible to use Managed App Configuration with apps installed through iTunes, the App Store directly on the device, or Apple Configurator.
MDM solutions operate at the device level, communicating directly with the iOS/iPadOS operating system using standard Apple-provided APIs. When using Managed App Configuration, the MDM service sends a dictionary of settings to the app, which then applies them. This can occur either as a part of the initial app installation or later as a management command.
Settings are defined using key-value type-value sets. A full list of keys, value types and default values for each setting in Plus and Enterprise is maintained here.
How these are inserted depends on the interface of the MDM you are using - options include:
- individual inputs
- XML insertion
- constructed interface via managed schema files
Many MDM providers, including SimpleMDM, format their Managed App Configuration settings as a series of individual inputs where the user defines the key, value type, and value for each setting. The following shows an example of setting the Unique iPad ID to the device's serial number using SimpleMDM.
Some MDMs support a single large text field formatted as XML, similar to our Remote Settings Control but with a slightly different format. While this method does generally require a basic understanding of XML, it has the benefit of allowing you to update a large number of settings quickly and efficiently. As an idea of what this looks like, to update the Homepage setting and Idle Time Limit, you would add the following dictionary through your MDM:
<dict> <key>homePage</key> <string>http://developer.apple.com/</string> <key>idleTime</key> <integer>30</integer> </dict>
You can build this dictionary manually using a template as described below in Editing Settings or you can export one from within the app based on the current configuration.
Constructed Interface via Managed Schema File
Other MDM providers use a standardized schema file we provide to construct a version of the app's settings menu within the MDM interface. Settings can be configured in the same way that they are inside the app via text input, selection dropdown, and toggle switch.
Customizing Setting Values for a Specific Device
When applying settings through Managed App Configuration, most MDM's are structured in such a way as to only allow for a single configuration to be applied to all devices being deployed, but it is often possible to identify a specific device or apply custom settings through token substitution or custom variables.
Most MDM providers now allow token substitution in the settings configuration. This allows a unique identifier to be set based on information the MDM is able to pull about the device, allowing for a large deployment to use unique identifiers without having to manually enter them on each device. While these may vary from vendor to vendor, they generally include:
- Device Name
- Phone Number, if applicable
- Serial Number
- WiFi MAC Address
Each provider may format these device variables differently; please contact your MDM provider directly for additional details.
Certain MDM providers also allow you to set up custom variables that can be defined within the MDM interface and passed to the app, which makes it easy to customize any of the app's settings for a specific device. An overview of what this looks like when using SimpleMDM is available here.
Settings are defined in most cases using key-value type-value sets. A full list of keys, value types and default values for each setting in Plus and Enterprise is maintained here.
If your MDM supports XML insertion, you can download a .zipped file containing a template for defining app settings through Managed App Configuration here.
Unzip this template and then open it in a plain text editor (like Notepad, not a word processor like Microsoft Word, which can add formatting to the text). The template is ordered in the same way as the app’s settings menu, set to the app's default settings, and labeled for easy identification.
Settings that accept text will be filled out in between the <string></string> tags and settings that require a number will use <integer></integer> tags. As an example, to change the homepage setting of the kiosk, you would find the matching key/value pair in the list:
and change the contents of the string tags to:
In an MDM that enters values as a set of multiple inputs, like SimpleMDM, this would translate to:
Settings that are toggled either on or off accept <true/> or <false/> values. For example, the Show Address Bar setting (turned On):
In an MDM that enters values as a set of multiple inputs, like SimpleMDM, settings that are toggled either on or off are considered to be boolean values. For example, the Show Address Bar setting (turned On):
Ampersands ('&') are a reserved character in XML. If a URL or another setting requires one, you will need to instead use the unit code ‘&’.
Test MAC Settings XML for Errors
Test your current .xml file for errors that might prevent the app from successfully updating through Managed App Configuration.
To test, you will need to upload the file to a web server where Kiosk Pro can access it or move the file over to the Kiosk Pro documents folder (where you would simply enter the filename).
If no errors are found, the message ‘File is valid’ will appear.
Otherwise, the app stops scanning the file when an error is found and will give you information about the error, including which line of the file it is on. Once the error has been corrected, you will need to retest the file to confirm that there are not additional errors later in the file.
Examples of errors
|List of keys with missing content|| A set of
| Encountered empty
||An integer tag is missing a value.|
| Found non-key inside
|Encountered unknown tag ___ on line #|| A tag has incorrect data, often as a result of a mispelling.
|List of unknown keys|| A set of
| Value missing for key inside
|| A set of
|List of keys with impossible value||An integer is using an incorrect value.|
|Encountered unknown ampersand-escape sequence at line #||An ampersand symbol ('&') is being used without being properly escaped.|
|Can’t Load XML File||The url is incorrect or unavailable.|
Export Current Settings to XML File
Export your current Kiosk Pro settings as a formatted list of key-value pairs for use in Managed App Configuration. Settings are exported in the .xml format used by MDMs that allow you to add all settings by copy and pasting into a single text field (like JAMF Pro).
When exporting settings, you have two options:
- Export All Settings - exports your entire setting configuration.
- Export Changed Settings Only - exports only the settings that have changed from the default.
There are a couple of settings not included in an exported list - specifically the SMTP password (for security), the Unique iPad ID, and the Kiosk Name and Unit Name for the Remote Management Server (to prevent accidentally overwriting with the values from the original device).
If you need to set any of these values through Managed App Configuration, you can either configure all settings manually using the template provided or you can export a settings list and copy and paste the key-value pair for that setting from the template to the configured list.
To export the settings:
- Open the Kiosk Pro settings on the iPad that is configured.
- Scroll down to the Managed App Configuration category and select Export.
- Select Export All Settings.
- Select "Export to file" or "Send by email" from the navigation.
A file called "mdm_settings.xml" will be created in the Kiosk Pro documents folder on the iPad, which you can transfer via iTunes. If you chose "Send by email", a window will appear allowing you to create an email, and the file will be deleted from the documents folder after being sent. This file’s contents will then need to be copied and pasted into the correct place within your MDM.
Steps for setting up a Mail account:
- Open the iPad’s General Settings (silver gear icon).
- Choose Mail from the sidebar and choose "Add Account".
- Choose an email provider from the list and enter your login information for your email account.
- Make sure that the toggle for "Mail" is On.
- Choose "Save" and you’re ready to go.
To transfer the file to your computer:
- Connect your iPad to a computer and open iTunes.
- Access your device by clicking the 'iPad' or 'iPhone' button that appears at the top left of the screen.
- In the left sidebar that appears, click 'Apps'.
- Scroll down to 'File Sharing' and click on the version of Kiosk Pro you are using.
- Select "mdm_settings.xml" and click 'Save to...' at the bottom of the file listings to save this to your computer.
Added to Enterprise in version 7.1, added to Plus in version 7.5.1