Remote Settings Control Settings

Remotely update Kiosk Pro settings using an .xml file hosted on your own server. This feature can be useful for large deployments of kiosks that need to be managed remotely.

Overview

Supported in:

Kiosk Pro Basic, Plus and Enterprise

Multiple kiosks with the same setup can share a single .xml file. For kiosks that have minimal differences in settings, you can use a single file that applies different settings to specific kiosks. For instance, you might want the kiosks in certain areas to default to a different language version of your website.

You can also create separate files for each iPad kiosk that you operate if you need unique configurations for each kiosk.

To use Remote Settings Control:

  1. Create your .xml file by editing one of our templates or by exporting a file from a device that's already been configured.
  2. Upload it to the web through your hosting provider.
  3. Enable = On.
  4. XML File Location = the full URL of your .xml file.
  5. Update Period = how often you want Kiosk Pro to check your server for changes to your .xml file.
  6. Run the kiosk presentation.


Enable Remote Settings Control

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This toggle controls Remote Settings Control feature.

Default Value: Off

Values for Remote Settings Control & Managed App Configuration

Key remoteSettingsEnabled
Key Type boolean
Default Value false


Settings XML File Location

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This should be set to the URL for the configured .xml file on your server. For example: https://www.example.com/settings.xml.

Default Value: blank

If you are using this feature to set up multiple devices (and do not need to update them remotely later), you can also store the file locally on the device. Once stored inside Kiosk Pro's documents folder, the file can be referenced using a file path relative to the documents folder. You can also use the Local File Directory feature to select a file to automatically set as the XML File Location.

Note: It's not possible to use a link shortening service for this setting (like Bit.ly, for example) or other type of redirect as the app isn't able to handle redirections in this context - the app just sees the redirected link as a 404 error and fails to update settings.

Values for Remote Settings Control & Managed App Configuration

Key externalSettingsFile
Key Type string
Default Value (blank)


Update Period

Supported in:

Kiosk Pro Basic, Plus and Enterprise

Define how often Kiosk Pro should check for changes to the .xml file set in XML File Location. When an updated .xml file is found, Kiosk Pro will download the file and refresh the homepage to apply these settings.

Default Value: blank

Unit of Measurement: minutes

Note: The refresh is dependent on the Update Policy setting.

While testing this feature, we recommend setting the update period to 1 or 2 minutes for faster results. When everything is configured correctly, increase the setting for deployment.

Values for Remote Settings Control & Managed App Configuration

Key localSettingsUpdatePeriod
Key Type string
Default Value (blank)


History

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This log shows the last 50 remote setting updates with information such as the file path for the .xml file, whether the update was successful and if not, the error that caused the failure.

The table can be exported to a .csv file into the Kiosk Pro documents folder on the device by selecting this setting and tapping ‘Export’ from the top navigation. Instructions on how to retrieve this file is available here.


Editing Settings

To download a .zipped file containing a template for remotely changing settings, 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). Look through the key/value pairs to find the settings your kiosk uses.

Be careful not to replace anything inside the <key></key> tags. Each setting must have a <key>Key</key> and a <key>Value</key>. All changes are made to the tags that come after these.

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>Key</key><string>homePage</string>
<key>Value</key><string>kioskgroup.com/kp-start</string>

and change the contents of the string tags to <string>http://example.com</string>.

Settings that are toggled either on or off accept <true/> or <false/> like the Show Navigation Bar setting:

<key>Key</key><string>showNavigationBar</string>
<key>Value</key><true/>

The above pair sets the Show Navigation Bar setting to on.

You can quickly test the basic syntax of your .xml file by using the Test Settings XML for Errors setting.

Ampersands ('&') are a reserved character in XML. If your URL uses one, you will need to instead use the unit code &amp;.

Be very careful to not set the XML File Location to an incorrect value in your XML file. For example, if you misspell the domain name, you will lose the ability to remotely update your iPad and will have to visit the kiosk in-person to manually correct the error.

Note: If you previously had Allowed Domains set and your new homepage would not be allowed by the previous Allowed Domains list, Kiosk Pro may need to be exited and restarted for the XML settings to successfully take effect.


Test Settings XML for Errors

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This feature allows you to test your .xml file for errors. When this setting is selected, Kiosk Pro will check the .xml file set in the XML File Location for Remote Settings Control.

If no errors are found, the message "XML file is valid" will appear. You can also test a file from within this setting by tapping "Test File" in the top navigation.

If the .xml file is not valid, the app stops scanning the file at the point where 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 test the file again to confirm that there are no 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>Vaule</key> instead of <key>Value</key>
  • Example: <key>Value</key><string></string>
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 misspelling.
Example: </flase> instead of </false>
List of unknown keys A set of <key> & <string> tags have incorrect data inside them.
Example: <string>PassCode</string> instead of <string>settingsPassCode</string>
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 & Transfer Current Settings

Supported in:

Kiosk Pro Basic, Plus and Enterprise

You can export your current Kiosk Pro settings as an .xml file in order to update other Kiosk Pro app settings. 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.

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

Note: You will need to turn on Remote Settings Control and configure an XML File Location prior to exporting the settings in order to successfully update another app. Also, if there's a Passcode for App Settings set (located in the Admin category in main app settings), please make sure you know what it is. As an alternative, you can delete the passcode before exporting the settings.

The exported .xml file will not include 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 .xml, you can either configure the .xml manually using the templates or you can export an .xml and copy and paste the key-value pair for that setting from the template to the configured .xml.

Updating with the settings file

Once the settings file is stored in Kiosk Pro on the new iPad:

  1. Open the Kiosk Pro settings
  2. Scroll down to the Remote Management & Notifications category and select Remote Settings Control.
  3. Enable = On.
  4. Settings XML File Location = "settings.xml"
  5. Tap Run Kiosk Presentation and your settings will update.

Applying a shared settings file

Kiosk Pro can share app settings between different versions and devices. This can make it easier to set up a handful of devices or upgrade from Lite without the need to manually configure each app.

The shared .xml file will not include the following settings:

  • Refresh Homepage (in Lite only)
  • SMTP password (for security)
  • Unique iPad ID (to prevent accidentally overwriting)
  • Kiosk Name (to prevent accidentally overwriting)
  • Unit Name (to prevent accidentally overwriting)

To transfer app settings on the same device:

  1. Open the Kiosk Pro settings on the iPad that is correctly configured.
    • In Lite: Scroll down to the Upgrade category and select Transfer Settings to Different Version.
    • In Basic, Plus or Enterprise: Scroll down to the Remote Management & Notifications category and select Remote Settings Control > Transfer Settings.
  2. Select "Transfer Current Settings" in the bottom left corner.
  3. Choose the app to share the file with.

The selected app will be opened and the setting configuration will be saved in the app's documents folder as "settings.xml".

To transfer app settings to a different device using AirDrop:

  1. Open the Kiosk Pro settings on the iPad that is correctly configured.
    • In Lite: Scroll down to the Upgrade category and select Transfer Settings to Different Version.
    • In Basic, Plus or Enterprise: Scroll down to the Remote Management & Notifications category and select Remote Settings Control > Transfer Settings.
  2. Select "Transfer Current Settings" in the bottom left corner.
  3. Choose "AirDrop".
  4. Select the device you want to share to.
  5. On the other device, a prompt will appear listing available apps. Select the app you want to share your settings to.

The selected app will be opened and the setting configuration will be saved in the app's documents folder as "settings.xml".

To apply the transferred settings:

  1. Open the Kiosk Pro settings on the iPad that is correctly configured.
  2. Scroll down to the Remote Management & Notifications category and select Remote Settings Control.
  3. Select Transfer Settings.
  4. Select "Apply Transferred Settings" and confirm.

The app will immediately apply the "settings.xml" file and update the app settings.


Editing an XML File Template

A .zipped file containing a settings template for Remote Settings Control is available here.

Unzip this template and then open it in a plain text editor (like TextEdit or Notepad. Do not use a word processor like Microsoft Word, which can add formatting to the text). Look through the key/value pairs to find the settings your kiosk uses.

Be careful not to replace anything inside the <key></key> tags. Each setting must have a set of <key>Key</key> tags and a set of <key>Value</key> tags. All changes are made to the tags that come after these.

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>Key</key><string>homePage</string> <key>Value</key><string>kioskgroup.com/start</string>

and change the contents of the string tags to <string>http://example.com</string>.

Settings that are toggled either on or off accept <true/> or <false/>. For example, if you wanted to turn on the Show Address Bar setting, you would write:

<key>Key</key><string>showAddressBar</string> <key>Value</key><true/>

You can quickly test the basic syntax of your .xml file by using the Test Settings XML for Errors setting.

Ampersands ('&') are a reserved character in XML. If your url uses one, you will need to instead use the unit code &amp;.

Be very careful to not set the Settings XML File Location to an incorrect value in your XML file. For example, if you misspell the domain name, you will lose the ability to remotely update your iPad and will have to visit the kiosk in person to manually correct the error.

Note: If you previously had Allowed Domains set and your new homepage would not be allowed by the previous Allowed Domains list, Kiosk Pro may need to be exited and restarted for the XML settings to successfully take effect.


Applying Remote Settings to Specific Kiosks

Our remote settings algorithm allows you to define certain sections of the remote setting .xml to apply to certain kiosks based on the Unique iPad ID or Group ID. For example, you could set a different homepage for each kiosk. There are two main options for this - using the identifier as a placeholder within settings or using it in combination with our 'ApplyTo' key.

Using Placeholders

Kiosk Pro Plus and Kiosk Pro Enterprise allow placeholders to be used in settings in order to automatically pull other information. For example, using a placeholder in your URL for a settings file allows you to customize specific devices without having to manually configure the URL for each one.

Note: When using a placeholder in a URL, special characters will be encoded. We recommend limiting use of things like spaces or punctuation when using placeholders.

Unique iPad ID & Group IDs

To use an identification setting, you can insert $UniqueiPadID$ or $GroupID#$, where the number sign is replaced with the Group ID number you want to use. For example, Group ID 4 would be $GroupID4$.

As an example, for a kiosk with a unique id of lobby1, a homepage of https://www.example.com/$UniqueiPadID$.html would be translated into https://www.example.com/lobby1.html.

Device Name

The device name can be used in Kiosk Pro settings by using the placeholder $DeviceName$.

As an example, for an iPad named "ConferenceRoom", using Settings XML File Location of https://www.example.com/$DeviceName$.xml would be translated into https://www.example.com/ConferenceRoom.xml.

Using 'ApplyTo'

Using the 'ApplyTo' key within your .xml allows you to define certain sections of the remote settings .xml file to apply to certain kiosks based on the Unique iPad ID or Group ID. This lets you maintain and host a single file, while still having different settings for individual or groups of kiosks.

To enable this functionality, use the ApplyTo element after the setting you want to define:

<key>ApplyTo</key>
<array>
    <string>(unique iPad ID here)</string>
</array>

As an example - to set the homepage of a single kiosk with a Unique iPad ID = 'Hallway1', you could set:

<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.kioskgroup.com</string>
    <key>ApplyTo</key><array><string>Hallway1</string></array>
</dict>

ApplyTo entries are applied sequentially, allowing you to define a default setting for all devices and then override that setting for specific kiosks:

<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.kioskgroup.com</string>
</dict> 
<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.google.com</string>
    <key>ApplyTo</key><array><string>Hallway1</string></array>
</dict><br>

In addition, our ApplyTo element also accepts two wildcards: '*' and '?':

  • ? - matches any character zero or one time, matching only one time
  • * - match any character zero or more times, matching as many times as possible

Wildcard examples:

  • kiosk_id = '1' is matched by: '*' or '?'
  • kiosk_id = '12' is matched by: '*' or '**' or '*?' or '*2' or '1*' or '??' or '1?' or '?2'
  • kiosk_id = '123' is matched by: '*' or '???' and so on

These wildcards can be used to apply settings to specific groups of kiosks, as in:

<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.kioskgroup.com</string>
    <key>ApplyTo</key><array><string>Hallway*</string></array>
</dict>
<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.google.com</string>
    <key>ApplyTo</key><array><string>Auditorium*</string></array>
</dict>

where all kiosks whose ids begin with 'Hallway' (like Hallway1 or HallwayAlcove) would display https://www.kioskgroup.com and all kiosks whose ids begin with 'Auditorium' (like Auditorium1 or AuditoriumBalcony) would display https://www.google.com.

To apply a setting to kiosks without a Unique iPad ID set, you can either not use the 'ApplyTo' element for the setting at all or use an empty string to apply the setting specifically to those kiosks.

So, for example, to apply a setting to a kiosk without a Unique iPad ID set, you could use:

<key>ApplyTo</key> - is not used at all

- or -

<key>ApplyTo</key><array><string></string></array>

Group IDs

In the Plus and Enterprise versions, you can also use Group ID's within the 'ApplyTo' statement. For example, if you want to set the homepage of any kiosk with a GroupID = 'Location1', you could set:

<dict>
     <key>Key</key><string>homePage</string>
     <key>Value</key><string>https://www.kioskgroup.com</string>
     <key>ApplyTo</key>
     <array>
     	<string>Location1</string>
     </array>
 </dict>

If needed, you can set multiple strings inside the <array> tag as in:

<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.kioskgroup.com</string>
    <key>ApplyTo</key>
    <array>
    	<string>Hallway1</string>
        <string>Hallway2</string>
        <string>Hallway3</string>
    </array>
</dict>

Remove an identifier

In 9.2, we changed remote updates to ignore blank identifier fields to help avoid removing the identifier by mistake. If you need to remove or empty an identifier field, you can set a RewriteOldValueByEmptyValue key to true or false to let Kiosk Pro know that an empty field is intentional. For example:

<dict>
    <key>Key</key><string>uniqueiPadID</string>
    <key>Value</key><string></string>
    <key>ApplyTo</key><array><string>Hallway1</string></array>
    <key>RewriteOldValueByEmptyValue</key><true/>
</dict>

Troubleshooting

Make sure the kiosk presentation is running

  • The app does not apply remote updates while the settings menu is open, so you must run the presentation. The app will check for an update when the presentation starts.
  • For a visual indicator of the update applying, turn on the Show Update Indicator setting.

Check the app settings

  • Double-check that Remote Settings Control is turned On and the URL set in Settings XML File Location does not contain any typos. This must also be set to a full URL, including the http:// or https:// protocol.
  • If you're waiting for an update after the initial update when the presentation starts, make sure an Update Period is set and that Apply Updates is configured how you want it to behave.

Check your settings XML file

  • Make sure you've set the Settings XML File Location to the same URL set in your app settings.
  • Make sure the file is valid using the Test Settings XML for Errors setting.

Change Log

Included in version 1.0. Added ability to test .xml file for errors in version 5.0. Added ability to export current settings in version 6.3. Removed unique identifiers from exported settings in version 6.4. Added ability to view update history in version 6.7. Added ability to share settings with other Kiosk Pro apps and devices in versions 9.3 & 9.4.

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