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

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 identifer) 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 they 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 to send via AirDrop to another device. More info 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 via AirDrop to another device. See below for more detail.

Share the settings to another app or 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 is correctly configured.
2. In Lite: Go to Upgrade > Transfer Settings to Different Version and tap 'Transfer Current Settings'.
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'.
4. If sharing to an app on the same device:
1. Choose the app to share the settings to.
2. The selected app will be opened and the setting configuration will be saved in the app's documents folder as 'settings.xml'.
5. If sharing the app to a different device:
1. Choose 'AirDrop'.
2. Select the device you want to share to.
3. On the other device, a prompt will appear listing available apps. Select the version of Kiosk Pro you want to share your settings to.
4. Kiosk Pro will be opened and the setting configuration will be saved in the app's documents folder as 'settings.xml'.

Apply the shared settings

1. Open the Kiosk Pro settings on the iPad that is correctly configured.
2. Go to Remote Management & Notifications > Remote Settings Control.
3. Select Export & Transfer Current Settings.
4. Select Export All Settings or Export Changed Settings Only.
5. Tap 'Apply' and confirm.

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

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 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>homePage</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>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></array>
</dict><br>

In addition, the 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>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.

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 of Kiosk Pro, 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>homePage</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>homePage</key>
    <string>https://www.kioskgroup.com</string>
    <key>ApplyTo</key>
    <array>
    	<string>Hallway1</string>
        <string>Hallway2</string>
        <string>Hallway3</string>
    </array>
</dict>

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. For example:

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