Control File: Survey Information

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

This field is optional but is highly desirable to use. The name field is the name that will be displayed on the PIEL Survey App home screen.It will also be displayed prominently on the Placeholder Screen (the screen that appears in between scheduled surveys).

We suggest that you do not give the survey a name that might be regarded as sensitive or private by participants.

name|PIEL Sample Survey

Author

This field is optional but is highly desirable to use. The author field is displayed below the survey name on the home screen.

author|PIEL Administration

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 address is correct to avoid errors in sending the data file. 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

Schedule

This section explains how to schedule multiple runs of the survey.

Can-run-once

The default survey type for the PIEL Survey is a scheduled survey. However, this can be changed.

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

Max-delay

This line specifies how long the participant has to commence a survey once they receive the notification that a survey is due. It is in seconds (300 is equivalent to 5 minutes). If the survey is terminated by the expiration of the max duration, any data will be saved and the survey will finish. If more surveys are due, the PIEL Survey will show the placeholder and wait for the next survey. If you use this setting, we advise that you explain to participants that the survey will only run if it is opened before the max delay time. This setting is optional and if not specified is set to 1 year.

max-delay|300

Max-duration

This line specifies how long the participant has to complete the survey run once they have opened it. It is marked in seconds (600 is equivalent to 10 minutes). If you use this setting, we advise that you explain to participants that the survey may be cut short if they take too long to finish it. This setting is optional and if not specified is set to 1 year.

max-duration|600

Run

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 times per day and multiple run lines per survey, allowing each day of week to be configured differently. 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 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

If the same schedule is used on multiple days, separate the days with a comma. For example, to 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

Schedules can also be set for random times. If multiple randomly timed surveys are desired within a specific 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

You can also combine fixed and random schedule times. 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

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-test

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.

This setting is of most use for a scheduled survey. For a scheduled survey, tapping the test button will send a notification in 10 seconds. The 10 seconds allows 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.

We recommend that "can-test" be disabled for the actual research project.

Exit-message

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. For instance, to show the message "Thank you for trying the PIEL Survey." for 3 seconds use the following line.

exit-message|3|

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!

Alert-sound

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 the notification sound on the user's device.

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|5