-
Notifications
You must be signed in to change notification settings - Fork 25
Campaign Definition
A campaign is a set of surveys. It is a high-level description of the overall data being collected. An example of a campaign would be a "Sleep Campaign" where someone is collecting information about users' sleep patterns. Another example would be of an "Fitness Campaign" where someone is collecting information about how frequently and/or intensely someone exercises.
A survey is a collection of survey items, which can either be a message, prompt, or repeatable set. It is a finer-grained assessment of a user regarding a specific event. In our "Sleep Campaign", an example survey could be the "Lay Down" survey that attempts to asses information about when a user laid down the night before, how long it took them to go to sleep, and/or what they did between laying down and going to sleep. In our "Fitness Campaign", an example survey could be the "Workout" survey that should be taken immediately after a workout, and would judge how long the workout took and/or what kind of exercises were performed.
A prompt is a single, specific inquiry about a user. A prompt is the finest-grained concept in the ohmage system and is used to determine a specific piece of information, the collection of which should fulfill the requirements of a survey, which, in turn, should fulfill the requirements of a campaign. Each prompt must have a specific type which defines how it is displayed to the user, what kind of data it collects, and how it is exported to be analyzed later. Example prompts from the "Lay Down" survey would be "What time do you remember laying down?" that would allow the user to input a specific time or "Select activities that you performed between laying down and going to sleep?" that would allow a user to choose between a series of predetermined activities and/or allow them to enter their own choices. Example prompts from the "Workout" survey would be "How long did the exercise last in minutes?" that would allow the user to enter a numeric value or "How did you feel after the workout?" that would allow the user to enter free-form text about their feelings after the workout. Prompts may be configured to be skippable, meaning that the user may skip the prompt and continue the survey.
A message is a brief chunk of text that is displayed to the user before a prompt. While messages can appear before other messages and/or after all prompts, it is discouraged to do so. There is a specific mechanism for displaying a message, such as a "Thank you" message, at the end of a survey and a series of messages may degrade the user experience.
A repeatable set is a collection of survey items and should be used when a series of prompts, with or without messages, may be displayed repeatedly. The last prompt in the series is the "escape" prompt which will determine if the set should be repeated again or should be terminated.
Any survey item whose condition is not met may be hidden, or "not displayed" in our terminology. Conditions are checked just before the survey item is displayed, and, if it is not satisfied, the survey item will not be displayed to the user.
A campaign is the container for the entire definition.
A campaign is defined as the following:
Name | Description | Required | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
campaignUrn | Every campaign in the system must have a unique URN, and it is best practice to name this in such a way that it can easily be traced back to the creator, for example: "urn:campaign:text:describing:author:version" | Beginning with 2.16 it is now optional when creating a campaign if the `campaign_urn` parameter is given; however, when the definition is returned, this field will be present. | ||||||||||||||||||||||||
campaignName | A name to be displayed to the user for this campaign. | Yes. | ||||||||||||||||||||||||
surveys | This is a list of surveys where each survey is defined below. For XML, each survey must be surrounded by survey tags.
|
Yes. |
A survey item can be any of the following.
Name | Description | Required |
---|---|---|
id | A unique identifier for this message. | Yes. |
messageText | The text to be displayed to the user. | Yes. |
condition | The condition which determines if the message is displayed or not. | No. |
Name | Description | Required |
---|---|---|
id | A unique identifier for the prompt. | Yes. |
displayLabel | The user-friendly name of this prompt used in visualizations. | Yes. |
promptText | The text to display to the user when prompting them to respond. | Yes. |
promptTextMarkdown | If provided this markdown will be rendered instead of the promptText. Markdown will only be parsed on 2.16.4 or later of the native android client. Only bold, italics and images are supported. If you use images, it is a good idea to test the campaign on multiple devices to make sure it is rendered correctly. Also images may look small on devices with a high dpi so using larger images is better (they will always be resized smaller so they fit in the width of the display). | No. |
promptType | One of the prompt types. | Yes. |
default | The default value for this prompt. This is type-dependent. | No. |
condition | The condition which determines if the prompt is displayed or not. | No. |
skippable | A boolean representing whether or not the prompt may be skipped. | Yes. |
skipLabel | If skippable, this is the text of the button to use to skip the label. | Yes, if 'skippable' is true. |
properties | A list of key, label, and, optionally, value duo/trios that define type-specific properties. | Yes. |
Note that this feature is not supported in the native Android app.
Name | Description | Required |
---|---|---|
id | A unique identifier for the repeatable set. | Yes. |
terminationQuestion | The text to be displayed to the user to allow them to choose to repeat the set. | Yes. |
terminationTrueLabel | The text indicating that the user does not wish to repeat the set. | Yes. |
terminationFalseLabel | The text indicating that the user does wish to repeat the set. | Yes. |
terminationSkipEnabled | This determines whether or not the skip button will be shown on the termination prompt. | Yes. |
terminationSkipLabel | The text for the termination button if it is enabled. | Yes, if 'terminationSkipEnabled' is true. |
condition | The condition which determines if the repeatable set is displayed or not. | No. |
prompts | A collection of survey items, except repeatable sets because there cannot be repeatable sets within repeatable sets. | Yes. |
Type name | Description | Output Format | Properties | Default | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
audio (only support in native ohmage) | An audio recording taken by the user at the time that the user was prompted. | A UUID that represents a distinct video clip. The video clip can be retrieve from the /app/audio/read URI. |
|
Not allowed. | ||||||||||||||||
file (2.17+) | A file attachment that is associated with survey response. | A UUID that represents a distinct file attachment. The file can be retrieve from the /app/media/read URI. |
|
Not allowed. | ||||||||||||||||
multi_choice | A multiple-choice answer from the user. | A JSONArray of keys representing the user's choices. | Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client.
|
A comma-separated list of keys where each key must be defined above. | ||||||||||||||||
multi_choice_custom | A multiple-choice answer from the user where the user may have created their own choice(s). | A JSONArray of keys representing the user's choices. | Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client.
|
A comma-separated list of keys where each key must be defined above. Because the keys for user-generated choices are random, it is not possible to make that a default choice. | ||||||||||||||||
number | A whole or decimal number. | A number value. |
|
Any number that is greater than or equal to the min and less than or equal to the max. | ||||||||||||||||
photo | A photo taken by the user, generally at the time that the user was prompted. | A UUID that represents a distinct image. The contents of this image can then be retrieve from the /app/image/read URI. |
|
Not allowed. | ||||||||||||||||
remote_activity | This is used to call Android 'Activity's of applications that have already been installed. These activities must return a JSONObject with at least one key, 'score', whose value is a double. Other key-value pairs may be returned by the remote Activity. The result of this prompt should be a, possibly empty, JSONArray of these JSONObjects, where each JSONObject represents a single external call to the remote Activity. | The JSONArray of JSONObjects as generated by the prompt. |
|
Not allowed. | ||||||||||||||||
single_choice | A single-choice answer from the user. | An integer representing the key from the user's choice. | Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client.
|
A key from the list above. | ||||||||||||||||
single_choice_custom | A single-choice answer from the user where the user may have created their own choice(s). | An integer representing the key from the user's choice. If the choice was generated by the user, the key assigned to it will be random and will correlate with a dictionary sent along with the response when queried. | Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client.
|
A key from the list above. Because the keys for user-generated choices are random, it is not possible to make that a default choice. | ||||||||||||||||
text | A free-form piece of text provided by the user. | A String. |
|
Any piece of text whose length is between the min and max value. | ||||||||||||||||
timestamp | A moment in time by a user down to the second granularity. the timestamp includes both date and time. | An ISO-8601 timestamp. | None. | Not allowed. | ||||||||||||||||
video (only support in native ohmage) | A video taken by the user at the time that the user was prompted. | A UUID that represents a distinct video clip. The video clip (mp4) can be retrieve from the /app/video/read URI. |
|
Not allowed. |
A condition is defined as follows:
Object | Definition |
---|---|
condition | expression | "(" condition ")" | condition conjunction condition |
conjunction | "and" | "or" |
expression | id operator value |
id | The ID of a prompt that is defined before this prompt in the same survey item container. |
operator | == | != | <(<) | >(>) | <=(<=) | >=(>=) |
value | Any combination of alphanumeric characters, the underscore "_" character, and the dash "-" character. |
These are elements that the server allows to be uploaded as part of a campaign XML file, but they are not used in the "official" ohmage phone or front end applications. These elements are not included in the above documentation, but you may encounter example XML files with them (e.g., in the ohmageConfiguration repository).
- campaign/serverUrl
- survey/editSummary
- survey/showSummary
- repeatableSet
- prompt/displayType
- prompt/abbreviatedText
If you are writing your own ohmage client, you may add additional elements to the XML and the server will not reject the XML.
Here is an example XML for the "Sleep Campaign":
<?xml version="1.0" encoding="UTF-8"?>
<campaign>
<campaignUrn>urn:campaign:example:Sleep:1</campaignUrn>
<campaignName>Example Sleep Campaign</campaignName>
<surveys>
<survey>
<id>LayDown</id>
<title>Lay Down Survey</title>
<description>This campaign assess when a user laid down for the night to go to bed.</description>
<introText>Welcome to the Lay Down survey!</introText>
<submitText>Thank you for taking the Lay Down survey!</submitText>
<showSummary>true</showSummary>
<summaryText>Here are the results from your survey.</summaryText>
<editSummary>false</editSummary>
<anytime>true</anytime>
<contentList>
<message>
<id>BeforePromptsMessage</id>
<messageText>This message should be the first thing you see in the survey.</messageText>
</message>
<prompt>
<id>TimeUserLaidDown</id>
<displayLabel>Time User Laid Down</displayLabel>
<displayType>event</displayType>
<promptText>Approximately, what time did you lay down last night?</promptText>
<abbreviatedText>Time Laid Down</abbreviatedText>
<promptType>timestamp</promptType>
<skippable>true</skippable>
<skipLabel>Skip</skipLabel>
</prompt>
<prompt>
<id>ActivitiesPerformedBeforeSleep</id>
<displayLabel>Activities Before Sleep</displayLabel>
<displayType>measurement</displayType>
<promptText>What activities did you perform before going to sleep?</promptText>
<abbreviatedText>Activities Before Sleep</abbreviatedText>
<promptType>multi_choice</promptType>
<skippable>true</skippable>
<skipLabel>Skip</skipLabel>
<properties>
<property>
<key>0</key>
<label>Read a book</label>
</property>
<property>
<key>1</key>
<label>Watched TV</label>
</property>
<property>
<key>2</key>
<label>Other</label>
</property>
</properties>
</prompt>
</contentList>
</survey>
</surveys>
</campaign>
Here is an example XML for the "Fitness Campaign":
<?xml version="1.0" encoding="UTF-8"?>
<campaign>
<campaignUrn>urn:campaign:example:Fitness:1</campaignUrn>
<campaignName>Example Fitness Campaign</campaignName>
<surveys>
<survey>
<id>DailyExercise</id>
<title>Daily Exercise</title>
<description>This survey measures the amount of non-workout-specific exercise the user performed throughout the day.</description>
<submitText>Keep at it!</submitText>
<showSummary>false</showSummary>
<!-- We only want the user to take this survey at the end of the day. -->
<anytime>false</anytime>
<contentList>
<prompt>
<id>NumHoursExercise</id>
<displayLabel>Number of Hours Exercising</displayLabel>
<displayType>count</displayType>
<promptText>How many hours did you spend today performing any sort of exercise (walking, running, lifting, etc.)?</promptText>
<abbreviatedText>Hours Exercising</abbreviatedText>
<promptType>number</promptType>
<default>2</default>
<skippable>false</skippable>
<properties>
<property>
<key>min</key>
<label>0</label>
</property>
<property>
<key>max</key>
<label>24</label>
</property>
</properties>
</prompt>
<message>
<id>NoExerciseMessage</id>
<messageText>You should try your best to perform some level of casual activity throughout the day.</messageText>
<condition>NumHoursExercise == 0</condition>
</message>
<prompt>
<id>WithFriends</id>
<displayLabel>With Friends</displayLabel>
<displayType>category</displayType>
<promptText>Did you do any of this exercise with friends?</promptText>
<abbreviatedText>Exercise with Friends</abbreviatedText>
<promptType>single_choice</promptType>
<condition>NumHoursExercise > 0</condition>
<skippable>true</skippable>
<skipLabel>Skip</skipLabel>
<properties>
<property>
<key>0</key>
<label>Yes</label>
</property>
<property>
<key>1</key>
<label>No</label>
</property>
</properties>
</prompt>
<prompt>
<id>WhichFriends</id>
<displayLabel>Which Friends</displayLabel>
<displayType>category</displayType>
<promptText>Which friends did you exercise with this time?</promptText>
<abbreviatedText>Exercised With</abbreviatedText>
<promptType>multi_choice_custom</promptType>
<condition>(NumHoursExercise > 0) and (WithFriends == 0)</condition>
<skippable>true</skippable>
<skipLabel>Skip</skipLabel>
<!-- There are no properties because this is a custom-choice prompt,
so the user is allowed to create their own responses which
should be retained each time this prompt is displayed. -->
</prompt>
</contentList>
</survey>
<survey>
<id>Workout</id>
<title>Intended Workout</title>
<description>This survey measures a user's explicit workout.</description>
<submitText>Great job!</submitText>
<showSummary>false</showSummary>
<!-- We want the user to take this right after a workout. -->
<anytime>true</anytime>
<contentList>
<prompt>
<id>TimeStarted</id>
<displayLabel>Time Workout Began</displayLabel>
<displayType>event</displayType>
<promptText>Approximately what time did you begin working out?</promptText>
<abbreviatedText>Time Workout Began</abbreviatedText>
<promptType>timestamp</promptType>
<skippable>false</skippable>
</prompt>
<message>
<id>ExercisesPerformedMessage</id>
<messageText>Now, add each of the exercises you performed one at a time.</messageText>
</message>
<repeatableSet>
<id>ExercisesPerformedRepeatableSet</id>
<terminationQuestion>Would you like to add another exercise?</terminationQuestion>
<terminationTrueLabel>No</terminationTrueLabel>
<terminationFalseLabel>Yes</terminationFalseLabel>
<terminationSkipEnabled>false</terminationSkipEnabled>
<prompts>
<prompt>
<id>ExercisesPerformed</id>
<displayLabel>Exercise</displayLabel>
<displayType>category</displayType>
<promptText>Select an exercise that you performed.</promptText>
<abbreviatedText>Exercise</abbreviatedText>
<promptType>single_choice_custom</promptType>
<skippable>false</skippable>
<properties>
<property>
<key>0</key>
<label>Pushups</label>
</property>
<property>
<key>1</key>
<label>Situps</label>
</property>
<property>
<key>2</key>
<label>Deadlifts</label>
</property>
<property>
<key>3</key>
<label>Curls</label>
</property>
<property>
<key>4</key>
<label>Squats</label>
</property>
<property>
<key>5</key>
<label>Jogging</label>
</property>
<property>
<key>6</key>
<label>Running</label>
</property>
<property>
<key>7</key>
<label>Aerobics</label>
</property>
<!-- Note that there is no other because this is a custom
choice prompt, so the user may enter in their own. -->
</properties>
</prompt>
<prompt>
<id>NumReps</id>
<displayLabel>Number of Repetitions</displayLabel>
<displayType>count</displayType>
<promptText>If applicable, how many repetitions did you perform?</promptText>
<abbreviatedText>Number Repetitions</abbreviatedText>
<promptType>number</promptType>
<condition>
(ExercisesPerformed != 5) and
(ExercisesPerformed != 6) and
(ExercisesPerformed != 7)
</condition>
<skippable>true</skippable>
<skipLabel>N/A</skipLabel>
<properties>
<property>
<key>min</key>
<label>1</label>
</property>
<property>
<key>max</key>
<label>1000000</label>
</property>
</properties>
</prompt>
<prompt>
<id>Distance</id>
<displayLabel>Distance</displayLabel>
<displayType>count</displayType>
<promptText>If applicable, how far did you perform this exercise?</promptText>
<abbreviatedText>Distance</abbreviatedText>
<promptType>number</promptType>
<condition>
(ExercisesPerformed != 0) and
(ExercisesPerformed != 1) and
(ExercisesPerformed != 2) and
(ExercisesPerformed != 3) and
(ExercisesPerformed != 5)
</condition>
<skippable>true</skippable>
<skipLabel>N/A</skipLabel>
<properties>
<property>
<key>min</key>
<label>0</label>
</property>
<property>
<key>max</key>
<label>1000000</label>
</property>
</properties>
</prompt>
<prompt>
<id>DistanceUnit</id>
<displayLabel>Distance Unit</displayLabel>
<displayType>metadata</displayType>
<promptText>What unit was that distance?</promptText>
<abbreviatedText>Distance Unit</abbreviatedText>
<promptType>multi_choice</promptType>
<default>0</default>
<condition>
(Distance != NOT_DISPLAYED) and
(Distance != SKIPPED)
</condition>
<skippable>false</skippable>
<properties>
<property>
<key>0</key>
<label>Feet</label>
<value>1</value>
</property>
<property>
<key>1</key>
<label>Meters</label>
<value>3.2808399</value>
</property>
<property>
<key>2</key>
<label>Kilometers</label>
<value>3280.8399</value>
</property>
<property>
<key>3</key>
<label>Miles</label>
<value>5280</value>
</property>
</properties>
</prompt>
</prompts>
</repeatableSet>
</contentList>
</survey>
</surveys>
</campaign>
There are a few special consideration which are detailed below:
- While this specification is not bound by any language or format, we currently only support XML. This means that each item in the definition must be the tag name and its value must be the value of that tag. Examples should best illustrate this.
- No two surveys or prompts may have the same identifier, even if the two prompts are part of separate surveys. This includes a prompt and survey with the same ID.
- Identifiers may contain only alphanumeric characters and underscores "_".