Designing Surveys

Building a survey as a video

A narrated walkthrough (2:50) that continues the survey from the quickstart video: screens and element types, a multiple choice question, a screen shown only after a low mood answer, a Random Block, a validated scale from the Item Library, and the preview. It is filmed in SMAAT on the Free plan. The narration is a synthetic voice; turn on captions in the player to read along.

Recorded in October 2026. Screens in newer versions of SMAAT may differ slightly. Chapters, transcript and all video tutorials →

Survey details and actions

Above the tabs, each survey has four fields:

• Internal Title (Researcher only): the name used in the Study Builder and on the dashboard.
• Title for Participants (optional): if filled, this title is shown to participants instead of the internal title.
• Description (Researcher only): a note for the research team. Participants do not see it.
• Group Code: if filled, the survey is sent or shown only to participants with that group code. If left blank, it is sent or shown to all participants.

Next to the fields are four actions:

• Download JSON saves the survey as a JSON file, including its screens, notification schedule, sensor configuration, settings and triggers.
• Upload JSON replaces the current survey's content with a downloaded file, after a confirmation. The survey's title, description and group code are kept. The replacement is permanent once the study is saved.
• Duplicate Protocol creates a copy within the same study, titled with “(Copy)”. It is unavailable when the plan's survey limit is reached.
• Delete Protocol removes the survey after a confirmation. This cannot be undone.

Building screens and elements

The Builder tab organises a survey into screens. Each screen holds one or more elements (questions, text, images, tasks and other content). Screen tabs run along the top: click a tab to edit that screen, drag tabs to reorder them, and use + Add Screen to add one. The Screen Title field renames the current screen, and Delete Screen removes it (unavailable when only one screen is left). Participants can move forward and back between screens in the app.

The Elements panel on the left lists the element types; clicking one adds it to the current screen. The Screen Builder in the centre shows the screen's elements, which can also be added with Add Element. Click an element to open its settings, drag it to reorder, or move it to another screen with Move to screen. Most answer types have a Required question checkbox; it is not offered for Rich Text, Text, Image, Sorting, Cognitive Task and Random Block. Every element can have its own conditional logic (see Screen Settings).

Element types

The Elements panel offers 17 types:

Cognitive Task

A Cognitive Task element embeds a short performance task in the survey, for example a reaction-time, n-back, Stroop or delay-discounting task. Its settings are Task Title (shown before the task starts), Instructions for Participants (leave blank to use the built-in instructions), Task Type (a searchable list; type into “Search tasks…”), Include practice phase with feedback (hidden for tasks whose practice is part of the procedure or that have no practice), Task Parameters for the chosen task, and Data Outputs to Store: Accuracy, Median Reaction Time, RT Variability, Omissions, Commissions and Task-Specific Score.

Adding a cognitive task as a video

A narrated walkthrough (2:14) that continues the Check-in survey from the quickstart video: a Cognitive Task element on a new screen, the Task Type list searched for Reaction Time, its default settings from Deary et al. (2011), the data outputs, and a run of the task in the Preview, with practice trials and feedback, then the test trials. It is filmed in SMAAT on the Free plan. The narration is a synthetic voice; turn on captions in the player to read along.

Recorded in October 2026. Screens in newer versions of SMAAT may differ slightly. Chapters, transcript and all video tutorials →

The Task Type list offers 47 tasks. For many of them the default parameters follow a named published procedure, listed in the table below. The public task library describes every task with its outputs, recommended use and references. Tasks that use pictures (for example the AAT variants, the dot-probe, the IAT and Picture Rating) come with built-in drink pictures for piloting; for research the catalogue recommends uploading a validated picture set.

Two older task types, “1-Back Working Memory” and “Delay Discounting”, remain only in studies that already use them; new tasks cannot select them.

Approach-Avoidance Task (phone movement), Beta

In this task participants pull the phone toward themselves or push it away in response to pictures. It is marked Beta (“Confirmed on an iPhone; Android is still being checked”) and works on phones only, because it reads the phone's accelerometer; the web preview simulates the movements with buttons or the arrow keys. Participants should hold the phone with both hands, ideally standing. The result stores reaction time, response force and validity for each trial. As noted in the editor, single-session test-retest reliability is low (Zech et al., 2023), so the task suits designs with repeated sessions.

Approach-Avoidance Training (phone movement) uses the same movements for approach-avoidance bias modification (Blomberg et al., 2025): a small cross (pull) or circle (push) on each picture says which way to move. In the active condition the symbol follows the picture's category, so the trained category is always pushed away; in the sham condition each category is pulled and pushed equally often. Study groups assign participants to a condition. The training is a research tool rather than a treatment, and the bias itself is measured with the Approach-Avoidance Task (phone movement) in separate sessions.

Static Balance, Rest and Postural Tremor, Dual-Task Walking (Beta)

These three tasks record the phone's motion sensors instead of taps, on phones only. Each recording starts after a short countdown and is framed by two vibrations, because the phone may be at the waist, in a pocket or in a hand with the eyes closed; the screen stays on, and the stop button is hidden while a recording runs. In Static Balance the participant stands still for 30 s with the phone at the waist, and the result is the sway in the horizontal plane. In Rest and Postural Tremor the participant holds the phone still, first with the forearm resting on the thigh and then with the arm outstretched, 15 s per hand. In Dual-Task Walking the participant walks for 45 s with the phone in a front trouser pocket, once normally and once while counting backwards in threes; the result is the stride time and its dual-task cost, the percentage increase while counting. A recording interrupted by leaving the app is started again; a recording with a gap in the sensor data, or with the stop question opened during it, is kept but not scored. The web preview shows the screens without measuring.

Random Block (A/B)

A Random Block contains two or more arms. Each arm is a labelled group of elements, added with ＋ Add arm. When the survey is shown, the app presents one arm at random and records which arm was shown and its probability. When to draw the arm sets the design:

• Every time the survey is shown (within-subject): a new arm is drawn at each presentation.
• Once per participant, then fixed (between-subject RCT): the arm is drawn once and kept for that participant, as in a randomised controlled trial.

The Block label becomes the column name in the data. Random Blocks with the same label are linked: the participant is assigned once and sees the matching arm (by arm label) in every linked block. A Random Block cannot contain another Random Block. Activation requires at least 2 arms with at least 1 element each.

Drawing

A Drawing element asks participants to draw on the screen. Drawing type is either Line over time (analysable curve) or Free sketch. In line mode participants drag from left to right to trace a value over time, for example mood from the last survey until now. The result is a resampled series plus its mean, slope and area under the curve. Free sketch accepts any strokes on a blank or image-backed canvas and produces spatial measures rather than a curve.

Canvas shape (Wide, Balanced or Square) fixes the canvas's aspect ratio on every device, so curves from different phones are comparable. Taller canvases allow more precise values; wider ones give more room along the time axis. Further settings are Top of the scale, Bottom of the scale, Start of the time axis, End of the time axis, Reported scale minimum and Reported scale maximum (default 0 to 100; the drawing is stored on a 0 to 1 scale and the exported summary is rescaled to these values), gridlines, undo of the last stroke, and whether the curve must span the whole time axis.

AI Conversational Agent

An AI Conversational Agent element holds a short text chat between the participant and a large language model. The settings are the System Prompt (the model's instructions, persona and rules), Initial Message (Optional), Max conversation turns (1 to 50; each participant message is one turn, after which the chat is locked), AI temperature (0-1) (lower values give more consistent replies), and up to 10 Goals that the conversation should cover. The full transcript is always saved as the response. Also extract a structured summary (JSON) adds a summary with one field per goal; it is stored alongside the transcript and roughly doubles the model cost of the element.

Screen Settings: randomisation, screen order and conditional logic

The Screen Settings button opens three groups of settings for the current screen:

• Randomization Settings: Randomize question order shows the screen's elements in random order. Number of elements to randomly select shows only a random subset (between 1 and the number of elements; empty means all elements).
• Screen Order Randomization: assigns the screen to a randomisation block, or leaves it at Fixed position (not randomized). Screens in the same block appear in a random order for each participant; + Create new block… adds a block. A block needs at least two screens. A screen in a block cannot have a condition that refers to another screen in the same block, because that screen may come later.
• Conditional Logic: the screen is shown only when its conditions are met. Conditions compare an earlier answer, or the participant's assigned group (“Participant group”), with a value. Operators are Equals, Greater than, Less than, Greater than or equal, Less than or equal, Is one of, Is not one of, File is uploaded, Is after, Is before, Option is at position, Item swiped to and Item tapped to, depending on the type of the earlier question. When there are several conditions, all of them must hold.

The same conditional logic is available on each element, so a single question can be shown or hidden based on earlier answers.

Inserting validated items from the library

Insert from Library, above the Elements panel, opens the Validated Item Library. The library holds validated scales and question modules (reusable sets of items, for example core demographics), with a search field (“Search scales…”) and filters. Selecting a scale shows its details, such as scoring, source, citation and licence. All items or a selection can be inserted, and they are added as a new screen named after the scale. Cognitive tasks, AI chats and Random Blocks are not library items.

After an insert, an Instruments Used panel below the Elements list shows each inserted instrument with its version and language, which supports exact reporting of the measures. If inserted items collect special-category data under GDPR Art. 9 (for example health or ethnic origin), a notice asks for an explicit lawful basis and consent text that covers them.

Notification schedules

Notifications prompt participants to complete a survey. In the Notification Schedule tab, Add Schedule adds a schedule of one of seven types. Each schedule appears as a card with an on/off switch; click the card to open it. Every schedule has a Schedule Name, a Notification Title and a Notification Body. On the Free plan a survey can have up to 3 schedules; the Basic, Pro and Team plans have no limit.

Scheduling prompts as a video

A narrated walkthrough (3:04) that continues the Check-in survey from the quickstart video: the seven schedule types, random sampling windows with a minimum interval, availability and a reminder, a fixed evening prompt for the first week, the Participant Burden bar, and a follow-up survey sent after a high stress answer. It is filmed in SMAAT on the Free plan. Adding email and SMS is shown in the email and SMS video. The narration is a synthetic voice; turn on captions in the player to read along.

Recorded in October 2026. Screens in newer versions of SMAAT may differ slightly. Chapters, transcript and all video tutorials →

Schedule types

• Fixed Time: notifications at set times of day (Notification Times, with + Add Time; new schedules start with 09:00, 15:00 and 21:00).
• Random Sampling: notifications at random times within Sampling Windows. Each window has a start and end time, a number of notifications and a minimum interval in minutes between them (it does not space prompts from different windows); + Add Window adds a window. The default is one window from 09:00 to 21:00 with 3 notifications.
• Smart Timing: a set number of prompts per day within a window, timed per participant. At first times are drawn across the window, as in random sampling. As responses accumulate, the times at which the participant tends to respond are chosen more often. Settings are Earliest time, Latest time, Notifications per day (1 to 24), Minimum spacing (minutes) and Time granularity (30 minutes, 1 hour or 2 hours; smaller slots need more responses to learn from).
• Interval-Based: notifications at a regular interval between a Start Time and an End Time, with Interval (hours) and Max Notifications (defaults 09:00 to 21:00, every 3 hours, at most 4).
• Event-based: a notification triggered by an event, selected under Trigger Event. The Standard group contains Enrollment, Study Completion, Survey Answer Trigger (answers in a chosen survey meet set conditions) and Custom Event (an external system sends a POST request to an endpoint shown with a Payload Template (JSON); the button Test Custom Event Notification sends a test). The Prescreening-based group uses the participant's prescreening answers: Participant's Preferred Time, Wake Time, Sleep Time, Preferred Days (Week) and Calendar Event, each with an Offset (minutes) (negative values send earlier). Standard events have a Delay After Event (minutes).
• Geolocation-Based: a notification when the participant enters or leaves a location (a geofence, that is, a circular area around a point). Locations are added by clicking on the map; each has a Radius (meters) and enter/exit options. The schedule also has an Active Time Window and a delay after the event.
• Place Visit: a notification when the phone detects that the participant has stayed at a new place, without locations being defined in advance. Settings are Trigger on (Arrival only (recommended), Departure only, or Both arrival and departure), Dwell time (minutes) (default 5), Dedup radius (meters) (default 100; two stops within this radius count as the same place), Dedup cooldown (hours) (default 6), Max triggers per day (default 6), Active time window (per day) (default 08:00 to 22:00), Location sharing and Delay after arrival (minutes). Location sharing is None by default, so the response carries no location data; Coarse (~1 km grid, adjustable with Coarse grid size (meters)) or Precise attaches coordinates to the response. No background sensor needs to be enabled; the app asks for background location permission when the participant joins. On days when the participant does not move, no prompts are triggered.

Days, schedule window, availability and reminders

• Active Days: the weekdays on which a schedule runs (new schedules start with Monday to Friday). Not used by event-based schedules.
• Schedule window: the period in which a non-event schedule runs: Entire study duration, Fixed calendar dates (From date and To date) or Relative to enrollment (days) (From day, where 0 is the enrolment day, and To day, where empty means the end of the study).
• Survey Availability Duration: how long the survey remains available after the notification (default 24 hours).
• Reminders: + Add Reminder adds a reminder for participants who have not completed the survey, with a delay in minutes, hours or days.

Delivery channels

Each schedule has Delivery Channels: push notification, email and SMS (text message), in an order that the researcher sets. With more than one channel, a Delivery Strategy sends them all at once or escalates to the next channel when the prompt has not been opened or completed after a set wait. Email and SMS have optional content fields, reach only participants who verified the contact detail and enabled the channel for the study, and SMS uses prepaid credits. The details are described in Notification Channels.

Survey-time sensors

The Sensors tab records sensor data while a participant answers this survey. For continuous collection independent of surveys, use Protocol → Background Data, described in Configuring Background Data. Nine sensors are available, each with a switch and a Show Details link with example data:

The Sampling Interval (milliseconds) is the time between two readings. It defaults to 1000 ms (one reading per second) and cannot be set below 200 ms. Shorter intervals and higher location accuracy use more battery.

Survey settings: self-initiation and completion message

The survey's Settings tab contains Allow Self-Initiation. When it is checked, participants see a button for the survey on the app's home screen and can start it at any time, in addition to any scheduled prompts. This suits participant-initiated reports such as event-contingent sampling (a report each time a defined event happens) or flexible diaries. Scheduled notifications are not changed. Each self-initiated completion is recorded with its own timestamps.

• Optional Message Next to Participation Button: a short text shown beside the button.
• Participation Frequency: Allow Repeatedly or Allow Only Once.
• Optional Message After Completion: shown after the participant completes the survey, for example a completion code to enter on a recruitment platform such as Prolific.
• Display Duration for Completion Message: (only with Allow Repeatedly) how long the message is shown, in minutes, hours or days, before the participation button becomes available again.

AI Tailoring and the AI Review page

AI-tailored surveys let a large language model draft survey content for each participant from that participant's history. They are enabled per study under Study Settings → AI → AI-tailored surveys → Enable AI-tailored surveys. The button is available only when three conditions are met:

• The study uses server-side encryption, not end-to-end encryption, because the drafting service has to read responses.
• An AI provider key is set in the same panel.
• The researcher ticks the acknowledgement that responses are sent to the configured AI provider, that the study cannot use end-to-end encryption, that participants are informed through the AI disclaimer, and that the provider's data handling is governed by the researcher's own agreement with the provider (DPA, data processing agreement).

Once enabled, each survey shows an AI Tailoring tab. Checking Tailor this survey per participant with AI reveals the brief editor:

• What should the AI generate? “Tailor an AI conversation (one AI chat question)” drafts the prompt and goals of the survey's AI Conversational Agent element, which the survey must contain. “Construct tailored questions & content” builds questions and content from a set of allowed types.
• Generation brief, Tone, Constraints (optional) and Safety rules (optional).
• Personalize from: prior survey answers, recent topics mentioned, and engagement patterns (timing, completion).
• For constructed content: whether it is one tailored block or the whole survey, its position before or after the base questions, the intent (measure, intervene or both), and Question types the AI may use.
• Generate once per participant or on each occasion, and Draft after N responses (the number of responses the participant needs before a draft is made).
• Auto-approve drafts that pass all guardrails; flagged drafts still require review.

Drafts appear on the study's AI Review page (study dashboard → AI Review), with the filters Pending, Flagged, Approved and All. Each draft can be approved, edited and then approved, or rejected. Participants receive only approved drafts, whether approved on this page or automatically.

Previewing surveys

The Preview tab shows the survey in a simulated phone or tablet. Device Type switches between Phone and Tablet, and Operating System between iOS and Android. Three views are available:

• Protocol: the survey's screens as the participant sees them. Cognitive tasks run in the preview. When screen order is randomised, Reshuffle order shows another possible order.
• Messaging: the notification as it appears on each channel, under Push, Email and SMS. Under Push, Show Sample Notification simulates an arriving notification.
• Permissions: the permission screen participants see, with sections for Notifications, Message Channels (when a schedule uses email or SMS), Foreground Permissions and Background Permissions.

Next Steps

Related sections: