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:

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 exporting the settings 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:

This toggle controls the Remote Settings Control feature.

Settings XML File Location

Supported in:

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

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

Update Period

Supported in:

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.

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.

History

Supported in:

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

After exporting an XML file from the app, open the file 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).

Each setting has a key (an identifier) and a value. Keys are unique to each setting, while values can vary depending on the type of setting. Possible value types:

• string - used when the setting needs a user-inputted value, like a URL, text, or whole number
• integer - used for settings with multiple options, each with a number identifier. For example, Show Settings has 3 options with the possible values being 0, 1, or 2.
• real - used for number values with decimals. In our case, that usually means a setting with a range, like brightness level or battery percentage
• boolean - these are either 'true' or 'false' and are used for toggle settings (for example: <true/> or <false/>)

For example, to change the Homepage setting, first you would find the key/value pair in the file:

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

and change the contents inside the string tags to your URL or filepath. For example: <string>http://website.com</string>.

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

Be very careful not to set the Settings XML File Location to an incorrect value in your XML file. Otherwise, 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 restarted for the XML settings to successfully take effect.

Test Settings XML for Errors

Supported in:

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 Settings XML File Location.

If no errors are found, the Validation Status will say "Valid". 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 will stop scanning the file at the point where an error is found and will give you information about the error, usually 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.

If the .xml file is valid but has errors, the Validation Status will say "Valid, but with semantic errors" and a table listing which keys and/or values have errors.

Export & Transfer Current Settings

Supported in:

You can export your current Kiosk Pro settings as an .xml file in order to update other Kiosk Pro app settings. There are several options for exporting:

• 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 - Transfer the file to another version of Kiosk Pro or send it via AirDrop to another device. More info is below.

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

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

Export the 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 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 to another version of Kiosk Pro or to send it via AirDrop to another device. See below for more detail.

Share the settings to another version of the app or another device

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.

1. Open the Kiosk Pro settings on the iPad that are correctly configured.
2. In Lite: Go to Upgrade > Transfer Settings to Different Version and tap 'Transfer Current Settings' in the lower right corner.
3. In Basic, Plus or Enterprise: Go to Remote Management & Notifications > Remote Settings Control > Export & Transfer Current Settings > Export All Settings or Export Changed Settings Only > tap 'Share' in the lower right corner. Proceed to step 4 or step 5 as applicable.
4. If sharing to an app on the same device:
1. In the pop-up menu, find and tap the desired app to share the settings with (the target app).
2. The target app will open automatically to the 'Apply Settings Transferred via AirDrop' screen and the setting configuration will be saved in the app's documents folder as 'settings.xml'. The screen will show the message 'Settings file is available and ready to apply'.
3. Tap 'Apply' at the bottom right corner of the screen and tap 'OK' to apply 'settings.xml'. Tap 'OK' again to confirm that 'Settings were updated'. The user is navigated to the main settings menu of the target app.
5. If sharing the app to a different device (the target device):
1. Check that WiFi is enabled in system settings on both devices. The devices do not need to be connected to a WiFi network, but WiFi must be enabled for the devices to communicate via AirDrop.
2. On the target device, verify that in iOS settings, General > AirDrop > Everyone is selected. This can be disabled after the file transfer is complete.
3. Choose 'AirDrop'.
4. Select the target device you want to share with.
5. On the target device, an AirDrop pop-up will prompt the user to 'Open with...' a list of available options. Select the Kiosk Pro app where the settings will be applied.
6. The selected Kiosk Pro app will open automatically to the 'Apply Settings Transferred via AirDrop' screen and the setting configuration will be saved in the app's documents folder as 'settings.xml'. The screen will show the message 'Settings file is available and ready to apply'.
7. Tap 'Apply' at the bottom right corner of the screen and tap 'OK' to apply 'settings.xml', then 'OK' to confirm that 'Settings were updated'. The user is taken to the main Settings menu of the target app on the target device.
8. Run the presentation.

Applying Remote Settings to Specific Kiosks

Using a single .xml file, you can apply specific settings to individual kiosks based on the Unique iPad ID or Group ID. For example, if your kiosk deployment shared most of the same settings, but had different homepages, you could define a different URL for each kiosk. There are two main options for this - using the identifier as a placeholder within settings or using it in combination with the '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 the use of spaces or special characters 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. In the Plus and Enterprise versions of Kiosk Pro, you can also use Group ID's within the 'ApplyTo' statement. This lets you maintain and host a single file, while still having different settings for individual or groups of kiosks.

To enable this functionality, Kiosk Pro supports the use of an ApplyTo key formatted as follows:

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

If needed, you can set multiple strings inside the  <array> tag, which will act as OR operators, allowing you to define multiple Unique iPad IDs or Group IDs to match and apply settings. 

Current V2 XML Format

When exporting the current V2 format for Remote Settings Control, all settings are wrapped in a single dictionary entry.  To use the ApplyTo element, you'll need to add an opening and closing set of array tags and one or more additional dictionary entries to allow for customization.  

If an Apply To element is contained in a dictionary entry, any settings defined in that dictionary set will only be applied to those kiosks.  Dictionary sets are applied sequentially, allowing you to apply default settings to all your devices through a main dictionary set without an ApplyTo element defined as the first dictionary in the file.  You can then overwrite specific settings as needed using one or more additional dictionary sets, which are applied sequentially after the main dictionary set. 

<?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>kioskSettings_v2</key>
   <!-- Remote Settings Control configuration exported from Kiosk Pro Basic -->
   <!-- This file uses Kiosk Pro's current XML format for Remote Settings Control (see 'kioskSettings_v2' above), compatible with devices running app version 10.4 or later. If your project includes kiosks on older versions of the app, you can learn more about using our legacy format at kioskgroup.com/legacy-xml -->
   <!-- Documentation for each setting and its possible values is available in our Knowledge Base at support.kioskgroup.com. A spreadsheet with these values is also maintained at kioskgroup.com/kiosk-pro-remote-settings -->
 
      <array>

         <!-- Primary settings to be applied to all kiosks -->
         <dict>		
            <!-- Homepage -->
            <key>homePage</key>
            <string>https://www.kioskgroup.com</string>
				
            <!-- Show Status Bar -->
            <key>showStatusBar</key>
            <true/>
				
            <!-- Show Address Bar -->
            <key>showAddressBar</key>
            <true/>
         </dict>

         <!-- Setting Overrides for Homepage and Status Bar only if Unique iPad ID = A or Unique iPad ID = B -->
         <dict>
            <!-- Homepage -->			
            <key>homePage</key>
            <string>https://support.kioskgroup.com</string>

            <!-- Show Status Bar -->
            <key>showStatusBar</key>
            <false/>
				
            <key>ApplyTo</key>
            <array>
               <string>A</string>
               <string>B</string>
            </array>	
         </dict>
	
      </array>
</dict>
</plist>

Legacy XML Format

When using the Legacy Format for Remote Settings Control, each setting is wrapped in a set of <dict></dict> tags and the ApplyTo element is included inside that dictionary entry after the key and value.  As an example - to set the homepage of a single kiosk with a Unique iPad ID = 'Hallway1', you could set:

<dict>
    <key>homePage</key>
    <string>https://www.kioskgroup.com</string>
    <key>ApplyTo</key>
	<array>
           <string>Hallway1</string>
           <string>Hallway2</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>homePage</key>
    <string>https://www.kioskgroup.com</string>
</dict> 
<dict>
    <key>homePage</key>
    <string>https://www.google.com</string>
    <key>ApplyTo</key>
	<array>
           <string>Hallway1</string>
           <string>Hallway2</string>
        </array>
</dict>

Wildcard Support

The ApplyTo element 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>homePage</key>
    <string>https://www.kioskgroup.com</string>
    <key>ApplyTo</key>
	<array><string>Hallway*</string></array>
</dict>
<dict>
    <key>homePage</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.

Special behaviors for identifiers

By design, the Remote Settings Control algorithm ignores blank identifier fields to prevent remotely clearing an identifier by mistake.

The identifiers that this applies to are Unique iPad ID, Group ID 1 through 6, and the Kiosk Name and Unit Name used for the Remote Management Server. These specific identifiers are also not exported with the rest of the app's settings when using one of Kiosk Pro's settings exports.

If you need to reset or empty one of these identifier fields remotely, you can set an additional key RewriteOldValueByEmptyValue to true to let Kiosk Pro know that clearing the field is intentional. This follows the format of the 'ApplyTo' element as described above. 

<dict>
	<key>uniqueiPadID</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.

Legacy Format

Prior to version 10.4, Kiosk Pro used a slightly different format for .xml files. Both versions are still supported.

For users who need to export settings in the legacy format, you must first turn on the Export Remote Settings XML in Legacy Format toggle located in the Advanced Settings menu.

XML formats are identified by the first key in the file - this must be set to either "kioskSettings_v2" for the newer format, or "kioskSettings" for the legacy format.