# Post-Study Survey Feature Guide

## Overview

The Post-Study Survey feature allows researchers to gather qualitative feedback from participants after they complete a UX research study. This feature integrates seamlessly into your existing card sort, tree testing, and prototype testing workflows.

---

## Features

✓ **Flexible Question Sets**: 3 default questions + 2 optional custom questions
✓ **Per-Study Configuration**: Each study can have its own survey or none at all
✓ **Smart Display**: Surveys appear automatically on the thank you page
✓ **Response Tracking**: View all responses with timestamps
✓ **CSV Export**: Download survey results for further analysis
✓ **Optional Participation**: Participants can skip the survey if desired

---

## Default Survey Questions

1. **"Were any terms unclear?"** - Identifies confusing terminology
2. **"Which category was hardest to name?"** - Reveals categorization challenges
3. **"Any missing items you expected?"** - Discovers content gaps

You can customize these questions and add up to 2 additional custom questions.

---

## Setup Instructions

### Step 1: Create the Database Tables

1. Navigate to `/scripts/setup_survey_tables.php` in your browser
2. You'll see confirmation messages when the tables are created
3. This only needs to be done once

### Step 2: Add a Survey to a Study

1. Go to **Dashboard** → **Studies**
2. Click the **📋 Survey** button on any study card
3. You'll see the Survey Management page

### Step 3: Configure Survey Questions

On the Survey Management page:

1. **Edit the default questions** to match your research goals
2. **Add custom questions** (optional) - leave blank if not needed
3. **Toggle "Active" checkbox** to enable/disable the survey
4. Click **Create Survey** or **Update Survey**

### Step 4: Activate Your Study

Make sure your study status is set to "Active" so participants can access it.

---

## How It Works (Participant Flow)

1. **Participant completes the study** (card sort, tree test, or prototype test)
2. **Redirected to thank you page** with the survey (if active)
3. **Fills out survey questions** (all questions are optional)
4. **Clicks "Submit Feedback"** or skips the survey
5. **Final thank you message** appears

---

## Viewing Survey Results

### From the Reports Dashboard

1. Go to **Reports & Analytics**
2. Find the study you want to analyze
3. If survey responses exist, you'll see a **Survey Responses** stat card
4. Click **📋 Survey Results (X)** button to view all responses

### Survey Results Page

Shows:
- **Total response count**
- **Completion rate** (% of responses with at least one answer)
- **Individual responses** with timestamps
- **Export to CSV** button for data analysis

---

## Managing Surveys

### Edit a Survey

1. Go to **Studies** → click **📋 Survey** on any study
2. Modify questions as needed
3. Click **Update Survey**

### Temporarily Disable a Survey

1. Go to the survey management page
2. Uncheck **"Show this survey to participants (active)"**
3. Click **Update Survey**

The survey will be hidden from participants but responses are preserved.

### Delete a Survey

1. Go to the survey management page
2. Click **🗑️ Delete Survey**
3. Confirm deletion (this also deletes all responses)

⚠️ **Warning**: Deleting a survey removes all collected responses permanently.

---

## Data Storage

### Database Tables

**study_surveys**
- Stores survey configuration (questions, active status)
- One survey per study (unique constraint)

**survey_responses**
- Stores participant responses
- Links to sessions and studies
- Includes submission timestamps

### Data Retention

- Responses are linked to sessions (if available)
- Deleting a study deletes its survey and all responses (cascade)
- Deleting a survey deletes all its responses (cascade)

---

## Export Options

### CSV Export

From the Survey Results page:

1. Click **📥 Export to CSV**
2. File downloads with format: `survey_results_study_X_YYYY-MM-DD.csv`
3. Includes:
   - Response number
   - Submission timestamp
   - All question answers

Use the CSV for:
- Qualitative analysis
- Thematic coding
- External tools (Excel, SPSS, NVivo, etc.)

---

## Best Practices

### Question Design

✓ **Keep questions open-ended** to gather rich insights
✓ **Focus on specific aspects** of the user experience
✓ **Use clear, simple language** that participants understand
✓ **Limit total questions** to avoid survey fatigue (3-5 is ideal)

### When to Use Surveys

**Good Use Cases:**
- Gathering qualitative feedback on terminology
- Understanding participant thought processes
- Identifying missing content or features
- Collecting improvement suggestions

**Not Recommended:**
- As a replacement for quantitative data
- For demographic information (use separate screening)
- For very long-form responses (consider interviews instead)

### Analyzing Results

1. **Look for patterns** across multiple responses
2. **Identify common themes** in feedback
3. **Combine with quantitative data** for richer insights
4. **Follow up** with participants for clarification if needed

---

## Troubleshooting

### Survey Not Appearing

**Check:**
- Is the survey marked as "Active"?
- Is the study status "Active"?
- Did the tables get created? (Run setup script again)

### Responses Not Saving

**Check:**
- Browser console for JavaScript errors
- Database permissions
- Survey ID and Study ID match

### Survey Button Not Showing

**Check:**
- Are you viewing the Studies page (`/public/studies/index.php`)?
- Are you logged in as a researcher?

---

## Technical Details

### API Endpoints

**GET** `/public/api/survey_get.php?study_id=X`
- Returns active survey for a study
- Returns null if no active survey

**POST** `/public/api/survey_submit.php`
- Saves survey responses
- Requires: `survey_id`, `study_id`, `responses` array

### Files Modified

- `public/thankyou.php` - Survey display and submission
- `public/studies/index.php` - Added Survey button
- `public/reports/index.php` - Added survey stats and link
- `includes/schema.php` - Added new tables to whitelist

### Files Created

- `public/studies/survey.php` - Survey management interface
- `public/reports/survey_results.php` - Survey results viewer
- `public/api/survey_get.php` - Get survey API
- `public/api/survey_submit.php` - Submit response API
- `scripts/survey_setup.sql` - SQL schema
- `scripts/setup_survey_tables.php` - Migration script

---

## Database Schema

```sql
study_surveys (
  id INT PRIMARY KEY AUTO_INCREMENT,
  study_id INT UNIQUE,
  question_1 VARCHAR(500),
  question_2 VARCHAR(500),
  question_3 VARCHAR(500),
  custom_question_1 VARCHAR(500),
  custom_question_2 VARCHAR(500),
  is_active TINYINT(1),
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

survey_responses (
  id INT PRIMARY KEY AUTO_INCREMENT,
  survey_id INT,
  session_id INT,
  study_id INT,
  participant_token VARCHAR(255),
  response_1 TEXT,
  response_2 TEXT,
  response_3 TEXT,
  response_4 TEXT,
  response_5 TEXT,
  submitted_at TIMESTAMP
)
```

---

## Future Enhancements (Not Yet Implemented)

Potential features for future development:
- Multiple choice questions
- Rating scales (1-5, Likert)
- Conditional questions (branching logic)
- Question randomization
- Multi-language support
- Response anonymization options
- Sentiment analysis
- Word cloud generation

---

## Support

If you encounter issues or have questions about the survey feature, check:

1. This documentation
2. Database tables exist (`study_surveys`, `survey_responses`)
3. Browser console for errors
4. PHP error logs on your server

---

**Last Updated**: October 27, 2025
**Version**: 1.0