Merge branch 'feature/electron' of https://github.com/HASEL-UZH/Perso…

…nalAnalytics into feature/electron

README.md

@@ -11,7 +11,7 @@ Anyone is welcome to contribute to PersonalAnalytics by extending it with new tr
 ## 🧑‍💻 Installation & Usage as a User
 Anyone may install PersonalAnalytics on their Windows or macOS device to non-intrusively collect computer interaction data, and analyze their activity, time spent and work habits for themselves. In the future, once we'll re-introduce the Retrospection (i.e. visualizations of the collected and self-reported data), it will be much easier to gain insights again.
 
-To install and use PersonalAnalytics, [consider this guide](./documentation/INSTALLATION.md).
+Learn more about how to [install and use PersonalAnalytics](./documentation/INSTALLATION.md).
 
 ## 👩‍🔬 Customization & Usage as a Researcher
 This project was created by and for researchers who want to ask study participants to run PersonalAnalytics on their device to non-intrusively collect **computer interaction data** in a privacy-protected way. As often times, having access to only automatically collected data is often not sufficient, PersonalAnalytics also offers an **experience sampling component**, which allows researchers to ask users to reflect and self-report on one or several questions (e.g. Have I been productive? Am I stressed right now?) at customizable times and using Likert-scales. As all collected data is only stored locally on participants' computers, there is an **export component**, guiding the participant through sharing and potentially obfuscating the captured data, before sharing it with the researchers through their data transfer service of choice. Most settings are configurable in the [study-config]([url](https://github.com/HASEL-UZH/PersonalAnalytics/blob/feature/electron/src/electron/shared/study.config.ts)), everything else can be customized in code.
@@ -21,6 +21,7 @@ Learn more about how to use [PersonalAnalytics for your research project](./docu
 ## 📖 Further Information
 - [Installation & Usage for End Users](./documentation/INSTALLATION.md)
 - [Customization & Usage for Researchers](./documentation/RESEARCH.md)
+- [Reporting an issue or bug](https://github.com/HASEL-UZH/PersonalAnalytics/issues)
 - [Data Collection & Privacy Policy](./documentation/PRIVACY.md)
 - [Contributions](./documentation/RESEARCH.md#contributions-guide)
 - [Information on the old PersonalAnalytics](./documentation/LEGACY.md)
@@ -33,15 +34,21 @@ The original version of PersonalAnalytics for Windows (created by André Meyer)
 In 2024, we've revived the project in creating a multi-platform app using TypeScript and Electron. It is using the TypeScript-versions of our original, most used data trackers, the [WindowsActivityTracker](https://github.com/HASEL-UZH/PA.WindowsActivityTracker/tree/main/typescript) and the [UserInputTracker](https://github.com/HASEL-UZH/PA.UserInputTracker/tree/main/typescript). In addition, it includes an experience sampling component that can ask users to provide self-reports on one or several questions at customizable times. At the moment, the new PersonalAnalytics does NOT yet feature a retrospection, but it's the plan to recreate it in the future.
 
 
-# 🙂 Main Contributors and People Involved
+## 🙂 Main Contributors and People Involved
 This work is carried by the following main contributors: 
 - [Dr. André Meyer](https://www.andre-meyer.ch) (University of Zurich, main contributor to the project)
 - [Prof. Dr. Thomas Fritz](http://www.ifi.uzh.ch/en/seal/people/fritz.html) (University of Zurich)
-- [Chris Satterfield](https://github.com/csatterfield) (contributor to MacOS version)
+- [Sebastian Richner](https://github.com/SRichner) (contributor to new version)
 - [Roy Rutishauser](https://github.com/royru) (contributor to MacOS-legacy version)
+- [Chris Satterfield](https://github.com/csatterfield) (contributor to MacOS-legacy version)
 - [Jan Pilzer](https://github.com/hirse) (contributor to Windows-legacy version)
-- [Sebastian Richner](https://github.com/SRichner) (contributor to new version)
+- [Alexander Lill](https://github.com/alexanderlill) (tester)
+- [Isabelle Cuber](https://github.com/isicu) (tester)
 - Dr. Manuela Züger (prev. University of Zurich, contributor to Windows-legacy version)
 - Dr. Sebastian Müller (prev. University of Zurich, contributor to Windows-legacy version)
 - [Dr. Tom Zimmermann](https://www.microsoft.com/en-us/research/people/tzimmer/) (Microsoft Research)
 - [Prof. Dr. Gail C. Murphy](https://blogs.ubc.ca/gailcmurphy/) (University of British Columbia)
+
+## 📨 Contact
+- You may contact André Meyer ([email protected]) in case of questions on the project.
+- Do not attempt contact in case of questions on a specific study in which you are participating. If you encounter technical issues, create an [issue](https://github.com/HASEL-UZH/PersonalAnalytics/issues), so that the community may offer help.

documentation/PRIVACY.md

@@ -1,11 +1,24 @@
 # Data Storage & Confidentiality
 
-PersonalAnalytics is a Windows and macOS application designed to be installed on knowledge workers computers to non-intrusively collect data about their work and work habits, including application usage, user input, websites visited, files worked on, emails and meetings, amongst others.
+## Goal & Overview
+PersonalAnalytics is a Windows and macOS application designed to be installed on knowledge workers' computers to non-intrusively collect computer interaction data, including user input and application usage data, as well as self-reporte data using an experience sampling component. The idea is that researchers can deploy PersonalAnalytics with study participants to allow them collect data during baseline and intervention phases and help them to answer their research questions. When creating a release of PersonalAnalytics, researchers can configure which data is collected. All data is stored **only locally** and **never automatically shared with the researchers without a user's  explicit consent**. 
 
-All data (tracked and self-reported data) is **stored ONLY locally on the knowledge worker's computer**. It is NOT uploaded to any servers. This also includes stored credentials, e.g. of the Microsoft Office 365 service or Fitbit service. When running, the context menu of the app has a menu item "Open Collected Data" which opens the directory where all the collected data is stored. In most cases, the directory contains a log file (text-file), a database file (pa.dat) and the hashed token for accessing the Microsoft Office 365 service. 
+## Overview over Collected Data
+Currently, there are three data trackers collecting data and storing it locally on user's computers:
+- **User Input Tracker**: User input data stems from mouse (number of clicks, pixels moved and pixels scrolled) and keyboard (number of keystrokes) and is aggregated per interval (e.g. once a minute). Note that the actual keys pressed are _not_ stored (no keylogging!)
+- **Windows Activity Tracker**: The application usage data includes an entry for each time a user switches from one app, website or file to another, storing the time of switch, app name and window title. The application usage is then automatically categorized using [research-based heuristics]([url](https://www.zora.uzh.ch/id/eprint/136503/1/productiveWorkday_TSE17.pdf)) ([source]([url](https://github.com/HASEL-UZH/PA.WindowsActivityTracker/tree/main/typescript/src/mappings))). 
+- **Experience Sampling Tracker**: Researchers can also define one or multiple questions that are shown to users at random intervals and ask to provide a rating to a question, such as on their perceived productivity, well-being, or stress levels. Only the question, rating (e.g. 5/7) and timestamp are stored.
 
-To manually review, modify and delete the collected data, the user needs to open the `pa.dat` file using [SQLite Browser](https://sqlitebrowser.org/).
+## Accessing, Modifying or Deleting the Data
+As mentioned above, all data is stored locally only on participant's machines. Users can access it, by clicking "Open Collected Data" in the taskbar icon (on Windows) or menubar (on macOS) and opening the file `database.sqlite` in a sqlite-compatible database viewer (such as [DB Browser for SQLite](https://sqlitebrowser.org/).
 
-In the settings, the user can enable or disable the different data trackers. In case a user is doing sensitive work, she can temporarily pause PersonalAnalytics (via the context menu) or shut it down completely.
+Should a user want to modify and/or delete their data, they can do so directly in the sqlite-file. No other copies of the data exists, unless the user made them. 
 
-During research studies, the researchers might ask users (i.e. study participants) to share the collected data with the researchers. They might or might not offer to obfuscate the collected data beforehand. This step depends entirely on the researchers and the owners and contributors of this project have **no control and/or responsibility** over this step. They encourage any researchers who use PersonalAnalytics for their research projects, to (1) be very transparent with what data is collected, (2) what the collected data will be used for (once the participants shares it with the researchers), (3) to only collect the absolute minimum of data, (4) to provide participants with a consent form to allow them to give informed consent on the collected data and its usage, and (5) to allow participants to require the deletion of their data.
+## Sharing Collected Data
+In case users are running PersonalAnalytics during a scientific study, the researchers might ask the users (or in this context, participants) to share their data with the reseachers. To that purpose, we recommend using the built-in data obfuscation and export feature, which allows users to understand what the data will be used for as part of the research project, review the collected data and decide which data they want to share and/or obfuscate. Afterwards, an encrypted and password-protected export-file is created which can be shared with the researchers per their instructions. The data export tool can be accessed by clicking "Export Data" in the taskbar icon (on Windows) or menubar (on macOS).
+
+## Note on Using PersonalAnalytics
+Note that the creators of PersonalAnalytics can in no way be held liable against use, misuse or problems that arise from using the app. The app was developed as a public, open-source application that can be freely used and extended (with [correct attribution](https://github.com/HASEL-UZH/PersonalAnalytics/blob/main/documentation/RESEARCH.md). The researchers are responsible for informing users (or participants) of the usage of PersonalAnalytics, collected data and usage of any data that is shared with researchers, as well as data privacy and data security. 
+
+## Questions and Support
+You may contact André Meyer ([email protected]) in case of questions on the project. Do not contact in case of questions on a specific study in which you are participating. If you encounter technical issues, create an [issue]([url](https://github.com/HASEL-UZH/PersonalAnalytics/issues)https://github.com/HASEL-UZH/PersonalAnalytics/issues), so that the community may offer help.

documentation/RESEARCH.md

@@ -62,7 +62,7 @@ Anyone is welcome to contribute to PersonalAnalytics by extending it with new tr
 7. If your pull request is approved, it will be merged into the main repository.
 8. If your pull request is not approved, you can make further changes and push them to your branch. The pull request will be updated automatically.
 
-## Install the dependencies
+### Install the dependencies
 After cloning this repository using your favorite git client, you need to install the dependencies.
 Make sure you use node version >=20. You can install the dependencies by running the following command in the root directory of the project:
 ```bash
@@ -71,13 +71,13 @@ npm install
 ```
 This will install all the dependencies required to build and run PersonalAnalytics. This will also call the `postinstall` script, which will make sure that the native dependencies are built for your platform.
 
-## Starting the application for development
+### Starting the application for development
 To start the application for development, you can run the following command in `src/electron`:
 ```bash
 npm run dev
 ```
 
-## Building the application
+### Building the application
 To build the application, you can run the following command in `src/electron`:
 ```bash
 npm run build
@@ -94,6 +94,9 @@ or for macOS (only on macOS):
 npm run build:mac
 ```
 
+### Testing PersonalAnalytics
+PersonalAnalytics was tested on `Windows 11` and `macOS 14`. It might work on older versions as well.
+
 ## Referencing PersonalAnalytics
 When leveraging PersonalAnalytics for your work or research, please cite it appropriately, by refering to the main publication as well as this repository.