Documentation

Getting Started

Create a study

From the dashboard, click New Study. Give it a title and description. A unique study ID is generated automatically and cannot be changed later.

Configure protocols

Go to Settings → Protocols to set up what the app collects. Each protocol has a name, an emoji (shown next to the name on the participant's mobile dashboard), a schedule (continuous, cron-based, or triggered by sensor conditions), and one or more tasks: sensor collection, ESM questionnaires, or cognitive tasks.

Generate participant IDs

Under Settings, enable participant IDs if you want to track which participant is on which device. Click Generate IDs to create a batch. Each ID is a unique code that participants enter when joining.

Enroll devices

Share the study's QR code with participants. They scan it with the StudyRun app, enter their participant ID (if required), and the device begins collecting data immediately.

Study Settings

How a study is run

A StudyRun study is deployed as a server-hosted configuration that participant devices download and follow. The general workflow is:

• Configure: set up your study name, description, protocols, and data sync settings on this page.
• Create protocols: a protocol defines what data the app collects, when it collects it, and who it applies to. Each protocol contains one or more tasks (sensor collection, questionnaires, or cognitive tasks) and runs on a schedule (continuous or cron-based). You can have multiple protocols active at once (for example, one for continuous accelerometer collection and another for daily ESM questionnaires). Once a protocol is configured, lock it to create an immutable snapshot. Only locked protocols are sent to participant devices. Locking ensures that every sensor reading can always be traced back to the exact settings that produced it, which is essential for scientific reproducibility.
• Enroll participants: share the QR code or study URL with participants. They scan it in the StudyRun app to join. If participant IDs are enabled, each person must enter their pre-assigned ID.
• Collect: devices run the active protocols in the background, buffering data locally and uploading it to the server on the configured interval.
• Update: if you change a setting or protocol, devices pick up the change automatically on their next upload cycle. No action is needed from participants.
• Close: when recruitment is complete, disable enrollment so no new devices can join. Existing participants continue collecting until their protocols expire or you exit the study.

General

Study ID

Auto-assigned at creation and cannot be changed. Used internally to identify the study in API calls, uploads, and exports. You do not need to set this; it is shown for reference only.

Study Name

A human-readable name shown to participants in the mobile app on the dashboard and study information screen. Keep it clear and recognisable; participants will see this name every time they open the app. Example: "Sleep & Activity Study 2026".

Study Description / Ethics Information

Free-text field displayed to participants in the app after they join, under the Study Information section. This is your primary channel for informed consent and ethics disclosure. Include: study purpose, ethics committee approval number, principal investigator name and contact, data handling procedures, participant rights, and how to withdraw. Write in plain language that participants can understand.

Study Timezone

The timezone used when evaluating protocol start and end dates and when calculating Study Day / Study Week values for relative date boundaries. Set this to the timezone where your participants are located. If your study spans multiple timezones, choose the one where the majority of participants are based, or use UTC for a neutral baseline. This does not affect the timestamps stored in sensor readings, which are always in UTC.

Client Settings

Show "Your Contribution" section

Activates an optional panel in the participant app's dashboard (shown between the tasks list and the sensor list) that visualises what each participant has contributed to the study so far. It displays days enrolled, total number of ESM responses submitted, the percentage of time each sensor was switched on, today's response rate, and a six-week compliance heatmap. Everything is computed locally on the device from data the participant has already generated; enabling this option does not collect anything new. Leaving it on gives participants a sense of engagement and progress, which often improves compliance; turn it off for blinded designs where you do not want participants to see summaries of their own behaviour.

Upload Interval

How often (in seconds) the device attempts to send buffered sensor data to the server. Default: 300 (5 minutes). Lower values give you fresher data in the dashboard but increase battery and data usage. For most studies 300 s is a good balance. Use 60–120 s if near-real-time monitoring is important. Avoid values below 30 s.

Batch Size

The maximum number of sensor readings sent in a single upload request. Default: 500. Larger batches are more network-efficient but use more memory during transmission. The default works well for most studies. Only reduce this if participants report upload failures on low-memory devices.

Max Retry Attempts

How many times the device retries a failed upload before skipping that batch. Default: 5. Failed batches are retried on the next upload cycle. The default is appropriate for most conditions. Increase it only if your study area has very unreliable connectivity.

WiFi Only

When enabled, data is only uploaded when the device is on WiFi. Useful for studies collecting high-frequency sensors (e.g. audio or accelerometer at fast rates) that generate large amounts of data. Participants must connect to WiFi regularly for uploads to occur, so consider including a reminder in your participant instructions.

Deployment

QR Code

Encodes the study configuration URL. Participants open the StudyRun app, tap "Join Study", and scan this code to enrol. You can download the QR code as a PNG and include it in consent forms, emails, or printed materials. The URL can also be shared as a plain link for online recruitment.

Allow Enrollments

Controls whether new devices can join the study. Toggle this off once all participants have enrolled to prevent unexpected new enrolments. Existing participants are not affected; they continue collecting data regardless of this setting. Re-enable at any time to allow additional enrolments.

Require Participant ID

When enabled, participants must enter a pre-assigned ID during enrolment. Only IDs you have generated are accepted. This acts as a lightweight authentication mechanism, so only people you have given an ID to can join. Recommended for studies where you need to track individual participants or control exactly who enrols. When disabled, anyone with the QR code or URL can join anonymously.

Participant ID Label

The label shown to participants when they are prompted to enter their ID. Default: "Participant ID". Customise this to match the terminology used in your consent materials (for example, "Student Number", "Subject Code", or "Reference Number"). Keep it consistent with what you told participants during recruitment.

Participant IDs

Generate IDs in batches of 20. Each ID is a short unique code. Copy unclaimed IDs and distribute them to participants before they enrol. IDs marked as Claimed have been used; they cannot be reassigned or deleted. Delete unused IDs if they were distributed to participants who are no longer taking part. Generate additional batches at any time as your study grows.

Configuration JSON

The raw configuration file sent to participant devices. You can view, copy, or download it for debugging or manual deployment. In normal use you do not need to interact with this directly; the dashboard manages it for you.

Team Access

Owner

Full access to all study settings, data, and team management. Can delete the study. There is one owner per study: the person who created it. Ownership cannot be transferred.

Editor

Can modify study settings, protocols, and upload settings. Can export data and send notifications. Cannot delete the study or manage team members. Assign this role to co-investigators or research assistants who need to configure the study.

Viewer

Read-only access. Can view the dashboard, data, and settings but cannot make any changes. Suitable for supervisors, ethics reviewers, or collaborators who need visibility but should not modify the study.

Protocols

What is a protocol?

Protocols are the heart of a study. A protocol defines what the app collects, when it collects, and who it applies to. Each study can have multiple protocols running in parallel (for example, one for continuous accelerometer collection and another for daily ESM questionnaires). Each protocol must be locked before it is sent to devices. Locking creates an immutable snapshot so that every reading can be traced back to the exact settings that produced it.

Structure

Tasks

Each protocol contains one or more tasks. A task is either a sensor collection (one or more sensors to record), an ESM questionnaire (a set of questions shown to the participant), or a cognitive task (e.g. a reaction time test). You can combine multiple tasks in a single protocol so they all run on the same schedule. For cron-based sensor tasks you also set a duration: how many seconds the sensors run each time the cron fires.

Schedule

A protocol runs on one of three schedules. Continuous means it runs at all times while the protocol is active. Sensors collect data in the background continuously. Interactive tasks (ESM questionnaires, cognitive tasks) in a continuous protocol appear in the participant's dashboard as "Run at any time", meaning they are always available and reappear after completion. Cron triggers the protocol at specific times using a cron expression. You can also configure a randomness delay (jitter): the protocol does not fire exactly at the cron time but instead waits a random number of minutes within the jitter window before triggering. This delays both data collection and any associated notification, so participants cannot predict exactly when the next prompt will arrive, which reduces anticipatory behaviour and improves ecological validity in ESM studies. Triggered fires the protocol when a set of sensor rules evaluates to true — e.g. "when the participant has been stationary for 30 minutes inside the home geofence". Rules are evaluated server-side on every upload, so the trigger reacts to real-time behaviour rather than a preset clock; this is the foundation for Just-In-Time Adaptive Interventions (JITAIs).

Cron expression syntax

A cron expression has five space-separated fields: minute hour day-of-month month day-of-week

*: every value

,: list  e.g. 9,13,21

-: range  e.g. 1-5

/: step  e.g. */2

Common examples

Triggered rules

A Triggered protocol fires when a rule tree built from sensor predicates evaluates to true. Rules combine individual conditions (e.g. "activity is WALKING", "heart rate exceeds 120", "device is inside a 100 m geofence") with AND / OR / NOT operators and nested groups. Each condition picks a sensor, a field, an aggregation (latest, count, average, changed, any, inside/outside, etc.) and, where applicable, a time window (current upload, last N minutes, today, this week, since enrollment). The server re-evaluates the rule every time the device uploads sensor data, so the end-to-end latency from "condition met" to "task on the participant's dashboard" is one upload cycle (typically under a minute).

Triggered protocols also carry a cooldown (minimum minutes between firings per device), a max firings cap (per device, over the life of the study), a duration (how long the triggered task remains actionable), and an optional jitter delay. They support the same notification options as cron protocols, including High Priority.

Rules referencing a sensor that no other active protocol is collecting are flagged at lock time (but still allowed, in case you plan to enable collection later). Platform-specific sensors (e.g. App Usage / Screen on Android, HealthKit on iOS) are badged with 🤖 or 🍏 in the rule builder.

Notifications

Cron-based and triggered protocols can show a notification to the participant when the protocol fires. Configure a title and message at the protocol level. The notification fires at the same moment the tasks become available (including any jitter delay), so participants always receive the notification and the data collection burst at the same time.

High Priority notification

When enabled, the scheduled notification is delivered at the OS's time-sensitive urgency tier: iOS UNNotificationInterruptionLevel.timeSensitive (pierces Focus and Do Not Disturb), Android IMPORTANCE_HIGH channel with CATEGORY_REMINDER (heads-up popover, bypasses "Priority only" DND). Leave it off and the notification is posted at default urgency, which may be silenced by the participant's Focus, sleep schedule, or Do Not Disturb settings.

Turn this on for momentary ESM prompts that expire quickly, safety check-ins, or any questionnaire where a missed response is worse than interrupting the participant. Leave it off for routine sampling protocols where the participant can reasonably reply later. High Priority notifications consume the user's attention budget, and overuse trains participants to silence the app entirely.

See Send Notifications → High Priority notifications in the docs for the full platform-by-platform behaviour table and the OS-level overrides participants can apply.

Scheduling options

Start and end dates

Optionally set a start date and end date for a protocol. Dates can be absolute (a fixed calendar date) or relative (e.g. 7 days after the participant enrolled). Relative dates are evaluated per participant, so each person gets the same study timeline regardless of when they joined. Before the start date the protocol is inactive; after the end date it stops automatically. Leave both blank to run indefinitely. This is ideal for phased studies, for example a baseline week of passive sensing followed by an intervention week with ESM prompts.

Participant filter

By default a protocol applies to all enrolled participants. Use the participant filter to restrict it to specific participant IDs. This lets you run different protocols for different groups, for example a control group with passive sensing only and a treatment group with additional ESM prompts.

How protocols reach devices

Which protocols are sent?

When a device checks in, the server evaluates all protocols and sends only those that are locked, enabled, within their date range, and pass the participant filter for that device. Unlocked (draft) protocols, disabled protocols, expired protocols, and protocols filtered to other participants are never sent.

Protocol order and sensor priority

The order of protocols matters. If two protocols are active at the same time and both collect the same sensor, the settings of the first protocol (highest in the list) take precedence for the duration of the overlap. Reorder your protocols to ensure the desired configuration wins when schedules clash.

Staying in sync

Devices check for updated configurations every time they upload data, typically every few minutes. If you change a protocol (adjust a sampling rate, add a sensor, or update a cron schedule), enrolled devices will pick up the change on their next upload cycle. No action is needed from participants.

Sensors

Collection modes

Interval

Polls the sensor at a fixed rate (e.g. every 100 ms). Configure the sampling rate to balance data resolution vs. battery use.

Event-driven

Only records when a change exceeds the threshold (e.g. acceleration changes by more than 0.5 m/s²). More battery-efficient for slow-changing signals.

✓ Available  ·  Foreground Only while app is on screen  ·  — Not available  ·  Privacy-sensitive Requires clear justification in your IRB application

Motion & Orientation

Environment

Location & Connectivity

Device & System

User Behaviour

Health & Wearable

Personal Data

ESM & Tasks

Experience Sampling Method (ESM)

ESM questionnaires let you prompt participants with surveys at scheduled times. Add an ESM task to any protocol with a cron schedule (e.g. 0 9,13,21 * * * for 9 AM, 1 PM, and 9 PM daily). When the protocol triggers, the participant has a configurable time window to respond before the questionnaire expires. Notifications are configured on the protocol, not on the ESM task itself.

Question types

Questionnaire settings

Title

Shown at the top of the questionnaire on the participant's device.

Instructions

Optional text shown to the participant before the questions begin.

Required

Per-question toggle. Required questions must be answered before the participant can submit.

Collected data: ESM

Each submitted questionnaire produces one record with the following fields.

Cognitive tasks

Data & Export

Accessing your study data

StudyRun gives you real-time access to everything your participants have collected. The Data tab lets you preview live readings as they arrive. The Visualisation tab shows coverage heatmaps so you can spot collection gaps instantly. The Export tab lets you download the full dataset in your preferred format for analysis. All timestamps are stored in UTC; no timezone conversion is applied before export.

Viewing data

Data tab

A live, scrollable table of sensor readings. Filter by sensor type, device, participant ID, or time range. Useful for spot-checking data quality during the study (for example, verifying that a newly enrolled participant is successfully uploading, or confirming a specific sensor is recording correctly). Each row shows the timestamp (UTC), sensor type, device ID, participant ID, and the sensor-specific data payload.

Virtual sensor types

The sensor-type filter also includes a couple of virtual entries that don't come from participant devices. HEARTBEAT exposes device-heartbeat events from the dedicated heartbeats table, so you can confirm when each device checked in regardless of whether any sensor was active. PROTOCOL_TRIGGER appears only in studies that have at least one JITAI (triggered) protocol with recorded firings; each row is one moment when a trigger rule evaluated TRUE for a device and the cooldown / max-firings gates allowed the protocol to run. The data.eval_context column holds a JSON snapshot of the rule-tree evaluation — which leaves matched and with what sensor values — useful for verifying trigger cadence and debugging rules after the fact.

Visualisation tab

Charts and heatmaps built from your collected data. The Sensor Completeness heatmap shows, per participant, which sensors have reported data over time, helping you identify individuals or sensors with collection gaps. The Client Connectivity heatmap shows device heartbeat activity over time: a green cell means the device checked in during that period, red means no heartbeats were received. Use this to distinguish a participant who simply has not uploaded yet from one whose app has stopped running.

Exporting

CSV

One row per sensor reading, with the sensor-specific data fields flattened into separate columns. Easiest to open in Excel or import into R and SPSS. Nested fields (e.g. accelerometer x, y, z) become separate columns. Best for smaller datasets or when you need a quick look at the data.

JSON

Each reading is a JSON object preserving the full nested data structure exactly as it was stored. Best for programmatic processing in Python or JavaScript where you want the complete payload without flattening decisions. Delivered as a gzip-compressed .json.gz file (roughly 10x smaller than raw JSON): pandas.read_json() reads it directly, or use gzip.open() in Python / zcat on the command line. Decompress it first if you want to open it in a text editor.

Parquet

Columnar binary format. Highly compressed and fast to read with pandas, Spark, or DuckDB. The best choice for large datasets (millions of readings). Parquet preserves type information (timestamps, integers, floats) without string conversion.

Applying filters

Before exporting, apply any combination of filters: date range, sensor types, specific devices, or specific participants. Only data matching all active filters is included. This lets you export a single sensor across all participants, or everything collected for a specific participant, without downloading the full dataset.

Chunked downloads

Clicking Prepare download splits your export into date-range files (UTC day-aligned, roughly 2.5 million readings each), so a months-long high-frequency study arrives as a series of modest, reliably-downloadable files instead of one enormous one. The chunks tile the full time range with no gaps and no overlaps: downloading every chunk gives you exactly the complete dataset, and each file name carries its date range so a folder of chunks stays sortable. Use Download all to fetch them one after another; if a download fails or your laptop sleeps, re-download just that chunk.

Download size

There is no size limit on exports. Files are streamed directly to your browser as native downloads (with a normal browser progress bar); the server does not buffer the entire file in memory, and neither does the browser. Row counts and sizes shown in the download planner are estimates; the actual files are compressed and typically smaller. For very large datasets, Parquet compresses significantly better than CSV.

Data schema

timestamp

Unix timestamp in milliseconds, UTC. All sensor readings from all devices share the same reference. When comparing readings across devices or merging with other datasets, no timezone conversion is required; all values are already in UTC.

sensor_type

String identifier for the sensor, for example ACCELEROMETER, LOCATION, HEART_RATE, or BATTERY. Matches the sensor names shown in the Sensors reference tab, which also lists all sensor-specific fields in the data object.

device_id

Unique identifier for the physical device. Stable for the lifetime of a study enrolment. If a participant re-enrolls on the same phone (e.g. after re-installing the app), they receive a new device ID. Multiple devices can share the same participant ID if a person has enrolled on more than one device.

participant_id

The participant identifier provided at enrolment. Maps directly to the ID you distributed during recruitment. If participant IDs are not required by your study, this is an auto-generated anonymous ID assigned at enrolment.

batch_id

Unique identifier for the upload batch this reading arrived in. Used internally for deduplication: if a device retries a failed upload, the server recognises the batch ID and discards the duplicate without storing it twice. You do not need to do anything with this field in your analysis.

protocol_id

The ID of the locked protocol that was active when this reading was collected. Because protocols are versioned snapshots, this field lets you trace every reading back to the exact sensor configuration, schedule, and participant filter that was in effect at collection time.

data

A JSON object containing all sensor-specific fields for this reading. For example, an accelerometer reading's data object contains x, y, z (in m/s²). See the Sensors tab for the complete field definitions for each sensor type. In CSV exports this object is flattened into individual columns.

Understanding gaps in your data

Short gaps (minutes)

Normal and expected. Gaps of a few seconds to a few minutes occur when the device restarts, switches between WiFi and mobile data, or the OS temporarily suspends the app. Data is cached on the device and uploaded as soon as connectivity resumes; no readings are lost.

Longer gaps (hours)

Usually indicate the app was force-closed by the participant or killed by the OS battery manager. Check the Client Connectivity heatmap to see the last heartbeat time for the affected device. If the device shows no heartbeats for an extended period, the app is likely not running. See the Troubleshooting section for steps to fix this.

Sensor-specific gaps

If only one sensor has gaps while others look normal, the most likely cause is a denied permission or an iOS foreground-only sensor (such as the accelerometer or microphone) recording gaps when the app is in the background. Check the Sensors tab to see which sensors are foreground-only on iOS.

Missing participants

If a participant appears in the Sensor Completeness chart but has no data for several sensors, they may not have granted the required permissions. Share the Participant Guide with them and ask them to check their app permissions in phone settings.

Send Notifications

Reaching participants outside the schedule

The Send Notifications panel lets you push an ad-hoc message to participant devices at any time, independent of the protocol cron schedule. Use it for study reminders, schedule changes, announcements, or whenever you need to reach participants outside their normal collection routine. Notifications are delivered through the app's own upload channel: no third-party push services (APNs or FCM) are involved, and no separate push infrastructure is required.

Composing a notification

Title

The headline of the notification, shown in the OS notification tray and inside the app. Defaults to "StudyRun". Customise it to give participants context at a glance (for example "Study Reminder" or your study's name). Keep it short: mobile operating systems truncate long titles.

Message

The body text of the notification. Participants see this both in the OS notification and inside the app's notification history. Be concise; most people read notifications as a one-line summary. For ESM reminders, include a clear call to action. For schedule changes, be specific about what has changed and when.

Target: All devices

Broadcasts to every currently enrolled device in the study. Use for study-wide announcements, general reminders, or messages that apply to all participants equally.

Target: Specific devices

Select individual device IDs from the list. The table shows each device's participant ID and the time of its last heartbeat, so you can identify the right device even without knowing the device ID in advance. Use this when you need to reach a specific device (for example, to follow up on a connectivity issue).

Target: Specific participants

Select by participant ID. All devices belonging to that participant receive the message. Use this when you want to reach a participant regardless of how many devices they have enrolled (for example, a participant who is enrolled on both a phone and a tablet).

High Priority notifications

The High Priority notification checkbox, available both when composing an ad-hoc notification here and when configuring a CRON-scheduled protocol, asks the operating system to treat the alert as time-sensitive. The effect differs by platform: iOS and Android expose different levels of "urgent" notifications, and the app maps High Priority to the most prominent tier each OS permits without requiring elevated entitlements.

Use it sparingly. High Priority notifications bypass some of the system-level quieting that participants rely on (Focus modes on iOS, "Priority only" Do Not Disturb on Android). Overuse erodes the signal; participants quickly learn to ignore or silence the app. Reserve High Priority for notifications that are genuinely time-critical: a momentary ESM that expires in minutes, a safety check-in, or a schedule change the participant must act on immediately.

Participants can always override these defaults from the OS. On iOS they can disable Time Sensitive notifications for the StudyRun app in Settings → Notifications. On Android they can lower the importance of the high-priority channel or block the app entirely in System Settings → Apps → Notifications. Respect these overrides: a participant who has silenced the app is telling you something, and repeated High Priority attempts will not reach them.

How delivery works

Delivery model

When you send a notification, it is queued on the server. Each device downloads pending notifications the next time it uploads sensor data, typically every few minutes on the default upload interval. This means delivery does not require an always-on network connection from the server side and works even on networks that block push notification services.

Sent

The device has downloaded the notification from the server. The message has reached the device and is stored locally. This status updates as soon as the device's next upload cycle completes.

Confirmed

The device has shown the OS notification to the participant. The participant's phone has displayed the alert in the notification tray. A notification can be Sent but not yet Confirmed if the device received it but the OS has not displayed it (e.g. Do Not Disturb is active).

Delivery timing

On the default upload interval of 5 minutes, most devices receive the notification within 5–10 minutes of sending. Devices with WiFi-only upload enabled may take longer if the participant is not connected to WiFi. Devices that are offline or not running the app will receive the notification as soon as they come back online and complete an upload.

Tracking delivery

History table

Every notification you send is recorded permanently with the time it was sent, the target audience, and overall Sent and Confirmed counters. The history persists for the life of the study, so you can always go back and verify that a particular message was sent and when.

Per-device breakdown

Click any row in the history table to expand it and see the per-device status: device ID, participant ID, the exact time the notification was sent to that device, and the time the device confirmed receipt. Use this to identify which specific devices have not yet received a message.

Status badges

Complete means all targeted devices have confirmed receipt. Pending means one or more devices are still outstanding, either waiting to complete an upload or because the OS has not yet displayed the notification. Partially delivered means some devices confirmed while others remain pending.

Permissions

Who can send

Only study owners and editors can compose and send notifications. Viewers can see the notification history and delivery counters but cannot send new messages. This prevents accidental notifications from team members who should have read-only access.

Examples

Security & Privacy

Designed for sensitive research data

StudyRun is built for academic research involving personal and sensitive participant data. All communication is encrypted, all credentials are hashed and never stored in plain text, and your data never passes through third-party services. On paid subscription servers, each deployment runs on its own EC2 virtual machine instance with its own EBS storage volumes in the AWS region you choose; your Study Data is logically isolated from every other customer's within the StudyRun application and database. The underlying AWS physical infrastructure operates under AWS's standard shared-tenancy model with hypervisor-level isolation between AWS tenants; AWS Dedicated Host or Dedicated Instance tenancy is available as a paid add-on on request. The shared demo environment is multi-tenant and is intended only for evaluation and testing, not for real-participant data collection.

Data in transit

Transport encryption

All traffic between participant devices and the server is encrypted with TLS 1.2/1.3, enforced by Caddy (the TLS-terminating reverse proxy in each deployment). The server does not accept plain HTTP connections. Weak cipher suites (NULL, MD5, RC4, export-grade) are disabled. The mobile app validates the server's TLS certificate before transmitting any data; a misconfigured or self-signed certificate will cause the app to refuse to connect.

No third-party intermediaries

Sensor data travels directly from participants' phones to your server. There are no analytics platforms, cloud relay services, or external APIs in the data path. You control the server, the database, and the entire network path. This makes it straightforward to document the data flow for ethics committee review.

Authentication

Researcher passwords

Account passwords are hashed with bcrypt, a slow key derivation function designed to resist brute-force attacks even if the database is compromised. Plain-text passwords are never stored or logged anywhere in the system.

JWT sessions

Researcher sessions use short-lived JWT access tokens (60 minutes) paired with longer refresh tokens (7 days). Tokens are signed with a server-side secret. An expired or tampered token is always rejected. This means a stolen session token has a limited window of usefulness.

Device tokens

Each enrolled device receives a unique 32-byte cryptographically random token (prefixed with dt_). The raw token is shown to the device once during enrollment and never stored again. The server stores only a SHA-256 hash of the token. On every upload, the device sends the raw token; the server hashes it and compares. Even if someone reads the database, they cannot extract device tokens.

Token binding

A device token is bound to a specific device ID and study ID at enrollment. On every upload, the server verifies that the token, device ID, and study ID all match. If an attacker obtains a valid token but uses a different device ID, the upload is rejected. This prevents token reuse across devices or studies.

Brute-force protection

All sensitive endpoints are rate-limited per source IP. Login: 5 attempts per minute. Registration: 3 per minute. Enrollment: 5 per minute. Uploads: 60 per minute. Configuration fetches: 30 per minute. Exceeding any limit returns a 429 response. This makes credential guessing and enrollment ID enumeration impractical.

Participant data integrity

Upload deduplication

Every upload batch has a unique batch ID. If a device retries after a network timeout, the server recognises the batch ID and discards the duplicate, so readings are never counted twice. This makes upload retries safe without requiring coordination from the device.

Payload checksums

Devices compute a SHA-256 checksum over their reading payload (count + sorted timestamps) and include it in every upload. The server independently recomputes the hash. If they diverge, the server logs a warning flagging possible data corruption in transit. This provides an early-warning signal for infrastructure issues.

Configuration integrity

Devices hash their current configuration on every upload. The server computes the expected hash based on the current locked protocols, participant filter, and date boundaries. If the hashes differ, the server tells the device to re-fetch its configuration, ensuring every device always runs the latest approved settings without the participant needing to take any action.

Complete audit trail

Every sensor reading is stored with its study ID, device ID, participant ID, sensor type, timestamp, batch ID, and the locked protocol version that was active at collection time. You can always trace any reading back to the exact device, participant, and protocol configuration that produced it, which is a requirement for scientific reproducibility and ethics compliance.

Access control

Role-based permissions

Studies have three roles. Owner has full control, and can delete the study, manage team members, and change any setting. Editor can modify settings, protocols, and export data, but cannot delete the study or manage the team. Viewer has read-only access and can view the dashboard, data, and settings but cannot make changes. Assign Viewer to supervisors, ethics reviewers, or collaborators who need visibility without the ability to interfere.

Enrollment control

You can disable enrollment at any time from Study Settings to prevent new devices from joining while existing participants continue collecting. When participant IDs are required, only devices presenting a valid, pre-generated, unclaimed ID can enroll. IDs are claimed atomically at the database level to prevent two devices claiming the same ID simultaneously.

Team invitations

Team members are invited by email. Each invitation generates a single-use code that expires after 7 days. The code is consumed on first use and cannot be reused. Expired or already-used codes are rejected. This prevents invite links from being forwarded or reused after the intended recipient has joined.

Operational security

Secrets management

Database credentials and signing secrets are stored as Docker secrets: file-based, mounted on tmpfs in RAM inside containers, never written to disk. Secrets are not passed as environment variables, so they do not appear in process listings, docker inspect output, or crash logs.

Automated backups

The server runs daily database backups using pg_dump in compressed custom format (-Fc). The last 7 daily backups are retained automatically; older backups are deleted.

Input validation

All API inputs are validated with strict constraints before processing. Upload batches are capped at 10,000 readings per request. IDs are capped at 200 characters. Notification target lists at 1,000 entries. String fields have maximum lengths enforced. Oversized or malformed payloads are rejected immediately with a 400 response.

Protocol versioning

Locking a protocol creates an immutable snapshot with a unique version ID. Researchers must explicitly unlock a protocol to make changes, creating a clear before/after boundary in the data. Unlocked (draft) protocols are never sent to devices; participants only ever run reviewed and approved configurations.

Participant Guide

Welcome to the study

StudyRun is a research app that collects sensor data from your phone while you go about your daily life. Once you join a study, the app runs quietly in the background. You don't need to open it for data to be collected. This guide explains how to get set up, what the app needs to work properly, and what to do day-to-day.

• Install and join: download the app, scan the QR code your researcher gave you, and you are enrolled in a few taps.
• Grant permissions: the app will ask for access to the sensors your study uses. Granting them is essential for the data to be complete.
• Keep the app installed: the most important thing you can do is not force-close or uninstall the app. It handles everything automatically.
• Respond to prompts: if your study includes questionnaires, tap the notification when it arrives and fill it in within the time window shown.

Getting started

Install the app

Download StudyRun from the App Store (iPhone) or Google Play (Android). The app requires iOS 16 or later, or Android 8.0 (API level 26) or later. Search for StudyRun or use the link your researcher provided. Installation is free.

Join a study

Your researcher will give you a QR code or a URL link. Open the StudyRun app, tap Join Study, then either tap Scan QR Code and point your camera at the code, or paste the URL into the text field and tap Join. The app will download the study configuration and you will be enrolled within a few seconds.

Participant ID

Some studies require a participant ID to control who can join. Your researcher will give you a code. Type it exactly as given, including any hyphens or capital letters (it is case-sensitive), then tap Join. If the ID is not accepted, double-check for spaces or typos and try again. If it still fails, contact your researcher, who may need to generate a new code for you.

What happens after joining

The app begins collecting data immediately according to your study's schedule. You will see a dashboard with the study name, a list of active sensors and their current status, and a count of readings waiting to be uploaded. You do not need to do anything; data is collected and uploaded automatically in the background.

Granting permissions

When the app starts a new sensor it will show a system dialog asking for permission. Always tap Allow. If you deny a permission, that sensor records nothing and your study data will be incomplete. If you accidentally denied a permission, you can re-grant it in your phone's Settings app at any time. The instructions below show exactly where to find each setting.

Location (iPhone)

Location must be set to Always to allow collection when the app is in the background (which is most of the time). If you only granted While Using, go to Settings > Privacy & Security > Location Services > StudyRun and change the setting to Always. Without Always permission, location readings will be missing whenever your phone screen is off.

Location (Android)

When the location dialog appears, tap Allow all the time. If you previously tapped Allow only while using the app, go to Settings > Apps > StudyRun > Permissions > Location and change it to Allow all the time. On some Android versions this option only appears in Settings, not in the in-app dialog.

Bluetooth / Nearby devices

If your study scans for nearby Bluetooth devices, grant Bluetooth access when prompted. On Android 12 and later this permission is called Nearby devices. This permission only scans for devices; it does not pair with anything or access your existing Bluetooth connections.

Microphone

Some studies measure ambient sound levels to estimate noise exposure. If asked for microphone access, tap Allow. The app records only the sound level in decibels; it does not record audio, capture conversations, or store any sound content. Think of it as a loudness meter, not a recorder.

Health data (iPhone)

If the study reads Apple Health data (steps, heart rate, sleep, etc.), a Health access screen will appear listing the specific data types requested. Toggle on everything in the list and tap Allow All, then Done. You can adjust these at any time in Settings > Health > Data Access & Devices > StudyRun.

Health data (Android)

If the study uses Health Connect, the app will open the Health Connect app (install it from Google Play first if needed). Tap Allow for each data type listed. You can review and change these permissions later by opening Health Connect > App permissions > StudyRun.

Physical activity (Android)

Required on Android 10 and later for step counting and activity recognition. Grant this permission when prompted. Without it, step counter and activity sensors will not record any data.

Keeping the app running

The most common reason for missing data is the app being stopped by the battery manager or by the participant force-closing it. Follow the steps below to make sure StudyRun can run continuously in the background.

Don't force-close the app

Do not swipe StudyRun away from your recent apps list to close it. On Android this stops the background service immediately. On iOS it suspends collection. The app does not need to be visible on screen to collect data; just leave it installed and running. If you accidentally close it, simply open it again and it will resume.

Battery optimization (Android)

Android phones from most manufacturers (Samsung, Xiaomi, OnePlus, Huawei, Oppo, Realme) aggressively limit background apps to save battery. You must disable this for StudyRun: go to Settings > Apps > StudyRun > Battery and set it to Unrestricted or No restrictions. On Samsung devices, also open Device Care > Battery > Background usage limits and make sure StudyRun is not listed under Sleeping or Deep sleeping apps. This is a one-time setup.

Background App Refresh (iPhone)

Go to Settings > General > Background App Refresh and make sure it is turned On both globally and for StudyRun specifically. Also check that Low Power Mode is not active (Settings > Battery); when Low Power Mode is on, iOS suspends background apps including StudyRun, which will cause gaps in your data.

Foreground notification (Android)

While StudyRun is running, you will see a small persistent notification in your notification tray. This is normal and required; it is how Android allows apps to run reliably in the background. Do not dismiss it. If this notification disappears, the service has been stopped and you should open the app to restart it.

If the app seems stopped

On iPhone: open the app briefly to resume background collection. On Android: open the app and check the dashboard. If sensors show as inactive, tap the sensor toggle to restart collection. If problems persist, try restarting your phone and opening StudyRun again. Contact your researcher if the issue continues.

Day-to-day use

Reading your dashboard

Open the app at any time to see the study dashboard. It shows the study name, pending tasks at the top, and the list of active sensors with status indicators below. Everything scrolls together as one list.

Tasks waiting for you

When a scheduled task fires (a questionnaire, photo diary, PVT test, etc.), it appears in the 'Tasks Waiting for You' section at the top of your dashboard. Each card shows the protocol name and how much time you have left to complete it. Tap a card to start the task. If a protocol has multiple tasks, they are presented one after another; complete each one before the next appears. Once all tasks in a session are done, the card disappears. If you do not complete a task before its time runs out, it expires and is removed automatically.

Always-available tasks

Some tasks may show 'Run at any time' instead of a countdown. These are always available and can be completed whenever you want. After you finish them, they will reappear so you can do them again later.

Responding to notifications

You will receive a notification when a new task is ready. Tap the notification to open the app, and the task will be visible in your dashboard. You do not need to respond immediately; the task stays in your dashboard until its time window expires.

Uploading data manually

Data uploads automatically every few minutes when you are connected to the internet. If your study uses WiFi-only upload, data only uploads when you are on WiFi, so make sure you connect to WiFi at least once a day. You can also force an immediate upload at any time by tapping Upload data now on the dashboard.

Pausing a sensor

If a specific sensor is causing problems (for example, high battery drain from GPS), you can pause it from the dashboard by tapping the toggle switch next to its name. This stops that one sensor without affecting the rest of the study. Let your researcher know so they are aware of the gap in data. You can re-enable it at any time.

Checking your upload status

The dashboard shows Pending readings: the number of sensor readings stored on your device that have not yet been uploaded. Under normal conditions this number stays low (under a few hundred). A very large number over several days suggests uploads are not happening; check your internet connection.

Privacy and leaving the study

Your data and privacy

Your data travels directly from your phone to your researcher's private server over an encrypted connection. No third-party companies or cloud services see your data. The researcher has configured exactly which sensors are active, and you can see the full list on your dashboard. For details on what data is collected and how it will be used, refer to the informed consent form your researcher provided.

Leave the study

You may leave the study at any time without giving a reason. Open the app, expand the Study Information section on the dashboard, and tap Exit Study. The app will upload any remaining data that has not yet been sent, then permanently delete all study data from your device. This cannot be undone.

Uninstalling the app

If you uninstall StudyRun, any data that has not yet been uploaded will be lost and cannot be recovered. Before uninstalling, open the app and tap Upload data now to ensure everything has been sent, then follow the Leave the study steps above. Once you have left the study and confirmed the upload, it is safe to uninstall.

Troubleshooting

Diagnosing problems

Most issues fall into one of three categories: the device is not uploading, a sensor is not collecting data, or the data looks incomplete or wrong. Start by checking the Client Connectivity heatmap to see when a device last checked in, and the Sensor Completeness heatmap to identify which sensors have gaps. These two views will usually tell you whether the issue is with the app running at all, or with a specific sensor.

Device not uploading

Check the app is running

On Android, the app runs as a foreground service with a persistent notification in the notification tray. If that notification has disappeared, the service has been killed; open the app to restart it. On iOS, open the app briefly; this resumes background collection. If the app crashes on launch, ask the participant to reinstall it.

Battery optimization (Android)

The single most common cause of missing data on Android. Manufacturers (Samsung, Xiaomi, Huawei, OnePlus, Oppo) aggressively kill background services to save battery. To fix: go to Settings → Apps → StudyRun → Battery and set it to Unrestricted. On Samsung devices, also open Device Care → Battery → Background usage limits and ensure StudyRun is not in the list of sleeping apps. These steps must be done once per device.

Background App Refresh (iOS)

Go to Settings → General → Background App Refresh and verify that it is enabled globally and specifically for StudyRun. If it is disabled, iOS will suspend the app before it can complete an upload. Also check that Low Power Mode is not active, because Low Power Mode disables Background App Refresh system-wide.

WiFi-only upload

If the study has WiFi Only upload enabled, the device will not upload while on mobile data. This is intentional for studies with large data volumes, but participants must connect to WiFi regularly. If upload gaps correlate with times the participant is away from home, consider disabling WiFi Only in the study's Data Sync Settings.

Device storage full

If the device's storage is nearly full, the app may fail to write new readings to the local database or fail to read the database during upload. Ask the participant to free up space. The app will resume normal operation automatically once storage is available.

Sensor not collecting

Permission denied

The most common cause of a sensor with zero readings. The participant must grant the required OS permission. Check: Location (must be set to Always, not just While Using, for background collection), Bluetooth / Nearby Devices (Android 12+), Microphone, Camera, HealthKit (iOS) and Health Connect (Android). Refer the participant to the Participant Guide for step-by-step instructions for each permission.

iOS foreground-only sensors

Several sensors on iOS only collect while the app is in the foreground: Accelerometer, Gyroscope, Magnetometer, Linear Accelerometer, and Microphone. These will show gaps whenever the app is in the background, which is most of the time for a typical participant. This is a hard iOS platform limitation and cannot be worked around. If continuous accelerometer data is required, Android devices are required.

Sensor not in any active protocol

Confirm in the Configure tab that the sensor is included in at least one protocol that is locked, enabled, within its date range, and whose participant filter includes the target participant. Draft (unlocked) protocols are never sent to devices; a protocol must be locked for devices to see it.

Protocol date range

If the protocol has a relative or absolute start or end date, confirm the participant is within the active window. Relative dates (e.g. Study Day 1–7) are evaluated from each participant's individual enrolment date. A participant who enrolled late may not be in range yet, or may have already passed the end date.

Data looks wrong or incomplete

Short gaps are normal

Gaps of a few seconds to a few minutes are expected during device restarts, network transitions (WiFi to mobile), or brief OS suspensions. Data is cached locally on the device and uploaded automatically when connectivity resumes. These short gaps do not represent lost data.

Long gaps (hours)

Gaps of several hours almost always mean the app was force-closed by the participant, killed by the OS battery manager, or the device was offline for an extended period. Check the Client Connectivity heatmap for the affected device; the heartbeat pattern will show exactly when the device was last active and when it came back online. As an additional diagnostic, the app emits a GAP_DETECTED marker whenever it wakes up and finds that more than one hour has passed since its last activity. These markers appear in the SETTINGS data stream with sensor=GAP_DETECTED and an action payload of {"gap_ms":..., "last_alive_ms":...}, giving the exact duration of the dormant period and the timestamp immediately before it. Filter the Data tab to sensor_type=SETTINGS and look for GAP_DETECTED rows to pinpoint when the app was killed and for how long. A run of GAP_DETECTED markers for the same participant over several days is a strong signal that the participant's phone (or their battery-optimisation settings) is aggressively killing the app and that they may need personalised guidance to keep StudyRun running in the background.

Wrong participant ID

If a participant typed their ID incorrectly at enrolment, their data will be filed under the wrong ID. You cannot change the ID on a running device. The participant must leave the study (which uploads any remaining data) and re-enrol with the correct ID, if enrollment is still open. To avoid this, always confirm the ID with the participant immediately after they join.

Export appears empty

Check that your export filters are not too restrictive. The most common mistake is having a date range, sensor filter, or participant filter active that excludes the data you expect to see. Open the Data tab with the same filters to verify data exists there before trying to export.

“An export is already running”

The server runs one export per study at a time (and a small number overall) so that large downloads cannot pile up and slow the whole dashboard. If you see this message, an earlier export for the study is still streaming, possibly one you started in another tab and navigated away from. Wait for it to finish, then try again. Large multi-week exports of high-frequency sensors can take a few minutes; the download progress in your browser confirms it is moving.

Registration issues

Academic email required

During the beta, account creation is restricted to email addresses at recognised academic institutions. The list is drawn from the Hipo university-domains-list dataset plus a small internal allowlist. If your institution's domain is not recognised but should be (small institute of technology, new university, etc.), email support at support@studyrun.org with your institution name and domain, and an admin can either add the domain to the allowlist or create the account directly. Consumer addresses (gmail.com, outlook.com, etc.) cannot register.

Verification code didn't arrive

After you click Create Account the page freezes in place and shows a code input. A 6-character code is emailed to the address you entered. Most providers deliver within 30 seconds. If nothing arrives after 2–3 minutes: (1) check your Spam / Junk folder (the message is from StudyRun and mentions a verification code), (2) confirm the email you typed is correct by using Edit details to step back, (3) click Resend code. Your institution's mail filter may block automated codes — try registering with a different academic address you have access to, or contact support.

Verification code expired

Each code is valid for 2 hours. If you wait longer, clicking Verify returns a 'verification session expired' message. Just click Resend code — a fresh code is emailed and a new 2-hour window starts. Your form data is preserved; you don't have to retype anything.

Changed your mind about the email

In the verification step, click Edit details and start over to unfreeze the form. Change the email (or anything else) and click Create Account again; a new code is sent to the new address. The old code cannot be used because the token records a hash of the submitted form — any change invalidates it.

Study configuration issues

Protocol not reaching devices

A protocol is only sent to a device if all of the following are true: it is locked (not in draft), it is enabled, the current date falls within its start/end range, and the participant filter includes that device's participant ID. Check each condition in the Configure tab. After making any change, devices will pick it up on their next upload cycle, typically within a few minutes.

Notifications not arriving

Check the Send Notifications history table for the notification in question. If Sent is 0, the target devices have not yet completed an upload since you sent it; wait for the next upload cycle. If Sent is non-zero but Confirmed is low, the OS on some devices may be blocking notification display. Ask the affected participants to check that notifications are enabled for StudyRun in their phone settings.

Questionnaire (ESM) not appearing

ESM tasks are triggered by their protocol's cron schedule. Check that the protocol is locked and that the cron expression is correct. You can test a cron expression at crontab.guru. Also confirm that the protocol's notification is configured; without a notification, participants may not know to open the app when a questionnaire is due.

Advice

Bluetooth vs. iBeacon sensors

They overlap partly but capture different data. Both scan Bluetooth Low Energy advertisements, but they answer different questions.

Key differences

Real-world use cases

Bluetooth answers "what BLE devices are near the participant right now?"

• Social context (number of devices near the participant, as a rough crowding / sociality proxy).
• Device inventory (the participant owns a smartwatch, wireless headphones, a Tile, a car key fob, etc.).
• Cross-device proximity in multi-participant studies.
• A catch-all environmental signal.

iBeacon answers "is the participant near a beacon the researcher placed at location X?"

• Indoor positioning with deployed beacons: one in the kitchen, one in the bedroom, one in the bathroom, etc. The participant's presence in each room becomes an observable signal.
• Workplace or lab studies: beacons at desks, meeting rooms, or specific equipment.
• Clinical and hospital studies: beacons near doors, medication cabinets, waiting areas.
• Any scenario where the researcher physically installs BLE tags at known locations and wants to know when a participant visits.

How they overlap

Every iBeacon is also a Bluetooth device. If you enable Bluetooth, your scans will see your deployed beacons in the raw BLE output too, but only by their MAC address and RSSI, not by their structured UUID/major/minor. Conversely, the iBeacon sensor is strictly filtered: it ignores non-iBeacon BLE advertisements (phones, earbuds, cars).

So the rule of thumb:

• If you want every BLE device near the participant, enable Bluetooth.
• If you have beacons you have deployed at known locations and want to detect proximity to them, enable iBeacon (either alongside Bluetooth or instead, depending on what else you need).

Operational note

Both sensors use the same permissions (BLUETOOTH_SCAN on Android 12+, ACCESS_FINE_LOCATION on older Android, Bluetooth + Location-when-in-use on iOS), share the same underlying BLE scanner, and both are blocked if the participant disables Bluetooth or denies the permission. If Bluetooth is off for any reason, iBeacon is off too.