Managed App Configuration Settings

Settings


Overview

Added to Enterprise in version 7.1
Added to Plus in version 7.5.1
Managed App Configuration, a feature introduced with iOS 7 which allows users to configure app settings remotely through Mobile Device Management (or MDM), is now supported in the Plus and Enterprise versions of Kiosk Pro.
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’s Volume Purchase Program. It is not possible to use Managed App Configuration with apps installed through iTunes, the App Store directly on the device, or Apple’s Configurator software.
MDM solutions operate at the device level, communicating directly with the iOS 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 pairs, similarly to Remote Settings Control but with a slightly different format. 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.
Some MDM providers allow token substitution in the settings configured. This allows a unique identifier to be set based on information the MDM is able to pull about the device, like serial number, UDID, phone number, or WiFi MAC address, allowing for a large deployment to use unique identifiers without having to manually enter them on each device.  Some MDM's also have the ability to pull specific user-configured identifiers, like display name or email address, for use as a variable.
Several MDM providers, including SimpleMDM, format their Managed App Configuration settings as a series of individual inputs, instead of the single text area.  The following shows an example of setting the Unique iPad ID to the device's serial number using SimpleMDM.

screen-shot-2016-09-19-at-10-30-23-am

Other providers may format these inputs & device variables differently; please contact your MDM provider directly for additional details.

Editing Settings

To download a .zipped file containing a template for defining app settings through Managed App Configuration,  visit this page.
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>kioskproapp.com/start</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/> like the Show Address Bar setting, set here to 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.  Again the Show Address Bar setting, set here to 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;’. 

Export

This setting allows you to export your current Kiosk Pro settings as 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).

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 configured.
  2. Scroll down to the Managed App Configuration category and select Export.
  3. 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:

  1. Open the iPad’s General Settings (silver gear icon).
  2. Choose ‘Mail, Contacts, Calendars’ from the sidebar and choose ‘Add Account’.
  3. Choose an email provider from the list and enter your login information for your email account.
  4. Make sure that the toggle for ‘Mail’ is On.
  5. Choose ‘Save’ and you’re ready to go.

To transfer the file to your computer:

  1. Connect your iPad to a computer and open iTunes.
  2. Access your device by clicking the 'iPad' or 'iPhone' button that appears at the top left of the screen.
  3. In the left sidebar that appears, click 'Apps'.
  4. Scroll down to 'File Sharing' and click on the version of Kiosk Pro you are using.
  5. Select "mdm_settings.xml" and click 'Save to...' at the bottom of the file listings to save this to your computer.


Test File for Errors

This setting allows you to test your current .xml 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 are:
  • List of keys with missing content - A set of <key> tags have incorrect or missing data inside of them or with them.
    • Example: <key></key> instead of <key>homePage</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 # - An tag has incorrect data, often as a result of a mispelling.
    • Example: </flase> instead of </false>
  • List of unknown keys - A set of 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.

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