Remote Update of Local Files Settings

Settings

Templates

JavaScript API Documentation

Common Questions


Enable

This feature allows Kiosk Pro to update the local files on the iPad remotely by visiting a pair of .xml and .zip files hosted on your servers.

Default: Off

When Remote Update of Local Files is enabled, Kiosk Pro will check the .xml file at the URL you provide to see if it has been updated and then, if it finds a new version number, will upload any files in the associated zip file, overwriting any files with the same name currently on the iPad.


XML File Location

This setting should be set with 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/localUpdate.xml'.

This setting must point at the .xml file, which provides Kiosk Pro with the version value and the location of the .zip containing the files to be placed locally, and cannot point directly at the .zip file itself.

You can download a sample .xml file here. Save this file to your hard drive, unzip, and then open the .xml template in a simple text editor like Notepad++ (free for Windows) or Text Wrangler (free for Mac), not a word processing software like Microsoft Word, which can add extra formatting that can be problematic. This .xml file consists of a few key/value pairs:

<dict>
    <key>version</key><integer>1</integer>
    <key>zip</key><string>localContent.zip</string>
    <key>clear-previous-content</key><false/>
</dict>

Version

The version value is how Kiosk Pro determines if the .xml file has been changed. For Kiosk Pro to update, this value must be larger than the last time this feature was used. Each time you use this feature to remotely update, you must increase the number inside the <integer> tags by at least 1. The latest version number applied to a specific kiosk can also be found in the app settings just below the 'Update Period' setting. 

Version numbers do not have to be updated incrementally by 1 every time; as long as the new version number is larger than the current one, the update will be triggered.  This allows you to add additional kiosks to an existing deployment without having to set up a new set of update files to get them on the same content. 

Zip

The zip value contains the name of the zip file containing the new files to be placed on the iPad. All the new files must be placed directly in a single .zip file which should be placed in the same folder on your server as the .xml file described above. Alternately if you prefer to store the .zip in another location you can define the full url to the .zip here.

Clear Previous Content

The clear-previous-content value allows you to delete previous content from the iPad following a successful download and unzip of new content. Setting the value to true enables deletion of previous content (which may still remain in the cache of the iPad until the cache is cleared). Older content is only deleted after a successful download of the zip file. Regardless of whether this is enabled, if there are any files in the .zip with the same name as a file currently on the device, the older version of the file will be overwritten.

When zipping your files for upload, it is important to zip the files directly, rather than zipping a folder containing the files. For example, if you were trying to upload a new index.html file and a folder of images, you would select the index file and the image folder directly (either by Select All (Ctrl-A) or by pressing Ctrl while clicking each file), then right-click and ‘Send to Compressed Folder’. You would not zip the folder containing the index file and image folder.

Defining Multiple .ZIP Files

In our 6.4 update, we also added the ability to define multiple .zip files in a single .xml file, making it possible to do smaller incremental updates for large content.  Click here to download a sample .xml file.

When a update is triggered, Kiosk Pro will step over all of the items in the .xml file until it finds a version number greater than its current version number. It will then download that .zip file and either clear, or leave the existing content as instructed. After downloading and unpacking a .zip, it will check the .xml again and repeat the process, stepping through to see if there is another version number greater than its current version number.


Test XML File for Errors

Added in version 8.0

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 Update of Local Files.

If no errors are found, the message ‘XML 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.


Server Request Timeout Period

This setting allows you to configure how long Kiosk Pro should attempt a server request when remotely updating local files before timing out. This type of timeout prevents Kiosk Pro from endlessly waiting for a response from a server that is taking too long to respond. The default is 300 seconds.

This setting adds a timer that monitors the amount of time that has passed since the last instance of load activity during the request for files.  Each time an instance of load activity occurs (e.g., bytes are received from the network for a request), the timer is reset again to zero. If the timeout period is reached without any response, the request is considered to have timed out. 

If a request times out, Kiosk Pro will attempt the request again the next time the update timer is triggered.

A request can timeout for a number of reasons:

  • problems with the server - for example, the server is offline, is experiencing heavy traffic, or experiences an error when trying to access the data necessary to fulfill the request and fails to send a response.
  • problems with the device - for example, the device is attempting to contact the wrong address for the server or isn’t connected to the internet.
  • problems with the network - for example, the WiFi router is overtaxed with requests from other computers and devices or there is a firewall in place blocking access to the server.

A longer timeout period will increase the length of time Kiosk Pro will wait for a response and can increase the success rate of downloads in certain circumstances.


Current XML Version

This setting will display the current version of your .xml file based on the integer set in your .xml file

Clearing the Version Number

As of our 6.4 update, the app supports clearing the version number when ‘Remote Update of Local Files’ is toggled off and back on. This can be done manually in the app's settings menu or remotely through a remote settings control update.

No content will be cleared as a part of this reset (although you can trigger deletion of previous content through the clear-previous-content flag in your .xml).


History

This setting shows the last 50 remote setting updates with information like 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.


Troubleshooting

Make sure that the presentation is running for long enough to finish pulling down the new files.

  • The app does not apply settings or updates while in the Settings menu, which means that the kiosk presentation must be running for the update to occur. 
  • You can see when an update is downloading by toggling the Show Update Indicator setting, which enables a progress indicator on screen while the download is occurring.
  • The app checks for user interaction before applying new content and refreshing.  If you are currently interacting with the kiosk, that will delay the update until the idle timer is triggered. See Update Period above for a full description of how this works.

Make sure your files and web address are named and formatted correctly.

  • The .xml file can be named anything as long as it is correctly referenced in the web address
  • The zip file can be named anything as long as it is correctly referenced in the .xml file and ends in .zip
  • The web address requires the full url including http://  or https://  , like http://www.example.com/localVersion.xml

Make sure you have updated your version number in the .xml file. If the version number has not been updated since the last time Kiosk Pro Plus checked the file, it will not download the contents of the .zip file.

  • It is best to make a practice of first uploading the new zipped content file and then once that is complete, upload the .xml file to instruct Kiosk Pro Plus to check for new content. If Kiosk Pro Plus goes to check the .xml and the associated .zip either is not there or has not yet been updated, it will not update the content until the next time the .xml file is updated.

Make sure your .zip file is structured correctly.

  • Make sure the zipped folder contains the files directly, so zip (contains index.html, image folder), not zip (contains folder (which contains index.html, image folder))
  • If you are using a Mac, you will need to download a file zip utility that does not add an extra layer of folder structure to the .zip file.

Set your update period to 1 or 2 minutes until you have everything working, then extend it for deployment.

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