Remote Settings Control Settings

Settings

Templates

JavaScript API Documentation

Common Questions


Enable

This setting 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 with a new version number is found, Kiosk Pro will download the .zip 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

This setting allows you to export your current Kiosk Pro settings as an .xml file, which can then be transferred to another iPad and used to update the Kiosk Pro settings on that device. You'll need to be able to connect your iPads to a computer with iTunes, or have a Mail account set up on your iPad.

Please note that you will need to enable and configure a URL for Remote Settings Control prior to exporting the settings or these will be blank when the file is used to update other devices.

There are a couple of settings not included in an exported .xml file - 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 .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.

To export the settings:

  1. Open the Kiosk Pro settings on the iPad that is correctly configured.
  2. Scroll down to the Remote Settings Control category and select Export.
  3. Select "Export to file" or "Send by email" from the navigation.

A file called "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.

Note: If there's a passcode set in these Kiosk Pro settings (near the top of the settings menu) please make sure you know what it is before following the rest of these steps. Alternately, you could delete the passcode before exporting the settings.

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 'settings.xml' and click 'Save to...' at the bottom of the file listings to save this to your computer.

After you've saved the file to your computer, you'll want to plug in your other iPad and repeat steps 1-4 of these instructions. Then, you can click 'Add File...' and select the 'settings.xml' file. You can also drag and drop from the file browser window.

Once the file is transferred to the other iPad:

  1. Open the Kiosk Pro settings on the new iPad.
  2. Scroll down to the Remote Settings Control category.
  3. Toggle Enable to On.
  4. Enter "settings.xml" into the XML File Location setting.
  5. Select Run Kiosk Presentation and your settings will update.

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>kioskproapp.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>http://www.kioskproapp.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 our Plus and Enterprise versions, you can also use Group ID's within the 'ApplyTo' statement so if you wanted 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>

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>http://www.kioskproapp.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 'kioskproapp.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>

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