Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@SRichner
SRichner committed Mar 7, 2024
1 parent 8b838e7 commit 2cbbcd0
Showing 1 changed file with 41 additions and 0 deletions.
41 changes: 41 additions & 0 deletions documentation/RESEARCH.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,47 @@ To customize PersonalAnalytics for your research study, please consider the foll
3. (optional) If you require further customizations, you can create them in the code (see [Contributions Guide](#contributions-guide)).
4. Use Github Actions (see [build.yml](https://github.com/HASEL-UZH/PersonalAnalytics/blob/feature/electron/.github/workflows/build.yml)) to build and deploy PersonalAnalytics and allow your participants to use it. Using the method, PersonalAnalytics can automatically update your participants' installations with new releases

## General Configuration of PersonalAnalytics (edit in `study.config.ts`)
| Parameter | Description | Change Required | Default Value |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `name` | The name of the study. This is shown in various places of PersonalAnalytics, such as the PersonalAnalytics' menu icon tooltip, the experience sampling and when exporting the study data. | ✅ | |
| `shortDescription` | A short description of the study. This is shown during the onboarding process, in the about page, and when exporting the study data. | ✅ | |
| `infoUrl` | A URL to a website that provides more information about the study. This is shown during the onboarding process, in the about page and when exporting the study data. | ✅ | |
| `privacyPolicyUrl` | A URL to a website that provides the privacy policy of the study. This is shown during the onboarding process, in the about page and when exporting the study data. | ✅ | |
| `uploadUrl` | A URL to a service where participants can upload their study data. This is shown when exporting the study data. | ✅ | |
| `contactName` | The name of the person that participants can contact. This is shown during the onboarding process, in the about page, when exporting the study data, in case of errors and in the application's menu when requesting help or reporting an issue. | ✅ | |
| `contactEmail` | An email address that participants can use to contact the study organizers. This is shown during the onboarding process, in the about page, when exporting the study data, in case of errors and in the application's menu when requesting help or reporting an issue. | ✅ | |
| `subjectIdLength` | The length of the subject ID that is generated for each participant. This is used to identify the participant's data. | | `6` |
| `dataExportEnabled` | Whether the participant should be able to export their data. If enabled, participants can export their study data through the application's menu. | | `true` |

### Tracker Configuration (edit `trackers` in `study.config.ts`)
#### WindowsActivityTracker
| Parameter | Description | Change Required | Default Value |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `enabled` | Whether the WindowsActivityTracker should be enabled. If enabled, the WindowsActivityTracker will collect data about the participant's application usage. | | `true` |
| `intervalInMs` | The interval in milliseconds at which the WindowsActivityTracker should collect data. | | `1000` |
| `trackUrls` | Whether the WindowsActivityTracker should track the URLs of the websites that the participant visits. On macOS: If this is enabled, participants need to enable the accessibility permission through the system settings. (They will be prompted to do so when running the application for the first time.) | | `false` |
| `trackWindowTitles` | Whether the WindowsActivityTracker should track the titles of the windows that the participant uses. On macOS: If this is enabled, participants need to enable the screen recording permission through the system settings. (They will be prompted to do so when running the application for the first time.) | | `true` |

#### UserInputTracker
| Parameter | Description | Change Required | Default Value |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `enabled` | Whether the UserInputTracker should be enabled. If enabled, the UserInputTracker will collect data about the participant's keyboard and mouse input. | | `true` |
| `intervalInMs` | The interval in milliseconds at which the UserInputTracker collects and stores the aggregated data. | | `10000` |

#### ExperienceSamplingTracker
| Parameter | Description | Change Required | Default Value |
|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|
| `enabled` | Whether the ExperienceSamplingTracker should be enabled. If enabled, the ExperienceSamplingTracker will prompt the participant to self-report on one or several questions at customizable times (see configuration below). | | `true` |
| `intervalInMs` | The interval in milliseconds at which the ExperienceSamplingTracker should prompt the participant to self-report. | | `1000*60*60*3` (3 hours) |
| `samplingRandomization` | Wether the ExperienceSamplingTracker should include a randomization for the time at which the participant is prompted to self-report. A value between 0 and 1. If enabled (value bigger than 0), the ExperienceSamplingTracker will randomly calculate a value that is between `intervalInMs` plus/minus `intervalInMs * samplingRanomization` | | `0.1` |
| `scale` | The questions scale. This applies to all questions. | | `7` |
| `questions` | An array of questions that the participant should self-report on. Each question has a `text` and a `scale` property. The `text` property is the question that the participant should answer. The `scale` property is the scale that the participant should use to answer the question. | ✅ | |
| `responseOptions` | An array of arrays with labels for the Likert-scale question. This can be either two labels that will be displayed on the left and right (e.g., `['strongly disagree', 'strongly agree']`) or three labels (e.g., `['strongly disagree', 'neutral', 'strongly agree']`). | ✅ | |



// show a checkmark or a cross

# Contributions Guide
Anyone is welcome to contribute to PersonalAnalytics by extending it with new trackers or improving existing ones.
Expand Down

0 comments on commit 2cbbcd0

Please sign in to comment.