Overview & Architecture

EMA Forge is an open-source browser-based toolkit for designing mobile ecological momentary assessment (EMA) studies and handing them off to a deployment in the researcher's own Cloudflare account. In one workflow, you can arrange surveys and branching, add optional phone-camera tasks, preview the participant experience, deploy the study with private response storage, and monitor or export responses. The Builder needs no account and does not upload your draft study to EMA Forge.

The key workflow is from idea to a working study link: a participant opens the study in their phone browser without installing an app, while the research team manages its own deployment and data. The guided Cloudflare setup can take minutes for a draft; reviewing measures, consent, costs, device support, and institutional approval takes additional work. Phone physiology tasks are experimental and require study-specific validation.

The workflow has four parts:

Why Serverless?

The guided deployment provisions a study-specific Worker and private R2 bucket in the researcher's Cloudflare account. You do not maintain an application server, while still documenting these services and the data flow in your protocol. The independent static-host route remains available for teams with an approved receiver or manual data-return process:

• Guided Cloudflare handoff. Install a prepared study in a Worker with its own private response bucket and protected Study Admin. Use a separate deployment for each study.
• Researcher-controlled exports. Inspect live response summaries and download response and dispatch logs from the protected deployment. The independent hosting route can instead use a researcher-approved receiver or manual return.
• Phone-browser participation. Participants open links without an app installation. Test connectivity, supported devices, submission acknowledgments, and recovery before recruitment.
• Inspectable runtime. The prepared study HTML includes the participant-side code and configuration. Researchers can inspect what runs on the phone and document external providers separately.

Tradeoffs to be honest about (see Known Limitations):

• The recommended Cloudflare deployment includes a private study dashboard; a standalone static export does not, and data are only visible after files are returned to the researcher.
• SMS still requires the researcher's own Twilio account and sender. The Cloudflare study host provides scheduling, signed callbacks, opt-out updates, and an auditable dispatch log (see Twilio Integration).
• The static host can see request metadata (IP, timestamp of page load). This is the same constraint as any web page — it's not a data transmission, but it's not nothing.

Feature Status Matrix

Keep this in front of you when planning a study. Anything marked BETA has shipped but hasn't yet been through external pilot validation; anything marked WIP or PLANNED is not yet usable.

System Requirements

For you (researcher)

• Any modern desktop browser. Chrome, Edge, Firefox, or Safari (from 2022 onward). The Builder and Analyze run entirely in your browser at emaforge.keeganwhitacre.com.
• A way to host your exported study. GitHub Pages is the path of least resistance and free for researchers. Any institutional static-file server works too. (See Hosting Your Study — it is genuinely ten clicks.)
• A way to send participants links at the right times — an SMS service, institutional email scheduler, Twilio, or similar. EMA Forge generates the links; something else delivers them.
• R or Python (optional). Analyze handles local inspection, data-quality review, and long-format export in the browser. Use R or Python for confirmatory and model-based analysis.

For participants

• iOS Safari 14.5+ or Chrome for Android 90+ (roughly anything from 2021 onward).
• For the HR / ePAT modules only: a rear-facing camera with a controllable torch (flashlight). All modern iPhones and most Android devices qualify; tablets without rear cameras do not. Desktop browsers will refuse to launch these modules.
• A working browser link. That's it — no app install, no account.

Quick Start — 5 minutes to a working draft

Go from an idea to a hosted web EMA study with surveys, branching, and optional camera-based physiology. Builder and Analyze need no installation or coding; Cloudflare deploys the participant study, private response storage, and study admin into your account. A draft can take minutes; review consent, measures, device support, and data handling before enrolling anyone.

1. Go to emaforge.keeganwhitacre.com and click Builder.
2. Click Open protocol library and choose Daily Rhythm & Sleep, or start from the default draft and build your own ordered survey/task flow.
3. Replace the consent placeholder with approved study language. Review the questions, sessions, task burden, and device requirements rather than deploying a demonstration protocol unchanged.
4. Open Review & Deploy, resolve blocking checks, and select Download prepared study.
5. Select Deploy to Cloudflare. Replace the masked example ADMIN_TOKEN with your own 32+ character password. Twilio is optional and can be connected inside Study Admin later. Copy the resulting workers.dev address; EMA Forge accepts it with or without https://.
6. Paste the address into EMA Forge and select Open admin. A new deployment opens directly on Install study; upload the prepared file.
7. Run the live /check.html. It shows a plain-language pass or failure and stores the synthetic check separately from participant responses. Then complete a real test session on your phone.
8. Return to /admin, open Analyze, and select Download analysis file. Open detailed Analyze and import that single .json file to inspect observed sessions and item responses. Completion remains unavailable without scheduled prompt events.

That round trip tells you whether your device can open sessions and whether your data is landing where you expect. Always do this before enrolling a participant.

Protocol Library

The standalone Protocol Library lets you browse descriptions, burden, device requirements, validation status, and linked evidence before opening an item in the Builder. It provides three kinds of reusable building blocks:

• Complete protocols replace the current draft and demonstrate end-to-end study flows.
• Question packs add a new survey step to the first session while safely remapping question, branching, and response-piping IDs.
• Physiology task presets configure an existing built-in task such as ePAT or heartbeat counting and add it to the first session.

Every item is versioned, inspectable JSON. A local community item can be installed with Install library JSON. The Library's guided creator can copy the current browser-saved study, validate and download the contribution JSON, and open a prefilled Submit for review request. Public items remain human-reviewed and are never published automatically. Established measures should disclose the exact version, permissions, timeframe, scoring, validation status, and any adaptations. Library JSON cannot execute uploaded JavaScript or introduce an unreviewed task engine.

Study Tab

Global study configuration. Set here:

• Study name & institution — appears in participant app title and CSV metadata.
• Theme & accent color — OLED (pure black, recommended for battery), dark, or light. Accent color inherits into the participant app.
• Response format — CSV (one row per answered question) or JSON (full structured payload). Both are downloaded; JSON is always included when a session contains high-density signal data (PPG/ePAT).
• Webhook URL (optional) — if set, session data is auto-uploaded to this URL instead of being manually downloaded by the participant. See Auto-upload with Webhooks for setup.
• Greetings — per-window header text ("Good Morning", "Check-In", etc.).
• Completion lock & crash recovery — see Runtime Behavior.

Onboarding & Consent

The Onboarding flow runs exactly once per participant, on their first link (?id=N&session=onboarding, Day 0). It covers:

• A progress-barred multi-screen intro.
• A rich-text consent screen that requires scroll-to-bottom before the "I agree" checkbox activates. Consent text accepts HTML so you can paste in your IRB-approved language with headings.
• An optional schedule-sanity screen letting the participant confirm they'll be available during each window.
• For sessions that include ePAT: a two-phase practice (tone-to-tone, then tone-to-heartbeat). The ePAT measurement itself runs at its scheduled session, never during setup.

If onboarding is disabled, Day 0 is skipped entirely and participants open their first scheduled session.

Measures

Measures is the single entry point for survey items and physiology. Choose a session, then add a rating, response item, PPG heart-rate capture, ePAT, or heartbeat-counting task. The participant-flow summary shows survey blocks and physiological tasks together; Schedule controls their exact order. Survey items appear as expandable cards and update the participant preview as you type.

Question types

Place context lookup (optional)

Choose Automatic EPA walkability for the recommended Cloudflare deployment. Researchers do not need to provide a dataset. After a participant taps Use my location and grants browser permission, the phone sends coordinates in a POST request to the study Worker, which queries EPA’s National Walkability Index mapping service. The Worker returns one category and does not write coordinates or EPA’s block-group ID to R2. EPA and Cloudflare receive the lookup request and may retain service metadata under their own policies. This is a historical, area-level built-environment measure, not a live walkability or pollution reading. If EPA is unreachable or the device position is too imprecise, the response contains a missing status. The independent static-host export does not provide this online lookup endpoint.

Choose Automatic Census urban/rural to query the U.S. Census Bureau’s 2020 Census block urban/rural flag through the same study Worker. You can also select three EPA Smart Location Database v3 measures: population density (2018 estimate, people per developable acre), distance to the nearest transit stop (from the block-group population-weighted centroid, not the participant), and share of households without a car (2018 estimate). These are historical context measures, not observations of the participant, transit service today, or an individual's means. Select any combination of five automatic measures in one question: the participant grants permission once, and the Worker sends coordinates to EPA and/or Census as needed. The three Smart Location measures share one EPA request. A response records selected categories and source versions; partial results include an indicator_statuses entry for each, and missing values remain missing. No dataset upload is needed. No response saves coordinates or a block ID. There is no automatic suburban classification. Unavailable services, positions outside coverage, and imprecise locations have distinct missing statuses. This lookup sends coordinates to Cloudflare and each selected provider, which may process request metadata. Use the on-device option if that transfer is inappropriate for your study.

EMA Forge uses fixed descriptive bands for the new EPA measures; they are not validated clinical cutoffs. Population density is low under 1, moderate from 1 to under 10, and high at least 10 people per developable acre. Transit distance is near at 400 meters or less, intermediate above 400 through 1600 meters, and far beyond 1600 meters. Car-free household share is low under 5%, moderate from 5% to under 20%, and high at least 20%. Review coverage and source definitions before using bands as research variables. Even without stored coordinates, combining multiple categories, response times, and repeated observations may disclose a participant's home or routine; select only what your protocol needs. Area-level car ownership must never be treated as the participant's ownership or income.

Choose On-device study-area data if coordinates must stay out of lookup requests. In this mode, the researcher prepares a licensed dataset, and matching happens in the participant’s browser. None of the modes stores coordinates in EMA Forge response records. Only the on-device mode can include a researcher-defined pollution or deprivation band; its source, period, and thresholds need to be documented. An area-level vulnerability indicator describes a place, not a participant's income or identity.

Adding this measure opens a setup notice about consent, location privacy, source licensing, and accuracy. For the on-device mode only, upload a small GeoJSON FeatureCollection (up to 2 MB) containing study-area Polygon or MultiPolygon features. Include metadata fields name, version, source_url (HTTPS), and method describing how source values became categories. Put only permitted categorical values inside each feature's properties.indicators: walkability, pollution, deprivation (very_low / low / moderate / high / very_high), or urbanicity (urban / suburban / rural). Example feature: {"type":"Feature","properties":{"indicators":{"walkability":"high"}},"geometry":{"type":"Polygon","coordinates":[[[...]]]}}. This is a format example, not an index or a ready-to-use data source. The study-area polygons are embedded in the publicly delivered study file, so upload only data you have the right to redistribute.

A pollution category needs a specific pollutant, geographic source, reference period, and threshold method; EMA Forge does not invent or automatically calculate those values. Neighborhood Atlas ADI has separate data-use terms; obtain permission before packaging it. A browser permission prompt appears after participants tap Use my location. Declines, denied access, locations outside coverage, and uncertain matches have distinct statuses. Preview never asks for actual location. Location services on the device may use their own providers, and derived categories can still reveal sensitive context when paired with participant ID and response time. Review study consent and institutional requirements before collecting these data.

Per-question settings

• Show in these survey steps: choose the exact session steps where this question appears. Select more than one step when you intentionally want to repeat a question.
• Required: blocks advancement until answered.
• Skip Logic: compound AND/OR conditions on any prior question. Operators: eq, neq, gt, gte, lt, lte, includes. When a condition evaluates false, the question is silently skipped and not recorded.
• Earlier-answer personalization: in a later question, use Insert earlier answer, choose the source item, and set fallback wording for participants who did not answer it. EMA Forge inserts the answer at the cursor, formats multi-select responses as readable prose, and checks that the source really appears earlier in every session where the follow-up is used. In JSON, the stored form is {{q_id|fallback wording}}; the builder handles this syntax for you.

Sessions & Scheduling

New studies start with one daily ePAT session and no survey questions. Choose the study length and active days, then add sessions as needed. Each session has a time window and an ordered participant flow. Add survey questions, PPG heart-rate capture, ePAT, or heartbeat counting from Measures or directly from a session. Adding a task enables its module; advanced controls stay under Task settings. Survey questions are optional.

Days & windows

• Study length: 1–365 days.
• Days of week: restrict to weekdays only, etc.
• Windows: each has an ID, a display label, and a start/end time. The ID (e.g. morning) is what becomes the session= URL parameter.

Participant flow

Drag the cards or use their arrow buttons to change the order. Add as many separate survey steps as your protocol needs. Measures assigns each survey item to specific steps. Each card has an Options control for its name or task selection and conditional task rules. The export stores this order as phase_sequence, with question_ids on every survey step.

The available steps are:

Steps run top to bottom. For example, add PPG heart-rate capture, then ePAT, then a new survey step. Questions only repeat when you select multiple survey steps for the same question.

Task settings

Add a task to a session from Measures or Schedule to enable it automatically. In Task settings you can adjust its settings or disable a module; a disabled task still assigned to a session will block export until re-enabled or removed.

Currently available: ePAT, HCT, and experimental IAT. No camera is required for the IAT — it is the only task module that works on any smartphone without hardware constraints.

Live Preview

The Builder contains a live participant app and the top-bar Preview button opens it in a full-screen iPhone-sized frame. Preview mode (__PREVIEW_MODE__ = true) disables link expiry and session locking so you can repeat a session. It also clearly simulates camera access, flashlight checks, PPG, calibration, ePAT, and HCT values; the Builder preview never asks for sensor permission.

Click Reset to restart the rendered session without changing the study draft. Preview is for flow and usability checks, not device compatibility or measurement validation; those checks still require a deployed HTTPS study on a supported phone.

The compact Simulated preview ⓘ badge expands on demand, so the notice remains available without displacing the participant screen.

Export Options

Hosting Your Study

This section is about hosting the exported study bundle — the thing participants will open. You are not hosting the Builder itself (that already lives at emaforge.keeganwhitacre.com).

The simplest complete option is the Cloudflare study host in Review & Deploy: it serves the participant app, stores responses privately, and provides the protected Admin workspace in one deployment. The GitHub Pages path below is an advanced static-host alternative and still needs a separate approved receiver for automatic response return.

1. Create a free GitHub account if you don't have one.
2. Create a new repository (e.g. my-ema-study). Make it public or private — both work with GitHub Pages on free accounts.
3. Click Add file → Upload files, and drop in the entire contents of your extracted Export zip (the index.html, config.json, and the css / js folders).
4. Go to Settings → Pages. Under "Source," choose main branch, root folder.
5. Wait a minute. Your study is now live at https://<your-username>.github.io/my-ema-study/.

Enter that URL in Review & Deploy. If automatic return is enabled, open the hosted check.html, send its synthetic test, and confirm the same ID exists in receiver storage. Then complete one full participant session and inspect that record before generating enrollment links.

# From your extracted bundle folder
git init
git add .
git commit -m "study v1"
git branch -M main
git remote add origin https://github.com/your-lab/your-study.git
git push -u origin main

# Then in GitHub: Settings → Pages → Source = main branch, root
# Your study is live at https://your-lab.github.io/your-study/

Participant Routing

Because there is no backend, the participant's session is entirely determined by the URL they open. Four query parameters drive this:

https://your-lab.github.io/study/?id=104&day=2&session=morning&t=1732812000000

Generating Links in Bulk

The Builder's Review & Deploy tab takes a base URL and a participant-ID range, and emits a CSV with one row per (participant × day × session). Each row includes a Phase_Sequence column so you can eyeball at a glance what each link will do.

Participant_ID,Day,Active_Weekdays,Session,Phase_Sequence,Send_Window_Local,URL_Template
104,0,Any,Setup,Onboarding,Researcher scheduled,https://.../?id=104&session=onboarding
104,1,Mon|Wed|Fri,Morning,Survey questions → ePAT → Reflection,08:00-10:00,https://.../?id=104&day=1&session=w1&t={sent_at_ms}
...

This CSV is the glue between EMA Forge and your delivery mechanism of choice. It now emits a URL_Template containing {sent_at_ms}; your delivery system must replace that token with the millisecond Unix timestamp at send time. Active_Weekdays and Send_Window_Local make the scheduling rules explicit rather than silently implying every row should be sent.

Sending Prompts

You have two paths. Both use the same participant, day, window, and send-time routing model.

• Bring your own mechanism. Drop the routing CSV into an institutional email merge, a Qualtrics contacts list, a Power Automate flow, or any SMS tool that can schedule messages from a CSV. You handle timing and t= injection.
• Use Cloudflare Study Admin. BETA Add the roster and connect Twilio inside the deployed study. The Worker handles timezone math, dedupes sends, records delivery callbacks, and enforces t= expiry. See Twilio Integration.

Session Lifecycle

When a participant opens a link, the runtime:

1. Parses URL parameters.
2. Checks expiry (if t and expiry_minutes are both set).
3. Checks the completion lock — has this (id, day, session) tuple already been submitted on this device?
4. Checks for an in-progress resume state for this session.
5. Renders the first step of the session (usually a pre-task EMA block).
6. On each phase completion, writes the phase's responses to local storage and advances.
7. When the last phase finishes, the full session payload is assembled and the "Save Local Copy" screen appears. Tapping it triggers a file download.

Expiry & Grace Period

• Expiry window (default 60 min): after this many minutes past t, the link renders a "Link Expired" screen and the Start button is disabled. Recorded as a missed ping by the Dashboard.
• Grace period: a participant must begin before expiry. Once started, the exported runtime allows completion until expiry + grace. Crossing that hard deadline records and delivers the partial session with status: expired_in_progress and endedReason: response_window_elapsed.

Session Locking

By default, a participant who completes a session and then re-clicks the same link sees a "Session Complete — thanks, come back at the next prompt" screen. This prevents accidental double-submissions.

Researchers can override with ?force=1 appended to the URL (useful for QA walkthroughs or for rescuing a participant whose submission didn't land). Do not include force in participant-facing links.

Crash Recovery

If a participant's browser crashes mid-session (tab killed by iOS memory pressure, phone restart, app switch past timeout), reopening the same link will:

• Restore all completed steps (surveys, finished task trials, etc.) — that data survives.
• Restart the current phase from the beginning. Partial data within the phase is discarded to avoid ambiguity.

This is intentionally conservative. A half-finished phase with an unknown number of missing questions is worse than a clean re-run.

Schema Versioning & Migrations

Every study carries a schema version (currently 2.0.0). When the Builder loads a saved study — whether from your browser's local storage or a backup file you imported — it checks that version:

• Equal → load as-is.
• Older → refuse to load. Version 2 assigns questions directly to steps; start a new study or retain an older backup outside this Builder.
• Newer → refuse to load. A newer schema might include fields this runtime doesn't know how to preserve; loading would silently corrupt them. Export a backup from the newer Builder or reset.

This is worth knowing when rolling out an EMA Forge update mid-study: finish in-progress waves on the old version, then upgrade.

What Happens at Session End

When the last phase completes, one of two things happens depending on whether you've configured a webhook (Study tab → Webhook URL):

Manual return (when no receiver is configured)

The participant sees a "Save Local Copy" button. Tapping it downloads one or two files to their device:

• ema_data_[ID]_[DAY]_[SESSION].csv — long-format, one row per question answered. Default output when the session contains only standard EMA responses.
• ema_data_[ID]_[DAY]_[SESSION].json — full structured payload, included automatically whenever the session contains high-density signal data (PPG samples, ePAT trial-level data). Written alongside the CSV, not instead of it.

The participant returns these files via whatever channel your IRB approved (secure email, REDCap file upload, institutional SFTP). Analyze accepts Cloudflare NDJSON, a folder of JSON files, or compatible long-format CSV; a CSV-only workflow is also viable for simpler studies.

Automatic return

The prepared Cloudflare study uses same-host /submit automatically. For an independent host, set an approved HTTPS Webhook URL. The participant sees an upload confirmation only after a readable success receipt. Otherwise "Save Local Copy" appears. Browser connectivity, receiver CORS, and actual server storage must be checked with a dummy submission before collecting participant data. See Auto-upload with Webhooks.

CSV Schema (Analyze export)

When you use Export CSV in Analyze, you get one row per (session, question) pair in long format. The columns:

JSON Schema (per-session)

The raw JSON payload is what Analyze reads and is the source of truth. Shape (abbreviated):

{
  "participantId": "104",
  "sessionId": "s_a1b2c3",
  "day": 2,
  "type": "ema_with_task",
  "status": "complete",
  "startedAt": "2026-04-22T08:03:11Z",
  "completedAt": "2026-04-22T08:06:48Z",
  "data": [
    {
      "type": "ema_response",
      "block": "s_baseline",
      "windowId": "w1",
      "startedAt": "...",
      "submittedAt": "...",
      "presentationOrder": [["q1", "q2"], ["q3"]],
      "responses": {
        "q1":    { "value": 72,                        "respondedAt": "..." },
        "q2":    { "value": "Working",                 "respondedAt": "..." },
        "q3":    { "value": {"valence": 0.4,
                             "arousal": -0.2},         "respondedAt": "..." },
        "q_hr_1":{ "value": { "bpm": 74,
                              "sqi": 0.82,
                              "ibi_series": [810, 795, ...] },
                   "respondedAt": "..." }
      }
    },
    {
      "type": "epat_response",
      "trials": [ { "trial": 1, "phase_ms": 342, "confidence": 3, "sqi": 0.91 }, ... ],
      "summary": { "valid_trials": 18, "mean_abs_phase_ms": 218, "..." }
    }
  ]
}

Analysis in R

Because the Dashboard's CSV export is long-format, getting from a folder of per-session files to a tidy dataset is short. A typical starter pipeline:

library(tidyverse)
library(jsonlite)

# 1. Ingest a folder of per-session JSON files
files <- list.files("data/", pattern = "\\.json$", full.names = TRUE)
sessions <- map(files, ~ fromJSON(.x, simplifyVector = FALSE))

# 2. Flatten to long format (or just use the Dashboard's master CSV)
df <- read_csv("ema_master_dataset_2026-04-22.csv")

# 3. Compliance per participant
compliance <- df |>
  distinct(participant_id, day, session_id) |>
  count(participant_id) |>
  rename(sessions_completed = n)

# 4. Mean mood by time-of-day, handling the long format
mood <- df |>
  filter(question_id == "q1") |>
  group_by(participant_id, window_label) |>
  summarize(mean_mood  = mean(response_numeric, na.rm = TRUE),
            sd_mood    = sd(response_numeric,   na.rm = TRUE),
            n          = n(),
            .groups    = "drop")

# 5. Affect Grid (stored as "valence;arousal" in response_value)
affect <- df |>
  filter(question_type == "affect_grid") |>
  separate(response_value, into = c("valence", "arousal"),
           sep = ";", convert = TRUE)

Analyze

dashboard.html is a local analysis and protocol-simulation workspace. Imports and synthetic generation run in your browser; EMA Forge does not upload the files to a central analysis service.

What to feed it

Analyze accepts five input shapes. You can mix compatible files in a single import — the parser sorts out which files are which.

• One analysis file from Study Admin (recommended). In the deployed study's /admin page, open Analyze and select Download analysis file. It includes the installed study's question configuration and all exported responses in one JSON file. Import just that file into detailed Analyze. Keep it in an institutionally approved location: it contains participant responses.
• A Cloudflare response export. From the deployed study's /admin page, select Download responses and import the resulting .ndjson file directly. Each line is one complete, lossless session envelope. Import multiple export parts together when the admin page indicates that more than one part is available.
• A folder of JSON files. One per-session .json as produced by the participant app, plus a single config.json (the same one inside your exported study). This is the right shape when participants return files manually, or when you've downloaded them out of REDCap/institutional storage.
• A CSV from the Google Sheets webhook. BETA If you're using the Google Apps Script webhook recipe, your sheet has a Raw JSON column holding each session's payload. Export the sheet as .csv (File → Download → CSV) and import it alongside your config.json. The parser reads each row's Raw JSON cell as a full session payload.
• A long-format EMA Forge CSV. Files with session_id and question_id columns preserve answered, presented-but-unanswered, and condition-skipped states when re-imported.

Once imported, Analyze renders:

KPIs

• Protocol completion — shown only when an explicit schedule manifest supplies the expected prompts. It is unavailable for response-only imports because missing files cannot prove a missed prompt.
• Delivery records — shown only when delivery events exist. EMA Forge does not infer delivery from a completed response.
• Rapid-session flags — sessions with total duration under 30 seconds. This is a review flag, not an automatic exclusion or a signal-quality verdict.
• Mean completion time — mean duration across observed completed sessions.

Filters & views

• Aggregate vs. Per-Participant segmented view.
• Date range (by study day).
• Exclude rapid sessions (<30s) toggle for sensitivity review.
• Records requiring review — for simulations with a schedule manifest, identifies participants below 60% protocol completion. It stays unavailable for response-only imports.
• Responses — type-aware summaries for numeric, categorical, text, affect-grid, and heart-rate items, plus an exploratory composite-score builder.
• ePAT — trial and session summaries, circular phase visualization, confidence, and signal-quality views.
• Export CSV — flattens all imported sessions into one long-format file (schema above).

Protocol-aware simulation

Select Simulate study to generate a deterministic synthetic dataset from a curated protocol. Choose participant count, study days, prompt completion, item missingness, and a random seed. The generator follows the protocol's ordered survey/task steps and branching, and produces compatible ePAT and heartbeat-counting envelopes when those tasks run.

Heart-Rate Capture (Camera PPG)

EMA Forge ships a lightweight photoplethysmography (PPG) pipeline that recovers heart rate from the participant's rear-facing smartphone camera, with the torch on as an illumination source. It powers two user-facing features:

• A heart_rate question type you can drop into an EMA block anywhere.
• A standalone HR step in a window's phase sequence (identical capture, structural placement differs).

If camera access cannot start, heart-rate, ePAT, and HCT screens offer Try camera again and Continue without measurement. Continuing records structured unavailable-task metadata, preserves completed survey answers, and never invents a physiological value. Researchers should define device eligibility and missing-data handling in the approved protocol before enrollment.

ePAT — Ecological Phase Assessment Task

The ePAT is a cardiac interoceptive-accuracy task adapted for in-the-wild, mobile-first use. It is directly descended from the Phase Adjustment Task (PAT) and its refined successor PAT 2.0 — see Acknowledgments & Prior Work for primary sources. Participants align an auditory tone with their own felt heartbeats by rotating a dial until the tone "feels like it's landing on" each beat. Their phase offset (in ms, relative to ground-truth peaks detected by the camera PPG) is the dependent measure.

Heartbeat Counting Task (HCT) BETA

The Heartbeat Counting Task is a classic measure of cardiac interoceptive accuracy (Schandry, 1981). Participants silently count the heartbeats they perceive over a set of timed intervals. The accuracy score for each interval is 1 - |actual - reported| / actual, where actual is the objective beat count and reported is the participant's count. Mean accuracy across intervals is the canonical Schandry score.

EMA Forge's HCT module reuses the same camera-PPG pipeline (ePATCore) that powers the ePAT and the inline heart-rate question type, so objective beat counts during each interval are computed with the WABP onset detector and signal-quality gating described in HR Capture (PPG). Participants hold their fingertip over the rear camera + flashlight for the duration of the task.

{
  "type": "hct_response",
  "startedAt": "2026-04-30T08:04:11Z",
  "baseline": { "recordedHR": [72, 71, ...], "totalBeats": 60, "finalSqi": 0.012, ... },
  "intervals": [
    {
      "intervalIndex": 1, "isPractice": false,
      "duration_sec": 35, "durationMs_actual": 35012,
      "reportedCount": 32, "actualBeats": 41,
      "accuracy": 0.7805,
      "confidence": 6, "bodyPos": 1,
      "recordedHR": [70, 71, ...], "ibi_series": [810, 795, ...],
      "qualitySummary": { "cleanBeats": 39, "flaggedBeats": 2,
                          "sqiBadSeconds": 0.5, "sqiFinalValue": 0.012, ... }
    }, ...
  ],
  "practices": [...],
  "summary": {
    "valid_intervals": 3, "practice_intervals": 1,
    "mean_accuracy": 0.81,
    "mean_confidence": 5.7,
    "interoceptive_awareness": 0.42,
    "mean_sqi": 0.011,
    "instruction_variant": "count",
    "randomized": true,
    "intervals_sec": [25, 35, 45]
  }
}

Implicit Association Task (IAT)

The IAT (Greenwald, McGhee & Schwartz, 1998) measures the strength of automatic associations between concept pairs by comparing response times across compatible and incompatible sorting conditions. EMA Forge implements the standard 7-block IAT with D-score scoring (Greenwald, Nosek & Banaji, 2003) computed entirely in the participant's browser at session end. No server, no camera, no hardware requirements beyond a touchscreen.

Because the IAT is RT-based, mobile deployment requires deliberate engineering choices that differ from desktop implementations:

• touchstart, not click. Response time is recorded from touchstart, which fires at finger contact (~50–100 ms earlier than click). click fires as a fallback for desktop/preview.
• rAF-anchored stimulus onset. The stimulus word is written to the DOM and then t₀ = performance.now() is captured inside a requestAnimationFrame callback — not at the moment of the innerHTML write. This ensures t₀ reflects pixel-on-screen rather than JS execution time, which can diverge by a full frame (16 ms at 60 Hz) or more under load.
• Half-screen tap zones. The left and right halves of the screen are independent invisible buttons. A hairline center divider provides a visual affordance. Tap targets are intentionally the full screen height, not thumb-zone strips, to minimize motor error variance.

{
  "type": "iat_response",
  "startedAt": "2026-04-30T08:12:44Z",
  "trials": [
    {
      "block_index": 0,
      "block_id": 1,
      "block_label": "Practice: Flowers",
      "pairing_id": null,
      "critical_for_d": false,
      "trial_n_in_block": 1,
      "trial_n_overall": 1,
      "stimulus": "Orchid",
      "category": "target_a",
      "correct_side": "left",
      "response_side": "left",
      "correct": true,
      "rt_ms": 621.4,
      "excluded": false,
      "exclude_reason": null,
      "timestamp": "2026-04-30T08:12:45Z"
    },
    ...
  ],
  "summary": {
    "d_score": 0.482,
    "d_mean_pairing1": 712.3,
    "d_mean_pairing2": 891.6,
    "d_sd_pooled": 372.1,
    "d_n_pairing1": 118,
    "d_n_pairing2": 117,
    "block_order_variant": 0,
    "fast_responder": false,
    "total_trials": 200,
    "excluded_trials": 3,
    "exclusion_rate": 0.015,
    "target_a_label": "Flowers",
    "target_b_label": "Insects",
    "attr_pos_label": "Pleasant",
    "attr_neg_label": "Unpleasant",
    "block_stats": [
      {
        "block_id": 1,
        "n_total": 20, "n_valid": 20, "n_excluded": 0,
        "n_errors": 2, "error_rate": 0.1,
        "mean_rt": 698.2,
        "fast_trial_count": 0, "fast_trial_rate": 0.0
      },
      ...
    ]
  }
}

library(jsonlite)
library(dplyr)
library(purrr)
 
sessions <- list.files("data/", pattern = "\\.json$", full.names = TRUE) |>
  map(read_json)
 
iat_summary <- sessions |>
  map_dfr(function(s) {
    iat <- keep(s$data, ~ .$type == "iat_response")
    if (!length(iat)) return(NULL)
    sm <- iat[[1]]$summary
    tibble(
      pid              = s$participantId,
      day              = s$day,
      d_score          = sm$d_score,
      block_order      = sm$block_order_variant,
      fast_responder   = sm$fast_responder,
      exclusion_rate   = sm$exclusion_rate,
      mean_rt_p1       = sm$d_mean_pairing1,
      mean_rt_p2       = sm$d_mean_pairing2
    )
  })
 
# Trial-level data (for block-by-block RT analysis)
iat_trials <- sessions |>
  map_dfr(function(s) {
    iat <- keep(s$data, ~ .$type == "iat_response")
    if (!length(iat)) return(NULL)
    iat[[1]]$trials |>
      map_dfr(as_tibble) |>
      mutate(pid = s$participantId, day = s$day)
  })

Conditional Tasks

A task step in a window's phase sequence can carry a condition that gates whether it runs at all:

{ kind: "task", id: "epat",
  condition: { question_id: "q_hr_1", operator: "gt", value: 80 } }

At runtime, EMA Forge evaluates the condition against the participant's responses collected earlier in the same session. If the condition is false, the step is silently skipped — as if it were never in the sequence. Typical use cases:

• "Only run ePAT if resting HR is elevated" — gate on a prior HR capture's BPM.
• "Only show the post-task stress items if the participant reported feeling stressed beforehand" — gate on a slider threshold.
• "Skip the cognitive task on the 3rd daily window" — gate on window ID.

Privacy Model

Written plainly, because IRBs will ask you to restate this in your protocol:

1. Response data transmission is opt-in. By default, data is generated, stored, and downloaded entirely on the participant's device, and you receive it via whatever channel the participant uses to return files. If the researcher configures a webhook (Study tab → Webhook URL), the session JSON is POSTed to that specific endpoint at session end instead. No transmission happens to any endpoint other than the one you configure. The webhook field is off by default.
2. The static host sees page-load requests. Your GitHub Pages / Netlify / institutional host will receive HTTP requests when the participant opens a link. These requests include timestamp, IP, User-Agent, and the full URL (including ?id=). If participant ID alone is identifiable, choose an unlinkable ID (short opaque strings, not names or MRNs).
3. No third-party analytics, no CDN fetches, no font-provider calls. The exported study has zero outbound network calls at runtime other than (a) the initial page load from your host, and (b) the single webhook POST at session end if configured. You can verify this in Chrome DevTools → Network.
4. Camera / microphone access (HR, ePAT) is handled entirely through the browser's getUserMedia permission prompt. The media stream never leaves the device; only the derived signal (BPM, IBIs, phase offsets) is stored.
5. Consent is captured as a boolean plus a timestamp in the onboarding JSON payload. The full consent text as the participant saw it is logged alongside.

IRB Boilerplate

Two variants depending on your data-return design — use the one that matches your protocol.

Variant A: Manual participant return (no webhook)

Participant response data will be collected via a custom web-based application (EMA Forge, an open-source static web tool). The application operates entirely in the participant's mobile browser: response data is generated and stored on the participant's device and is not transmitted to any central server in the course of normal operation. Participants return completed session files to the research team via [INSTITUTIONAL SECURE CHANNEL — e.g., REDCap file upload, institutional SFTP]. No protected health information or direct identifiers are included in the study data; participants are identified only by an opaque study ID. Physiological measurements (heart rate via photoplethysmography) are derived from the participant's smartphone camera locally; raw video is not stored or transmitted. The application source code is open and available for review at github.com/keeganwhitacre/emaforge.

Variant B: Webhook auto-upload to a defined endpoint

Participant response data will be collected via a custom web-based application (EMA Forge, an open-source static web tool). The application operates in the participant's mobile browser and, at the end of each session, transmits the session's response data via HTTPS POST to a single pre-configured endpoint controlled by the research team at [ENDPOINT DESCRIPTION — e.g., an institutionally-hosted endpoint writing to a secured REDCap project / an institutional Google Workspace sheet under the PI's account / an AWS Lambda writing to an encrypted S3 bucket in the institution's AWS organization]. No data is transmitted to any other endpoint. If network transmission fails, the application falls back to on-device storage and manual return via [FALLBACK CHANNEL]. No protected health information or direct identifiers are included in the study data; participants are identified only by an opaque study ID. Physiological measurements (heart rate via photoplethysmography) are derived from the participant's smartphone camera locally; raw video is not stored or transmitted. The application source code is open and available for review at github.com/keeganwhitacre/emaforge.

Known Limitations

• Admin is operational, not a full clinical data platform. The Cloudflare Admin workspace provides live response counts, recent sessions, protected exports, roster/delivery controls, and descriptive analysis; confirmatory analysis and higher-risk access controls remain the researcher's responsibility.
• Missed-prompt detection requires event data. Response files alone cannot reveal prompts that produced no file. Analyze therefore leaves completion unavailable unless a roster and scheduled prompt-event log or a synthetic schedule manifest is present.
• Device heterogeneity. HR/ePAT quality depends on camera sensor, torch brightness, and case thickness. Pilot across a range of devices before locking your protocol.
• Browser storage can be cleared. A participant who "clears website data" mid-study loses their in-progress resume state (but not already-downloaded session files). The completion lock also resets.
• Single-file exports don't let you patch typos. Use the static-hosting bundle if you anticipate edits after deployment.
• Accessibility is a work in progress. Screen-reader support for sliders and the affect grid is incomplete. Audit against your accessibility requirements before broad enrollment.

Roadmap

Auto-upload with Webhooks BETA

The recommended prepared Cloudflare study automatically posts each completed session to the deployment's same-host /submit endpoint. "Save Local Copy" is the safety fallback when storage is unavailable. Manual return remains available when no receiver is configured.

For independent hosting, the webhook option provides the same automation. When you paste an approved HTTPS URL into the Receiver field, the exported study silently POSTs the full session JSON to that URL at save-time. The participant sees "Data uploaded successfully" only after the receiver responds with readable JSON containing {"status":"success"}. A failed or unreadable acknowledgment offers a local download. Confirm storage on the receiver before enrollment; an HTTP 200 alone does not prove data was saved.

What gets sent

The runtime POSTs a JSON body to your endpoint with this shape:

{
  "submission_id": "s_a1b2c3",
  "participant_id": "104",
  "day": 2,
  "window_id": "morning",
  "session_data": {
    "participantId": "104",
    "sessionId":     "s_a1b2c3",
    "day":           2,
    "type":          "ema_with_task",
    "status":        "complete",
    "startedAt":     "2026-04-22T08:03:11Z",
    "completedAt":   "2026-04-22T08:06:48Z",
    "data": [ /* ema_response, epat_response, etc. — full payload */ ]
  }
}

The top fields include a stable submission_id for receiver deduplication and convenient dispatch/filtering on your receiving end. The session_data object is the same JSON documented in JSON Schema.

Webhook recipes by receiver

These recipes are examples that require testing in your own hosting and institutional environment. The endpoint must return readable JSON with {"status":"success"} after durable storage and permit the study origin through CORS. The Google Apps Script option may save a row even when a browser cannot read its redirected response. EMA Forge's webhook is a plain HTTPS POST with a JSON body. Anything that can accept that and return a readable success receipt after saving can work. The table below summarises the recipes documented in this section; pick the one whose tradeoffs match your IRB, your IT environment, and your willingness to do setup work.

Google Sheets via Apps Script BETA

An example receiver for testing with non-sensitive data. Apps Script Content Service redirects its response; browser cross-origin access and institutional approval must be checked before relying on it for participant data.

function doPost(e) {
  try {
    const data  = JSON.parse(e.postData.contents);
    const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

    if (sheet.getLastRow() === 0) {
      sheet.appendRow(['Timestamp', 'Participant ID', 'Day', 'Window', 'Raw JSON']);
      sheet.getRange(1, 1, 1, 5).setFontWeight("bold");
      sheet.setFrozenRows(1);
    }

    sheet.appendRow([
      new Date(),
      data.participant_id || 'Unknown',
      data.day            || 'Unknown',
      data.window_id      || 'Unknown',
      JSON.stringify(data.session_data || data)
    ]);

    return ContentService
      .createTextOutput(JSON.stringify({status: 'success', submission_id: data.submission_id}))
      .setMimeType(ContentService.MimeType.JSON);

  } catch (error) {
    return ContentService
      .createTextOutput(JSON.stringify({error: error.message}))
      .setMimeType(ContentService.MimeType.JSON);
  }
}

Cloudflare study host → private R2 BETA

This is EMA Forge's recommended path for hosting, study administration, optional messaging, and automatic data return. One Worker serves the participant study and stores one JSON object per session, uses the stable submission ID as its key, confirms a successful write before acknowledging the participant app, treats an exact retry as a duplicate, and refuses changed data that attempts to reuse an existing ID. The private bucket has no public read route. Study installation, roster management, monitoring, browser-local analysis, and exports require the deployment's admin token.

One deployment per study. A Worker binds one private R2 bucket and maintains one active study, roster, and response collection. For a new study in the same Cloudflare account, create another Worker with a unique name; the new template leaves the STUDY_DATA bucket name unset so Cloudflare provisions a separate bucket automatically. Confirm that the new Worker's binding points to its own bucket before installation. Older deployments made with a fixed default bucket name may still need a one-time binding correction. If Admin reports a storage conflict, connect a new empty bucket before installing; never clear the existing study's bucket. Reinstalling a protocol for the current study preserves historical responses; installing a differently named study is blocked so those records are not mixed.

Updating an existing study: Download the new prepared HTML and install it in the existing Study Admin. Keep the existing Worker, URL, and R2 bucket. If an EMA Forge feature also changes Worker code, choose Update an existing Worker’s code → Download Worker update in Review & Deploy. Select the existing Worker in Cloudflare Workers & Pages, choose Edit code, replace its code with that self-contained file, and deploy while preserving its STUDY_DATA binding and admin secret. The raw worker.mjs has a separate import and is not the single-file update. The Create new study host button is for a separate study, not a software update. If running several independent studies, each has its own Worker and bucket; Worker code changes must currently be applied to each. Do not delete a Worker to update it.

library(aws.s3)

Sys.setenv(
  AWS_ACCESS_KEY_ID     = "<your R2 access key>",
  AWS_SECRET_ACCESS_KEY = "<your R2 secret key>",
  AWS_S3_ENDPOINT       = "<account_id>.r2.cloudflarestorage.com"
)

# Sync entire bucket to local
files <- get_bucket_df(bucket = "ema-forge-sessions", region = "auto")
for (key in files$Key) {
  save_object(key, bucket = "ema-forge-sessions",
              file = file.path("data", basename(key)))
}

Azure Function → SharePoint List STABLE

The institutional Microsoft path. Best fit when your university mandates Microsoft 365 for research data storage, when your IRB prefers data stay inside the institutional tenant, or when your IT contact will resist approving non-Microsoft cloud services. Azure Functions on the consumption plan are free up to 1 million executions per month, which is well above any plausible EMA workload.

This recipe requires a one-time app registration in Azure AD, which typically means asking your central IT to grant the Sites.ReadWrite.All application permission. Most university IT shops process this routinely.

const { app } = require('@azure/functions');
const { Client } = require('@microsoft/microsoft-graph-client');
const { ClientSecretCredential } = require('@azure/identity');
require('isomorphic-fetch');

app.http('SaveSession', {
  methods: ['POST', 'OPTIONS'],
  authLevel: 'function',
  handler: async (req, ctx) => {
    const cors = {
      'Access-Control-Allow-Origin':  '*',
      'Access-Control-Allow-Methods': 'POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    };
    if (req.method === 'OPTIONS') return { status: 200, headers: cors };

    try {
      const raw  = await req.text();
      const data = JSON.parse(raw);

      const credential = new ClientSecretCredential(
        process.env.TENANT_ID,
        process.env.CLIENT_ID,
        process.env.CLIENT_SECRET
      );
      const graph = Client.initWithMiddleware({
        authProvider: {
          getAccessToken: async () =>
            (await credential.getToken('https://graph.microsoft.com/.default')).token
        }
      });

      const siteId = process.env.SHAREPOINT_SITE_ID;
      const listId = process.env.SHAREPOINT_LIST_ID;

      await graph
        .api(`/sites/${siteId}/lists/${listId}/items`)
        .post({
          fields: {
            Title:        `${data.participant_id}_D${data.day}_${data.window_id}`,
            Participant:  String(data.participant_id || ''),
            Day:          Number(data.day) || 0,
            Window:       String(data.window_id || ''),
            ReceivedAt:   new Date().toISOString(),
            SessionJSON:  JSON.stringify(data.session_data || {}).slice(0, 250000)
          }
        });

      return {
        status: 200,
        headers: { ...cors, 'Content-Type': 'application/json' },
        body: JSON.stringify({ status: 'success' })
      };
    } catch (err) {
      ctx.error(err);
      return {
        status: 500,
        headers: { ...cors, 'Content-Type': 'application/json' },
        body: JSON.stringify({ error: err.message })
      };
    }
  }
});

npm install @azure/functions @azure/identity @microsoft/microsoft-graph-client isomorphic-fetch

Power Automate → Excel STABLE

Simpler than the Azure Function path, but the "When an HTTP request is received" trigger is a Premium Power Automate connector that most institutional Microsoft 365 plans do not include. Before investing time, check with IT whether your Microsoft 365 plan has Premium Power Automate. If not, use the Azure Function path instead.

REDCap via institutional PHP proxy STABLE

Direct browser-to-REDCap POSTs are blocked by CORS on most REDCap installations. The realistic path is a one-file PHP proxy hosted on your lab's institutional web server, which accepts the POST from the participant's phone and forwards it to REDCap's API using your project token. This is the path most IRBs prefer because the data path is institutional end-to-end — the participant's phone hits a university domain, which forwards to a university REDCap instance, with no external cloud services involved.

<?php
// ema-forge-redcap-proxy.php
// Forwards EMA Forge sessions into a REDCap project's repeatable instrument.

header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: POST, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type');
header('Content-Type: application/json');

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(200);
    exit;
}

$REDCAP_URL    = getenv('REDCAP_URL')   ?: 'https://redcap.your-uni.edu/api/';
$REDCAP_TOKEN  = getenv('REDCAP_TOKEN') ?: 'PASTE_YOUR_TOKEN_HERE';
$SHARED_SECRET = getenv('EMA_SECRET')   ?: '';  // optional, recommended

if ($SHARED_SECRET && ($_GET['auth'] ?? '') !== $SHARED_SECRET) {
    http_response_code(401);
    echo json_encode(['error' => 'unauthorized']);
    exit;
}

$body = file_get_contents('php://input');
$data = json_decode($body, true);
if (!$data) {
    http_response_code(400);
    echo json_encode(['error' => 'invalid JSON']);
    exit;
}

$record = [[
    'record_id'                => $data['participant_id'] ?? 'unknown',
    'redcap_event_name'        => 'ema_arm_1',           // edit to match your project
    'redcap_repeat_instrument' => 'session',
    'redcap_repeat_instance'   => 'new',                  // REDCap auto-assigns
    'session_day'              => $data['day'] ?? '',
    'session_window'           => $data['window_id'] ?? '',
    'session_json'             => json_encode($data['session_data'] ?? []),
    'session_received'         => date('Y-m-d H:i:s'),
]];

$payload = http_build_query([
    'token'             => $REDCAP_TOKEN,
    'content'           => 'record',
    'format'            => 'json',
    'type'              => 'flat',
    'data'              => json_encode($record),
    'overwriteBehavior' => 'normal',
    'forceAutoNumber'   => 'false',
    'returnContent'     => 'count',
]);

$ch = curl_init($REDCAP_URL);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = curl_exec($ch);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code >= 200 && $code < 300) {
    http_response_code(200);
    echo json_encode(['status' => 'success']);
} else {
    http_response_code(502);
    echo json_encode(['error' => 'redcap rejected', 'code' => $code]);
}

AWS Lambda → S3 STABLE

For labs standardised on AWS. Cost is roughly $0–3 per month at EMA scale: Lambda's free tier covers ~1M requests/month indefinitely, and S3 storage runs about $0.023 per GB-month. Output shape mirrors the Cloudflare R2 recipe (one JSON file per session, partitioned by participant/day), so analysis pipelines are interchangeable.

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

const s3     = new S3Client({ region: process.env.AWS_REGION });
const BUCKET = process.env.BUCKET_NAME;

export const handler = async (event) => {
  const cors = {
    'Access-Control-Allow-Origin':  '*',
    'Access-Control-Allow-Methods': 'POST, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type',
  };

  if (event.requestContext?.http?.method === 'OPTIONS') {
    return { statusCode: 200, headers: cors };
  }

  try {
    const body = JSON.parse(event.body);
    const pid  = String(body.participant_id || 'unknown');
    const day  = String(body.day || '0');
    const win  = String(body.window_id || 'na');
    const ts   = Date.now();
    const key  = `sessions/${pid}/day-${day}/${win}_${ts}.json`;

    await s3.send(new PutObjectCommand({
      Bucket:      BUCKET,
      Key:         key,
      Body:        JSON.stringify(body),
      ContentType: 'application/json',
      Metadata:    { participantid: pid, day, windowid: win }
    }));

    return {
      statusCode: 200,
      headers:    { ...cors, 'Content-Type': 'application/json' },
      body:       JSON.stringify({ status: 'success', key })
    };
  } catch (err) {
    return {
      statusCode: 500,
      headers:    { ...cors, 'Content-Type': 'application/json' },
      body:       JSON.stringify({ error: err.message })
    };
  }
};

Cautions and gotchas

• Webhook URLs in a public study are public. Anyone can inspect exported HTML and POST synthetic data, including if the URL contains a query-string secret. Use server-side validation, study-specific limits and reconciliation; a static webpage cannot keep a shared secret.
• Google Apps Script has quotas and redirects. Capacity depends on the account and payload; verify browser-to-receiver acknowledgment and storage under expected load.
• Apps Script may store a row while the browser cannot read its response. Cross-origin redirects and CORS can cause the participant to see "Upload not confirmed" after the server wrote data. Check the sheet before accepting a manually returned copy to avoid duplicates.
• If you change the webhook URL mid-study, participants who cached the old exported HTML will continue to post to the old URL until they clear site data or you push a new export. Make webhook changes at export boundaries, not mid-enrollment.
• Webhooks do not eliminate the manual-download safety net. By design. If connectivity fails at session end, the "Save Local Copy" button reappears and the participant can still return the file by your IRB-approved channel.

Twilio Integration BETA

Twilio credentials can be entered on the protected /admin page after deployment. They are encrypted in private study storage using the admin token; Cloudflare Worker secrets remain an alternative. Google Sheets and Apps Script are no longer part of the recommended path. The Worker reads the installed EMA Forge schedule, evaluates it in each participant's IANA timezone every five minutes, sends an individualized link, and stores an auditable dispatch record separately from response data.

Setup

1. Complete the normal Cloudflare deployment and install the prepared study at /admin.
2. Open Install study in Study Admin. Enter your Account SID, Auth Token, and either a sending number or Messaging Service SID, then choose Connect Twilio. The credentials are not displayed again. If the admin token changes, reconnect Twilio.
3. In Twilio, set the incoming-message webhook to https://<your-study-host>/twilio/incoming using POST. The Worker validates Twilio's signed request before changing a roster record.
4. Open Participants & delivery in Study Admin. Upload a CSV or add participants, send a test message, and only then enable scheduled messaging.

Roster schema

How delivery works

1. A Cloudflare Cron Trigger invokes the Worker's scheduled handler every five minutes.
2. The Worker determines the participant's calendar study day and local time, intersects participant preferences with protocol weekdays, and derives a stable randomized minute inside each window.
3. A prompt is claimed with a participant/day/window key before the Twilio request. This prevents overlapping scheduler runs from sending the same prompt twice.
4. The Worker creates an opaque /j/… link. Its private R2 mapping contains the participant, day, session, and send time needed to enforce the configured response window and grace period. The SMS does not expose those routing parameters.
5. Twilio API acceptance, sent, delivered, failed, and opt-out events are retained as separate states. Signed delivery callbacks update the existing dispatch record.

Explicit send failures retry up to three times, no more frequently than every fifteen minutes. An API acceptance is not labeled handset delivery. The Analyze tab reports exactly the states received from Twilio and does not infer delivery from a successful API request.

Admin and analysis

The protected Admin workspace provides the participant link, connection check, live response counts, roster, messaging controls, revocable participant invite links, response summaries, physiology-session counts, recent submissions, raw NDJSON, and the dispatch audit log. Invite links are study-scoped rather than a general-purpose URL shortener. Operational analysis runs in the browser against protected Worker endpoints; participant data are not uploaded back to EMA Forge.

Known limitations

• Twilio setup is still external. Researchers must obtain a Twilio sender and satisfy the applicable messaging registration requirements. Credentials can then be entered in Study Admin.
• Five-minute scheduling is approximate. It is appropriate for EMA windows, not exact-to-the-second interventions.
• Phone numbers are sensitive. They are kept in the private roster, separate from response files, but remain the researcher's responsibility under the approved data-management plan.
• Admin summaries are descriptive. Download the lossless response and dispatch files for confirmatory analysis and archived reproducibility.
• Test before enrollment. Verify at least two timezones, STOP, delivery callbacks, link expiry, and one complete response on the actual participant devices.

Under the Hood

You do not need any of this to run a study. It's here for the small subset of users who want to audit the code, contribute a new task module, or fork the project for a deeply custom use case.

ema-forge/
├── index.html             # Landing page
├── builder.html           # Study authoring environment
├── dashboard.html         # Local analysis dashboard
├── readme.html            # This file
├── ppgtester.html     # Standalone PPG pipeline tester
│
├── css/
│   ├── studio.css             # Shared design tokens + component styles
│   ├── builder.css            # Builder workspace layout
│   └── dashboard.css          # Analyze workspace layout
│
├── library/                # Versioned protocols, packs, and task presets
│
├── js/
│   ├── state.js               # Central state + schema (SCHEMA_VERSION)
│   ├── storage.js             # LocalStorage + project import/export + migrations
│   ├── export.js              # Compiles study to HTML / zip bundle
│   ├── preview.js             # Live iframe preview
│   │
│   ├── tabs/                  # Builder tab controllers
│   │   ├── study.js
│   │   ├── onboarding.js
│   │   ├── questions.js
│   │   ├── schedule.js        # Windows + phase_sequence editor
│   │   ├── tasks.js           # Pluggable module registry
│   │   └── deployment.js      # Routing CSV generator
│   │
│   └── dashboard/
│       ├── parser.js          # Ingests participant JSON folder
│       ├── simulator.js       # Deterministic synthetic protocol runs
│       └── dashboard.js       # Charts, filters, CSV export
│
└── templates/                # Source files stitched into the exported study
    ├── epat-core.js           # PPG pipeline + BeatDetector
    ├── study-base.js          # Runtime skeleton
    ├── module-onboarding.js
    ├── module-ema.js          # EMA block + inline HR capture
    └── module-epat.js         # ePAT task

git clone https://github.com/keeganwhitacre/emaforge.git
cd emaforge
python -m http.server 8000
# then open http://localhost:8000

Credit & Citation

EMA Forge was created by Keegan Whitacre at the Affective Science Lab, The Ohio State University. If you use EMA Forge in a published study, please cite:

Whitacre, K. (2026). EMA Forge: A serverless toolkit for
ecological momentary assessment and digital phenotyping.
Affective Science Lab, The Ohio State University.
https://github.com/keeganwhitacre/emaforge

For ePAT-specific methods, also describe the implementation (PPG pipeline + AudioContext-scheduled stimulus + dial-alignment response) in your Methods section. Issues, pull requests, and replication reports are welcome.

License

EMA Forge is released under the MIT License — free for academic and commercial use, modification, and redistribution. See LICENSE in the repository for the full text.

Acknowledgments & Prior Work

EMA Forge stands on a substantial body of prior work. The ePAT task in particular is not a novel invention but an ecological adaptation of an established psychophysical paradigm. Proper attribution here matters both scholarly and practically — if you publish using these modules, these are the citations your Methods section owes.

The Phase Adjustment Task (PAT) lineage

The core psychophysical logic of the ePAT — aligning an auditory tone to felt heartbeat via a continuous-adjustment response — is adapted from the Phase Adjustment Task developed by Plans, Ponzo, Morelli, Cairo, Ring, Keating, Cunningham, Catmur, Murphy & Bird, with subsequent refinements in PAT 2.0.

• Plans, D., Ponzo, S., Morelli, D., Cairo, M., Ring, C., Keating, C. T., Cunningham, A. C., Catmur, C., Murphy, J., & Bird, G. (2021). Measuring interoception: The phase adjustment task. Biological Psychology, 165, 108171.
• Palmer, C., Murphy, J., Bird, G., et al. (2025). Refinements of the Phase Adjustment Task (PAT 2.0). Preprint. doi:10.31219/osf.io/4qtwv.
• Original reference implementation (Swift/iOS): huma-engineering/Phase-Adjustment-Task.

The ePAT's contribution is specifically the ecological framing: porting the paradigm to a participant-owned smartphone, using camera PPG rather than a dedicated pulse oximeter, scheduling it within an EMA protocol rather than as a discrete lab session, and treating the resulting phase-offset trajectory as a time-varying individual-difference signal rather than a single-point measurement.

Beat detection — WABP

The PPG peak-detection routine is a JavaScript port of the WABP (Waveform Analysis for Blood Pressure) algorithm, originally developed for arterial blood pressure onset detection and released on PhysioNet. The algorithm generalizes well from arterial pressure to PPG because both signals share the characteristic upstroke-dominant morphology the algorithm was designed around.

• Zong, W., Heldt, T., Moody, G. B., & Mark, R. G. (2003). An open-source algorithm to detect onset of arterial blood pressure pulses. Computers in Cardiology, 30, 259–262.
• Reference C implementation: PhysioNet wabp.c.

Camera-based PPG acquisition

The browser-side camera acquisition approach — sampling the red channel of a rear-camera video stream under torch illumination — was informed by Richard Moore's open-source demonstrator, which established the feasibility of the pattern in a pure web environment.

• Moore, R. heart-rate-monitor. github.com/richrd/heart-rate-monitor.

Conceptual framework

The decision to operationalize interoceptive accuracy as an ecological, time-varying construct — and to embed it within a broader affective-science EMA protocol — is grounded in the Theory of Constructed Emotion and contemporary work on interoceptive predictive processing. The ePAT is one instrument within that larger program; it is not itself a complete theory.