From 0254b612c946a98f5411b6cb40c0e2ed10ed1800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Erik=20Bj=C3=A4reholt?= Date: Wed, 16 Sep 2026 12:30:37 +0200 Subject: [PATCH 1/3] docs: add a Research section with participant instructions ActivityWatch is used as a data-collection instrument in academic studies, but the participant-facing instructions have been circulated over email and go stale between releases. This adds a canonical, versioned page studies can link to. - research/index: why the tool suits research (local-first, auditable, category-only collection), the IJmker 2008 validity citation, and how to cite ActivityWatch via the Zenodo DOI - research/participant-instructions: install and permissions per platform, what is recorded, and the end-of-study export, plus a "Notes for researchers" section covering the mistakes that generate support mail (the per-row export menu instead of "Export all buckets as JSON", CSV vs JSON, two buckets being normal, and the UI auto-selecting a locale from the browser language) Studies keep their own branding, upload location and translations; only the mechanics live here. --- src/index.rst | 7 ++ src/research/index.rst | 48 +++++++++ src/research/participant-instructions.rst | 119 ++++++++++++++++++++++ 3 files changed, 174 insertions(+) create mode 100644 src/research/index.rst create mode 100644 src/research/participant-instructions.rst diff --git a/src/index.rst b/src/index.rst index 52cba29..08f30fb 100644 --- a/src/index.rst +++ b/src/index.rst @@ -45,6 +45,13 @@ Table of contents development forking +.. _research-docs: +.. toctree:: + :maxdepth: 2 + :caption: Research + + research/index + .. _meta-docs: .. toctree:: :maxdepth: 3 diff --git a/src/research/index.rst b/src/research/index.rst new file mode 100644 index 0000000..871626e --- /dev/null +++ b/src/research/index.rst @@ -0,0 +1,48 @@ +.. _research: + +ActivityWatch in research +========================= + +ActivityWatch is used as a data-collection instrument in academic studies. This section +documents the **Research Edition**, a purpose-built variant for that use, and maintains the +participant-facing instructions so that studies can link to a canonical, versioned page +rather than circulating copies over email. + +Why researchers use it +---------------------- + +- **Local-first.** Data stays on the participant's device. Nothing is transmitted + automatically. The participant creates an export file and uploads it deliberately, which + makes the data flow easy to describe in an ethics application. +- **Open source.** The collection logic can be read, audited and cited by reviewers. +- **Cross-platform.** Windows, macOS and Linux, plus Android. +- **Category-only collection.** The Research Edition can be configured to store predefined + categories rather than window titles or URLs. + +Self-reported computer use is a poor measure of actual computer use. The canonical validity +study found that self-report agreed with software registration for only 18% of participants, +and misclassified exposure for more than 80%: + + IJmker S, Leijssen JNM, Blatter BM, van der Beek AJ, van Mechelen W, Bongers PM. + *Test-retest reliability and validity of self-reported duration of computer use at work.* + Scand J Work Environ Health. 2008;34(2):113-119. `doi:10.5271/sjweh.1220 + `_ + +How to cite +----------- + +If you use ActivityWatch in published work, please cite the software: + + Bjäreholt E, Bjäreholt J. *ActivityWatch.* `doi:10.5281/zenodo.4957165 + `_ + +The repository also contains a ``CITATION.cff``, which GitHub renders as a +"Cite this repository" button. + +If you are running or planning a study, please get in touch. We are glad to help scope the +instrument, and we keep a list of studies that have used ActivityWatch. + +.. toctree:: + :maxdepth: 2 + + participant-instructions diff --git a/src/research/participant-instructions.rst b/src/research/participant-instructions.rst new file mode 100644 index 0000000..c773a33 --- /dev/null +++ b/src/research/participant-instructions.rst @@ -0,0 +1,119 @@ +.. _research-participant-instructions: + +Participant instructions (Research Edition) +=========================================== + +.. note:: + **For researchers.** This page is maintained by the ActivityWatch project so that studies + can link to it instead of maintaining their own copy of the technical steps. It is kept in + sync with the current Research Edition build. + + Adapt freely: add your study name, your contact details, and your upload location. + Translate as needed. The parts worth linking rather than copying are the mechanics below, + because those are what change between releases. + + *Last reviewed: 2026-09-16, against v0.14.0b5-research.* + +The Research Edition is a separate build. It installs alongside a normal ActivityWatch +installation without interfering with it: the Research Edition runs on port **5667**, a +standard installation runs on port 5600. The dashboard shows a **Research Edition** badge at +the top. If you see that badge, you are in the right place. + +Installing +---------- + +Download the build for your system from the link your researcher gave you, then open the +downloaded file and follow the installation steps. + +**Windows.** The installer is not code-signed, so Windows may show a blue +"Windows protected your PC" dialog. Click **More info**, then **Run anyway**. + +During installation, leave **Start ActivityWatch when Windows starts** ticked. It is ticked +by default. + +**macOS.** The app asks for two separate permissions, and it needs both: + +1. **Accessibility.** On first launch you may see "Missing accessibility permissions". + Enable *ActivityWatch Research* under System Settings > Privacy & Security > + Accessibility, and restart the app if prompted. Without this permission the app cannot + record anything. +2. **Browser control.** If you use Chrome or Safari, macOS asks whether + *ActivityWatch Research* may control it. Click **OK**. This is only used to sort the page + into a category. The address is not stored. + +If macOS shows a notification that a background item was added, leave it allowed. + +Starting automatically +---------------------- + +The Research Edition enables start-at-login by itself the first time it runs. You do not need +to configure anything. + +It is still worth checking once or twice during the study that the icon is present: in the +system tray on Windows (bottom right, possibly hidden under the **^** arrow), or in the menu +bar on macOS (top right). If it is missing, start *ActivityWatch Research* from the Start menu +or Applications folder. + +What is recorded +---------------- + +The Research Edition records **which applications you use** (for example Word, Teams or +Chrome) and for how long. It does **not** record which websites you visit or what your window +titles say. Browser activity is converted into predefined categories on your own computer +before anything is stored, and your computer's hostname is removed from the export. + +No information about your activity is sent anywhere automatically. At the end of the study you +create a file and upload it yourself. + +(For completeness: if you open the dashboard, the web interface asks GitHub for the latest +version number. That request contains nothing about your activity.) + +Exporting your data at the end of the study +------------------------------------------- + +Do this once, at the end of the study period, and keep the Research Edition running while you +do it. It takes a couple of minutes. + +1. Click the **ActivityWatch Research** icon (macOS: menu bar, top of the screen. Windows: + bottom right near the clock, possibly under the **^** arrow) and choose **Open Dashboard**. + The dashboard opens in your browser. Check that it says **Research Edition** at the top. + If the dashboard does not open, go to http://localhost:5667 +2. Click **Raw Data** at the top right of the page. If your dashboard is not in English, + this is the same button under a translated name (Swedish: **Rådata**). +3. You will see two rows, ``aw-watcher-window_…`` and ``aw-watcher-afk_…``. That is normal. + **Do not export them one by one.** Scroll down to **Import and export buckets**, and under + **Export buckets** click **Export all buckets as JSON** (Swedish: **Importera och + exportera buckets** > **Exportera alla buckets som JSON**). +4. A file named ``aw-bucket-export.json`` appears in your Downloads folder. You do not need to + open or edit it. +5. Upload that file where your researcher has asked you to. + +If something looks wrong, contact your researcher rather than searching online. The study +version behaves differently from the public ActivityWatch. + +Notes for researchers +--------------------- + +A few things that reliably cause support questions: + +- **Two buckets is correct**, not a symptom of a double installation: one window watcher and + one AFK watcher. Four rows would mean the participant opened the standard dashboard on port + 5600 instead. +- **Use "Export all buckets as JSON", not the per-row menu.** The three-dot menu on a row + exports a single bucket. Participants following that route upload two files, or silently + omit AFK data. +- **JSON, not CSV.** CSV covers one bucket, contains events only, carries no metadata, and + does not go through the export API. +- **The interface may not be in English.** The web UI ships ``en``, ``uk``, ``de``, ``ru``, + ``zh-CN`` and ``sv`` locales, and it **selects one automatically from the browser + language** unless the participant has already chosen one. Translation coverage is + incomplete across all locales, so participants will see a mix. The tray menu is hardcoded + English regardless. + + Write button names in both languages in your participant instructions, for example + "Rådata (Raw Data)". Assuming English will send some participants looking for a label + their screen does not show. +- **The exported filename is fixed.** It cannot carry a participant number, so your upload + form needs a field or a per-participant link. +- **Live Raw Data is unsanitised by design.** The rewriting to ``research-participant`` + happens in the export. From 847f81a401d8649dd003d5faf15b801ef09d390f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Erik=20Bj=C3=A4reholt?= Date: Wed, 16 Sep 2026 15:38:18 +0200 Subject: [PATCH 2/3] docs(research): add a list of studies using ActivityWatch ActivityWatch appears in methods sections rather than titles or abstracts, so it is largely invisible to citation indexes - both Zenodo DOIs currently report zero tracked citations despite real academic use, including a 2,000-participant Oxford study and a multi-year ERC-funded deployment at Ghent. A public list serves two purposes: it lets researchers choosing an instrument see prior use, and it gives existing users a reason to tell us they exist. --- src/research/index.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/research/index.rst b/src/research/index.rst index 871626e..15d6210 100644 --- a/src/research/index.rst +++ b/src/research/index.rst @@ -39,6 +39,30 @@ If you use ActivityWatch in published work, please cite the software: The repository also contains a ``CITATION.cff``, which GitHub renders as a "Cite this repository" button. +Studies using ActivityWatch +--------------------------- + +An incomplete list, maintained so that researchers choosing an instrument can see prior use. +ActivityWatch typically appears in methods sections rather than titles or abstracts, so it is +largely invisible to citation indexes — if you have used it and are not listed, please tell us. + +- **Psychological Wellbeing, Sleep, and Video Gaming: Analyses of Comprehensive Digital + Traces** — Oxford Internet Institute (Ballou, Földes, Hakman, Vuorre, Magnusson, Przybylski), + Stage 1 Registered Report, 2025. ActivityWatch used as the Android data-collection channel + for 2,000+ participants over three months. +- **On/Off** — imec-mict-UGent (Vanden Abeele, Perneel, Van Gaeveren), the DISCONNECT ERC + citizen-science panel. ActivityWatch used for opt-in laptop and PC collection, documented in + the study's participant information and privacy materials. +- **Traces as Data** — Parry & Klingelhoefer, handbook chapter, 2025. Named as an exemplar + desktop-logging tool. +- **Sabermetrics for Cyber** — Rivera, Booz & Hammerstein, ECCWS 2025. Used as an instrument. +- **Activity Frames** — Iyamu, 2026 (arXiv:2608.05784). +- Theses: Kroček (University of South Bohemia, 2020), Kraus (Czech Technical University in + Prague, 2021), Panchuk (NURE Kharkiv, 2026). + +Further deployments are known but unpublished or not yet listed here, including at the +University of Maryland iSchool, MIT Media Lab, Clemson University, and Lund University's IIIEE. + If you are running or planning a study, please get in touch. We are glad to help scope the instrument, and we keep a list of studies that have used ActivityWatch. From be65c9a61f75324e9dbbd0ec89af657981aef844 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Erik=20Bj=C3=A4reholt?= Date: Thu, 17 Sep 2026 11:39:37 +0200 Subject: [PATCH 3/3] docs(research): correct sanitisation mechanism, bucket-count diagnosis, and study classification - Notes for researchers now lead with where filtering actually happens: transform_window runs before client.heartbeat, so titles/URLs are filtered at capture, not export. The research-participant rewrite is the hostname, which is export-only. Adds the fail-closed export refusal (pre-existing database) as the failure mode that actually generates mid-study support mail. - Row count is not an edition discriminator: a standard install also shows two buckets, and the two editions are separate servers. Diagnose by the Research Edition badge and port 5667. Buckets are per watcher and per host. - Split the studies list by actual relationship. Activity Frames (Iyamu 2026) cites ActivityWatch once as related work and runs its own capture pipeline; it is not an instrument use. Traces as Data and the student theses likewise move out of the instrument list. --- src/research/index.rst | 50 +++++++++++++++-------- src/research/participant-instructions.rst | 24 ++++++++--- 2 files changed, 52 insertions(+), 22 deletions(-) diff --git a/src/research/index.rst b/src/research/index.rst index 15d6210..d922b3e 100644 --- a/src/research/index.rst +++ b/src/research/index.rst @@ -39,29 +39,45 @@ If you use ActivityWatch in published work, please cite the software: The repository also contains a ``CITATION.cff``, which GitHub renders as a "Cite this repository" button. -Studies using ActivityWatch ---------------------------- +Studies and publications +------------------------ An incomplete list, maintained so that researchers choosing an instrument can see prior use. ActivityWatch typically appears in methods sections rather than titles or abstracts, so it is -largely invisible to citation indexes — if you have used it and are not listed, please tell us. +largely invisible to citation indexes — if you have used it and are not listed, please +tell us. + +Used as a data-collection instrument +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Psychological Wellbeing, Sleep, and Video Gaming: Analyses of Comprehensive Digital - Traces** — Oxford Internet Institute (Ballou, Földes, Hakman, Vuorre, Magnusson, Przybylski), - Stage 1 Registered Report, 2025. ActivityWatch used as the Android data-collection channel - for 2,000+ participants over three months. + Traces** — Oxford Internet Institute (Ballou, Földes, Hakman, Vuorre, Magnusson, + Przybylski), Stage 1 Registered Report, 2025. ActivityWatch is the Android data-collection + channel for 2,000+ participants over three months, alongside console and storefront + telemetry. - **On/Off** — imec-mict-UGent (Vanden Abeele, Perneel, Van Gaeveren), the DISCONNECT ERC - citizen-science panel. ActivityWatch used for opt-in laptop and PC collection, documented in - the study's participant information and privacy materials. -- **Traces as Data** — Parry & Klingelhoefer, handbook chapter, 2025. Named as an exemplar - desktop-logging tool. -- **Sabermetrics for Cyber** — Rivera, Booz & Hammerstein, ECCWS 2025. Used as an instrument. -- **Activity Frames** — Iyamu, 2026 (arXiv:2608.05784). -- Theses: Kroček (University of South Bohemia, 2020), Kraus (Czech Technical University in - Prague, 2021), Panchuk (NURE Kharkiv, 2026). - -Further deployments are known but unpublished or not yet listed here, including at the -University of Maryland iSchool, MIT Media Lab, Clemson University, and Lund University's IIIEE. + citizen-science panel. Used for opt-in laptop and PC collection, documented in the study's + participant information and privacy materials. +- **Sabermetrics for Cyber** — Rivera, Booz & Hammerstein (CMU SEI), ECCWS 2025. + +Discussed, compared or built upon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These cite ActivityWatch without using it to collect their data. + +- **Traces as Data** — Parry & Klingelhoefer, handbook chapter, 2025. Names ActivityWatch as + an exemplar desktop-logging tool. +- **Activity Frames** — Iyamu, 2026 (`arXiv:2608.05784 `_). + Cites ActivityWatch once as related work, and runs its own capture pipeline. +- Student theses building on or integrating ActivityWatch: Kroček (University of South + Bohemia, 2020), Kraus (Czech Technical University in Prague, 2021), Panchuk (NURE Kharkiv, + 2026). + +Unpublished or unlisted deployments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Known deployments that have not produced a listed publication, including the University of +Maryland iSchool, MIT Media Lab, Clemson University, and Lund University's IIIEE. If you are running or planning a study, please get in touch. We are glad to help scope the instrument, and we keep a list of studies that have used ActivityWatch. diff --git a/src/research/participant-instructions.rst b/src/research/participant-instructions.rst index c773a33..658692d 100644 --- a/src/research/participant-instructions.rst +++ b/src/research/participant-instructions.rst @@ -96,9 +96,25 @@ Notes for researchers A few things that reliably cause support questions: -- **Two buckets is correct**, not a symptom of a double installation: one window watcher and - one AFK watcher. Four rows would mean the participant opened the standard dashboard on port - 5600 instead. +- **Filtering happens at capture, not at export.** The watcher classifies browser titles + into study categories and strips URLs *before* the event is recorded, so live Raw Data + already shows categories rather than real titles. What live Raw Data still shows is the + **real hostname**: that is rewritten to ``research-participant`` on export only. A + researcher comparing the dashboard to an export will see the hostname change, and nothing + else. +- **The export fails closed, and that is the alarming one.** If the Research Edition was + installed over an existing ActivityWatch database, the old unfiltered events are still + there, and the export refuses rather than shipping them. The message says to reinstall on + a clean profile. Tell participants to install the Research Edition on a machine that has + no prior ActivityWatch database, or expect this at the end of the study, when there is no + time left to re-collect. +- **Two buckets is the default**, not a double installation: one window watcher and one AFK + watcher. Do not use the row count to tell the Research Edition from a standard install -- + a standard installation also shows two buckets, and the two run as separate servers, so + opening port 5600 does not add rows to the 5667 view. Diagnose by the **Research Edition** + badge and port **5667**. Buckets are created per watcher and per host + (see :doc:`the data model `), so extra watchers or a hostname + change can add rows on either server. - **Use "Export all buckets as JSON", not the per-row menu.** The three-dot menu on a row exports a single bucket. Participants following that route upload two files, or silently omit AFK data. @@ -115,5 +131,3 @@ A few things that reliably cause support questions: their screen does not show. - **The exported filename is fixed.** It cannot carry a participant number, so your upload form needs a field or a per-participant link. -- **Live Raw Data is unsanitised by design.** The rewriting to ``research-participant`` - happens in the export.