Preview Changes will not be visible to customers until published.

[Archived] Remote Settings Control Settings

Settings

Related Settings

Templates

JavaScript API Documentation

Common Questions

Overview

This feature allows you to change the settings of Kiosk Pro remotely by changing corresponding values in an XML file and hosting it on your servers for Kiosk Pro to visit.

Default: Off

Remote Settings Control can be extremely useful when deploying many kiosks with similar settings as multiple kiosks can be set up with a single .xml file. 

Alternately, you may want to create a separate XML file for each iPad kiosk that you operate, giving you more individualized control over each kiosk. For instance, you might want the kiosks in certain areas to default to a different language version of your web site. More on  Applying Remote Settings to Specific Kiosks.

To set up 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. Set XML File Location to the full internet address path of your XML file.
  4. Toggle Enable to On.
  5. Set the Update Period to how often you want Kiosk Pro to check your server for changes to your XML file.

XML File Location

This setting should be set to the URL to the configured .xml file on your server. This requires the full internet address (including 'http://', 'https://', and any prefix subdomain such as 'www') of the .xml file. For example: 'http://www.example.com/folder/settings.xml'. 

If you do not have a server available to host this file, you can host it on Dropbox.  

If you are just 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 by syncing it with iTunes. Once synced to Kiosk Pro's Documents folder, the file can be referenced in this setting through a relative file path. In most cases, this will just be the file name (as it will be stored in the root of the Documents folder), but if you need to check, you can do so by going to 'General' > 'Local Mode' and looking for the file in that list.

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

Test File for Errors

This setting allows you to test your settings.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 ‘Remote Setting 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>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 # - An 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: <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.

Update Period

This setting is how often Kiosk Pro will check your server for changes to your XML file. When an updated file is found, Kiosk Pro will download the .xml file referenced and refresh the homepage to apply these settings. If Update Policy is set to Delay While Idle Timer is Active, the update will be delayed until the idle timer triggers.

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

History

This setting 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 it’s failure.

The table can be exported to a .csv file into the Kiosk Pro Documents folder on the iPad by selecting ‘Export’ from the top right corner. You can find instructions on how to retrieve this file in our  Storing content Locally on the iPad article.

Export

You can export your current Kiosk Pro settings as an .xml file in order to update other Kiosk Pro app settings. You have a few options with exporting:

  • Transfer the file to your computer using iTunes.
  • Email the file to yourself. (requires a Mail account set up on the iPad)

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.
  4. Select "Export to file" 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.
  5. Select "Send by 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.

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 set (located in Admin category in main app settings) please make sure you know what it is. Alternately, you could 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 Update category and select Remote Settings Control.
  3. Enable = On.
  4. XML File Location = "settings.xml"
  5. Tap Run Kiosk Presentation and your settings will update.

Share

You can share Kiosk Pro settings between Kiosk Pro apps and devices:

  • Share with another Kiosk Pro version on the same device. (added in 9.3)
  • Share with Kiosk Pro on another device using AirDrop. (added in 9.3)
  • Share with a Mac using AirDrop. Requires OS X Lion or later. (added in 9.4)

Steps for how to share settings are available here.

Editing an XML File Template

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/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 File 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 External Settings File name 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

The Unique iPad ID can be used as a placeholder within Kiosk Pro settings by inserting ‘$UniqueiPadID$’ (capitalized and spaced as shown, without the single quotes). Each Group ID can be used as a variable by inserting ‘$GroupID#$’ (so ‘$GroupID1$’, ‘$GroupID2$’, etc., again capitalized and spaced as shown, without the single quotes). 

As an example, for a kiosk with a unique id of ‘lobby1’, a homepage of 'http://www.example.com/$UniqueiPadID$.html' would be translated into 'http://www.example.com/lobby1.html', allowing you to customize specific devices without having to manually configure the URL for each one. For a kiosk with a Group ID 1 of ‘texas-locations’, a Remote Settings Control URL of 'http://www.example.com/$GroupID1$.xml' would be translated into 'http://www.example.com/texas-locations.xml'.

Using 'ApplyTo'

Using our 'ApplyTo' key within your .xml 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.  This lets you maintain and host a single file, while still having different settings for individual or groups of kiosks.

To enable this functionality, we 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>http://www.ipadkiosks.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>http://www.ipadkiosks.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>http://www.ipadkiosks.com</string>
    <key>ApplyTo</key><array><string>Hallway*</string></array>
</dict>
<dict>
    <key>Key</key><string>homePage</string>
    <key>Value</key><string>https://www.kioskgroup.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 'ipadkiosks.com' and all kiosks whose ids begin with 'Auditorium' (like Auditorium1 or AuditoriumBalcony) would display 'kioskgroup.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 our 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>http://www.ipadkiosks.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>http://www.ipadkiosks.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>

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