Remote Update of Local Files Settings

Supported in:

Remotely update the local files stored in Kiosk Pro's documents folder by storing a pair of .xml and .zip files on your own server.

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. If there is a new version number, it will upload the files in the associated zip file, overwriting any files with the same name currently on the iPad.

Enable

Supported in:

This toggle controls the Remote Update of Local Files feature.

Version XML File Location

Supported in:

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

Note: This setting must point at the .xml file, not 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 plain-text editor like Notepad++ (free for Windows) or BBEdit (free for Mac). Do not use a word processing software like Microsoft Word, which may add extra formatting that can break the code.

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

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 trigger. 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 is 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 of new content. Setting the value to "true" will delete all of the previous content (which may still remain in the cache of the iPad until the cache is cleared). 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. You would not zip the folder containing the index file and image folder.

How to zip files

1. Right-click on the file or folder (to select multiple files, hold down the [Ctrl] key on your keyboard - command on Mac - and click on each file you wish to zip)
2. Windows: Select "Send to" > "Compressed (zipped) folder".
3. Mac: Select "Compress untitled folder".

Defining multiple .zip files

You can define multiple .zip files in a single .xml file, making it possible to do smaller, incremental updates for large content. A sample .xml file can be downloaded here.

When an update is triggered, Kiosk Pro will go through 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 to see if there is another version number greater than its current version number.

Update Period

Supported in:

Define how often Kiosk Pro should 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. The page refresh is dependent on what is set for the Update Policy setting.

Server Request Timeout Period

Supported in:

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.

This setting adds a timer that monitors how long it's been 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

Supported in:

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

Clearing the Version Number

You can clear the version number by toggling "Remote Update of Local Files" off and on again. 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.

History

Supported in:

This setting shows the last 50 remote updates of local content with information like the file path for the .xml file, whether the update was successful and if not, the error that caused its 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 navigation. Instructions on how to retrieve this file are available here.

Test XML File for Errors

Supported in:

When this setting is selected, Kiosk Pro will check the .xml file set in the ‘Version XML File Location’ for Remote Update of Local Files. You can also test a file from within this setting by tapping "Test File" in the top navigation.

If no errors are found, the message ‘XML File is Valid’ will appear.

If the .xml file is not valid, the app stops scanning the file at the point where 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 test the file again to confirm that there are not additional errors later in the file.

Examples of errors

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 Update Indicator setting.

Check the app settings

• Double-check that Remote Update of Local Files is turned On and the URL set in Version 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 content zip and version XML file

• Make sure you've set the Version XML File Location to the same URL set in your app settings.
• Check if the file is valid using the Test Version XML for Errors setting.
• Check that the zip file is correctly referenced in the version .xml file.
• Update the version number in the version .xml file for each update. You can check the Current XML Version in the settings to see the last successful update.
• If the app is running when you make an update, make sure you upload the zip file first, then the version .xml file. Otherwise Kiosk Pro may not see the new content and won't update until the zip finishes uploading.
• The files in the zip are downloaded directly to Kiosk Pro's documents folder. If your zip has an extra folder, your content may not be referenced correctly.
• 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.