# In-Study Feedback Feature - Complete Guide

## Overview

The In-Study Feedback feature allows participants to provide feedback **during** the card sort exercise, capturing their thoughts, confusion, or insights in real-time. A floating feedback button appears on the right side of the screen during the study, allowing participants to submit feedback without interrupting their workflow.

## Key Features

- ✅ **Floating Feedback Button**: Unobtrusive circular button on the right side of the screen
- ✅ **Real-Time Feedback**: Participants can provide feedback while actively working
- ✅ **Customizable Questions**: Configure text, textarea, or 5-star rating questions
- ✅ **Non-Intrusive**: Feedback is optional and doesn't interrupt the card sort
- ✅ **Comprehensive Reports**: View all feedback with rating analytics and visualizations

## Setup Instructions

### Step 1: Enable Feedback for a Study

1. Go to **Studies** → Select your study → **Edit Study**
2. Scroll down to the **"Enable In-Study Feedback"** section
3. Check the ☑️ **"Enable In-Study Feedback"** checkbox
4. Click **"Save Changes"**

### Step 2: Configure Feedback Questions

1. After enabling feedback, click **"⚙️ Configure Feedback Questions"**
2. Click **"+ Add Question"** to create feedback questions
3. For each question:
   - Enter the question text
   - Select question type:
     - **Short Text**: One-line text input
     - **Long Text (Paragraph)**: Multi-line textarea
     - **5-Star Rating**: Star rating scale (1-5)
   - Optionally mark as required (participants must answer before submitting)
4. Click **"Save Changes"** or **"Add Question"**
5. Repeat to add more questions

**Example Questions:**
- "What was confusing or unclear during this exercise?" (Long Text)
- "How easy was it to organize these cards?" (5-Star Rating)
- "Any suggestions for improvement?" (Long Text)
- "Did any card placement feel uncertain?" (Long Text)

### Step 3: Participant Experience

When participants start the card sort:

1. A purple circular button (💬) appears in the **bottom-right corner** of the screen
2. Participants can click it at any time during the sort
3. A modal opens with your configured feedback questions
4. Participants fill out and submit their feedback
5. They can submit feedback **multiple times** during the study if needed
6. The button remains visible until they finish the card sort

### Step 4: View Feedback Results

1. Go to **Reports** → Select your study
2. Click the **"💬 In-Study Feedback"** button (shows count if feedback exists)
3. Review feedback organized by question:
   - **Rating questions** show:
     - Average rating
     - Star distribution graph
     - Individual ratings with timestamps
   - **Text questions** show:
     - All responses listed
     - Submission timestamps
     - Full text content
4. Export data from the main export menu if needed

## Database Schema

The feature uses two new tables:

### `in_study_feedback_questions`
Stores researcher-configured feedback questions for each study.

**Columns:**
- `id` - Primary key
- `study_id` - Foreign key to studies
- `question_text` - The question text
- `question_type` - Type: 'text', 'textarea', 'rating'
- `is_required` - Whether the question is required (0 or 1)
- `sequence` - Display order
- `created_at` - Timestamp

### `in_study_feedback`
Stores participant feedback responses.

**Columns:**
- `id` - Primary key
- `study_id` - Foreign key to studies
- `session_id` - Foreign key to sessions (nullable)
- `question_text` - The question that was answered
- `answer_text` - Text response (nullable)
- `rating` - Rating value 1-5 (nullable)
- `submitted_at` - Timestamp

## API Endpoints

### `GET /public/api/in_study_feedback_questions.php`
Fetch feedback questions for a study.

**Parameters:**
- `study_id` (required)

**Response:**
```json
{
  "ok": true,
  "questions": [
    {
      "id": 1,
      "study_id": 5,
      "question_text": "What was confusing?",
      "question_type": "textarea",
      "is_required": 0,
      "sequence": 0
    }
  ]
}
```

### `POST /public/api/in_study_feedback_questions.php`
Create a new feedback question (researcher only).

**Body:**
```json
{
  "study_id": 5,
  "question_text": "What was confusing?",
  "question_type": "textarea",
  "is_required": 0,
  "sequence": 0
}
```

### `PUT /public/api/in_study_feedback_questions.php`
Update a feedback question (researcher only).

**Body:**
```json
{
  "id": 1,
  "question_text": "Updated question text",
  "question_type": "text",
  "is_required": 1
}
```

### `DELETE /public/api/in_study_feedback_questions.php`
Delete a feedback question (researcher only).

**Body:**
```json
{
  "id": 1
}
```

### `POST /public/api/in_study_feedback_submit.php`
Submit participant feedback responses.

**Body:**
```json
{
  "study_id": 5,
  "session_id": 123,
  "responses": [
    {
      "question_text": "What was confusing?",
      "answer_text": "The categories weren't clear",
      "rating": null
    },
    {
      "question_text": "How easy was it?",
      "answer_text": "",
      "rating": 4
    }
  ]
}
```

## Files Modified/Created

### New Files:
- `scripts/in_study_feedback_setup.sql` - Database migration
- `public/api/in_study_feedback_questions.php` - Questions CRUD API
- `public/api/in_study_feedback_submit.php` - Submit feedback API
- `public/studies/feedback_builder.php` - Feedback question builder UI
- `public/reports/feedback_results.php` - Feedback results report
- `IN_STUDY_FEEDBACK_GUIDE.md` - This guide

### Modified Files:
- `includes/schema.php` - Added feedback tables to allowed tables
- `public/studies/edit.php` - Added feedback toggle and configuration link
- `public/studies/create.php` - Added feedback toggle
- `public/participant.php` - Added floating feedback button and modal
- `public/reports/index.php` - Added feedback results link

## Best Practices

1. **Keep questions focused**: Ask specific questions about the card sort experience
2. **Mix question types**: Use ratings for quantitative data and text for qualitative insights
3. **Don't overwhelm**: 3-5 questions maximum for in-study feedback
4. **Make most optional**: Only mark truly critical questions as required
5. **Test first**: Preview the feedback widget as a researcher before going live

## Troubleshooting

### Feedback button not showing
- Ensure "Enable In-Study Feedback" is checked in study settings
- Verify at least one feedback question has been created
- Check browser console for JavaScript errors

### Database errors
- Run the migration: Upload `scripts/in_study_feedback_setup.sql` to your web host
- Execute the SQL statements in phpMyAdmin or your database tool
- Verify the `enable_feedback` column exists in the `studies` table

### Questions not saving
- Check researcher authentication (must be logged in as researcher)
- Verify API endpoints are accessible
- Check browser console for error messages

## Support

If you encounter issues:
1. Check the browser console for JavaScript errors
2. Verify database tables were created correctly
3. Ensure all files were uploaded to the web server
4. Test in researcher preview mode first

---

**Feature Version**: 1.0  
**Last Updated**: October 31, 2025