Managed App Configuration for MDM Settings

Overview

Supported in:

Kiosk Pro Plus and Enterprise

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. 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/or 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

Individual Inputs

Many MDM providers, including Miradore and 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.

XML Insertion

Some MDMs, including Jamf Pro, 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.


Editing Settings

Supported in:

Kiosk Pro Plus and Enterprise

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:

<key>homePage</key>
<string>kioskgroup.com/kp-software</string>

and change the contents of the string tags to:

<string>http://example.com</string>.

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):

<key>showAddressBar</key>
<true/>

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 ‘&amp;’.


Customizing Settings for a Specific Device

When applying settings through Managed App Configuration, the majority of 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 still often possible to identify a specific device or apply custom settings through token substitution or custom variables.  

Some providers, including Miradore, allow you to create multiple config files to apply to specific devices or groups of devices. 

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
  • ICCID
  • ID
  • IMEI
  • MEID
  • Model
  • Phone Number, if applicable
  • Serial Number
  • UDID
  • 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.


Test MAC Settings XML for Errors

Supported in:

Kiosk Pro Plus and Enterprise

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 <key> tags have incorrect or missing data inside of them or with them.
  • Example: <key>homepage</key> instead of <key>homePage</key>
  • Example: <key></key>
Encountered empty <integer> on line # An integer tag is missing a value.
Found non-key inside <dict> at line # The <dict> tag is either missing a closing </dict> tag or there are incorrect items inside the set of <dict> tags.
Encountered unknown tag ___ on line # A tag has incorrect data, often as a result of a mispelling.
Example: </flase> instead of </false>
List of unknown keys A set of <key> & <string> tags have incorrect data inside them.
Example: <key>PassCode</key> instead of <key>settingsPassCode</key>
Value missing for key inside <dict> at line # A set of <key> tags is missing data.
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

Supported in:

Kiosk Pro Plus and Enterprise

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).

You have a couple options for how the file is exported:

  • Save - Save the file on the device to transfer to your computer using iTunes.
  • Email - Email the file to yourself. This requires a Mail account to be set up on the iPad.
  • Share - AirDrop the file to another Apple device, or transfer to another app. More info below.

You also have the option to export a file with only the settings you've made changes to.

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:

  1. Open the Kiosk Pro settings on the iPad that is correctly configured.
  2. Scroll down to the Remote Update category and select Remote Settings Control.
  3. Select Export & Transfer Current Settings.
  4. Select Export All Settings or Export Changed Settings Only.
  5. Select "Save" if you want to transfer the file to your computer. A file called "mdm_settings.xml" will be created in the Kiosk Pro documents folder on the iPad.
  6. Select "Email" if you want to email the file. A window will appear allowing you to create an email, and the file will be deleted from the documents folder after being sent.
  7. Select "Share" if you want to transfer the file via AirDrop, or to another app. More info below.

Change Log

Added to Enterprise in version 7.1, added to Plus in version 7.5.1

Still stuck? How can we help? How can we help?