Survey Control File

Survey Identification

This section explains each of the lines in the first part of the control file. Many of these field names are case-sensitive. Keep them in lower case.

Name, author and version fields

These lines are optional. The name field (as distinct from the .survey filename) is the name that will be displayed on the PIEL Survey App home screen.

name|PIEL Sample Survey

author|PIEL Administration

version|1.0

Author-email

The author-email field is the address to which a survey project will be emailed at its completion. If you do not specify an email address, the participant will need to add it manually before sending the data file. Please take care to ensure that the email is correct to avoid errors in sending the email. As mentioned previously, we highly recommend that you test the survey, including sending data files before using the survey with participants.

author-email|contact@contact.com

Subject-id

This line allows the allocation of a unique identifier to each participant’s survey and is recorded as a field in the output file. If you don't include a Subject ID, the PIEL Survey will ask for an ID when it runs the survey. You should enter a subject-id if you don't want the participant to be asked to enter an ID.

subject-id|0001

Scheduling

Please note that the default survey type is a "Run once" survey. This is described in more detail below. To create a scheduled survey, you will need to place the following line in the survey file.

can-run-once|0

This section explains how to schedule multiple runs of the survey. These fields are not needed if the survey is only to be a "run once" survey.

Max-duration

This line specifies how long the participant has to complete the survey run once they have opened it before it times out. It is marked in seconds and often set at 600 (10 minutes). This setting is optional and if not specified is set to infinity.

max-duration|600

Max-delay

This line specifies the duration of the delay between the beginning of the alert sound and when the survey is marked as expired because, in that particular survey run, it has been unopened. It is in seconds and often set at 300 (5 minutes).

max-delay|300

Run lines: Fixed and random sampling

This line specifies explicitly on which days of the week and at what times notifications are sent to prompt the completion of the survey. There may be multiple run lines per survey, allowing each day of week to be configured differently. There is an upper limit of 64 schedule notifications. Surveys can be set to run at fixed or random times during a set time interval or can be set to use a combination of both fixed and random sampling. The general format of a survey schedule line is: run|days of the week (specified by number)|time specification, time specification.

The week starts on Monday, specified as 1. Sunday is specified as 7. An asterisk (*) is used to denote “on all days", indicating that the survey should be identically scheduled on all 7 days of the week. Use a 24 hour clock (no punctuation e.g. 1230, not 12:30).

For example, to run a survey every day at 3:11pm (1511)

run|*|1511

Fixed Sampling

Specify which days and times of the week a survey should be run. If the same schedule is used on multiple days, separate the days with a comma. E.g., run on Sunday at 7:15pm, 7:20pm and 7:25pm and on Monday and Tuesday at 7pm, 7:30pm and 8pm.

run|7|1915,1920,1925

run|1,2|1900,1930,2000

Random Sampling

If multiple random alarms are desired within some time period, it is best to break up the time period into shorter chunks and schedule an alert for each of these shorter periods. This saves alerts falling on top of each other or running into each other. E.g., schedule 3 random runs on Monday between 9am and 2pm. The following example ensures the minimum time between runs is one hour. Some researchers only allocate 5 or 10 minutes between chunks of time.

run|1|0900-1000,1100-1200,1300-1400

Combined Fixed and Random Sampling

The following lines from the sample survey indicate both fixed and random sampling.

run|7|1915,1920,1925 #(fixed)

run|1|0900-1200,1500,1700-1900 #(fixed & random)

run|2,3,4|1300-1600 #(random only)

Run-for/ Number of days

This line specifies how many days the surveys run, starting from the date the survey starts. E.g., run for 7 days starting from the day the survey starts. There is effectively no limit to the number of days a survey can be programmed to run.

run-for|7

Behaviour

This section explains how to control the behaviour of the survey.

Can-run-once

This option allows the survey to be run on demand. This feature is sometimes called event contingent sampling. A value of "1" enables the "can-run-once" feature and a value of "0" disables it. The following screenshot shows a survey that has "can-run-once" selected. The green "Start" button shows this in the text "Start Run-once Survey". If "can-run-once" is disabled, the text displayed will be "Start Scheduled Survey".

Please note that if "can-run-once" is enabled, the survey can be manually started as many times as you want, but once each time. Even if a schedule is specified, a scheduled survey will not run unless this option is disabled. If "can-run-once" is disabled, the survey will be run as a scheduled survey and a schedule must be included in the file.

If no value is set, "can-run-once" is enabled by default.

can-run-once|0

can-run-once|1

Can-test/Allowing testing

Enabling this feature will allow testing of some features such as the alert sounds, max-delay, exit messages and survey questions after the control file is installed into the PIEL Survey. A value of "1" enables "can-test" and "0" disables it.

If no value is set, testing is enabled by default.

can-test|0

can-test|1

The screenshot above shows a survey with "can-test" enabled. This can be seen by the enabled "Test" button. Responses are not recorded in test mode.

When testing, an option is given to test immediately or in 5 seconds. The 5 second option is to allow time to put the app into the background and wait on the notification. The survey will start when the user taps the notification or the app icon. Please note that in versions older than iOS 10, notifications are not received when the app in the foreground.

This feature is useful for testing how well the questions and responses fit the screen visually. It is also useful to demonstrate the survey to participants before they commence the actual study

Exit messages

This is an optional line in the survey. This line specifies the text displayed on the screen following the last question (see following image). Its length is specified in seconds.

exit-message|3|Thank you for trying the PIEL Survey.

Multiple exit messages can be scheduled to show throughout the duration of a project. There will be one exit message per survey run which will be chosen randomly from the selection provided. Specify each message and its duration on a new exit-message line.

exit-message|3|Thank you for trying the PIEL Survey.

exit-message|3|Thank you for your participation

Placeholder message

This is an optional line in the survey. This line specifies the message that appears on the screen when a scheduled survey commences or if participants peek at the App in between survey runs (see following screenshot).

placeholder-message|Nothing for now, thank you for checking!

Survey alert sounds

There is a small library of alert sounds that can be used with the PIEL Survey App. If the alert-sound line is omitted, the default sound is "005" (the "robot" sound).

The following sounds are available.

Specify the alert sound via: alert-sound|x where x is the number of the sound in the library. The following example shows how to specify the robot alert sound.

alert-sound|005