Merge pull request #294 from HASEL-UZH/feature/electron

Updated documentation

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)
@@ -37,11 +38,23 @@ In 2024, we've revived the project in creating a multi-platform app using TypeSc
 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.
+
+
+## ↪️ Dependencies
+This project uses [PA.WindowsActivityTracker](https://github.com/HASEL-UZH/PA.WindowsActivityTracker) and [PA.UserInputTracker](https://github.com/HASEL-UZH/PA.UserInputTracker/) as its main data trackers.
+For the full list of dependencies, consider [package.json](./src/electron/package.json).

documentation/INSTALLATION.md

@@ -2,13 +2,13 @@
 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.
 
 ## How to install PersonalAnalytics on Windows
-1. Visit https://hasel.dev/pa
+1. Visit https://hasel.dev/pa (or use the link provided to you by the researchers)
 2. Select the Windows version (exe-file)
 3. Wait for the download to complete
 4. Allow the install-file (exe) to be downloaded in case your browser blocks it
 5. Double click the downloaded file and follow the installer
-6. Select "Run PersonalAnalytics"
-7. Follow the Onboarding wizard that explains the study, collected data and how to use PersonalAnalytics
+6. Select "Run PersonalAnalytics" before closing the installer
+7. Follow the Onboarding-wizard that explains the study, collected data and how to use PersonalAnalytics
 8. Access PersonalAnalytics anytime through the context-menu in the taskbar icon
 
 The following video shows the steps in action:
@@ -17,8 +17,20 @@ The following video shows the steps in action:
 
 
 ## How to install PersonalAnalytics on macOS
+1. Visit https://hasel.dev/pa (or use the link provided to you by the researchers)
+2. Select the macOS version (dmg-file)
+3. Wait for the download to complete
+4. Open the downloaded instller and drag the PersonalAnalytics-app to your Applications folder
+5. (optional) Click "Open" in case a warning is shown that the app was downloaded from the internet
+6. After the installation completes, follow the Onboarding-wizard, which explains the study, collected data and how to use PersonalAnalytics
+7. On the second page, grant PersonalAnalytics the permissions it requires to function corectly
+8. Note that you might need to manually quit and restart PersonalAnalytics after giving permission
+9. Access PersonalAnalytics anytime through the context-menu in the menubar icon
+
+The following video shows the steps in action:
+
+[![How to install PersonalAnalytics on macOS](https://markdown-videos-api.jorgenkh.no/youtube/ovfRzp3Ksgk)](https://youtu.be/ovfRzp3Ksgk)
 
-<!-- tbd: Sebastian -->
 
 ## Using PersonalAnalytics
 For the majority of the time, PersonalAnalytics is running nonintrusively in the background.

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.