HH/docs/SURVEY_TRACKING_GUIDE.md

# Survey Tracking System - Complete Implementation Guide

## Overview

The survey tracking system has been successfully implemented to track patient survey engagement through their journey. This system captures detailed metrics about survey delivery, opens, completion, and abandonment.

## What Was Implemented

### 1. Database Models

#### Enhanced SurveyInstance Model
Added tracking fields to track survey engagement:

- **open_count**: Number of times the survey link was opened
- **last_opened_at**: Timestamp of the last time the survey was opened
- **time_spent_seconds**: Total time spent on the survey in seconds
- **Enhanced status choices**:
  - `sent` - Sent (Not Opened)
  - `viewed` - Viewed (Opened, Not Started)
  - `in_progress` - In Progress (Started, Not Completed)
  - `completed` - Completed
  - `abandoned` - Abandoned (Started but Left)
  - `expired` - Expired
  - `cancelled` - Cancelled

#### New SurveyTracking Model
Tracks detailed events during survey interaction:

- **event_type**: Type of tracking event
  - `page_view` - Page View
  - `survey_started` - Survey Started
  - `question_answered` - Question Answered
  - `survey_abandoned` - Survey Abandoned
  - `survey_completed` - Survey Completed
  - `reminder_sent` - Reminder Sent
- **time_on_page**: Time spent on current page in seconds
- **total_time_spent**: Total time spent in survey in seconds
- **current_question**: Current question number being viewed
- **user_agent**: Browser user agent string
- **ip_address**: User's IP address
- **device_type**: Device type (desktop, mobile, tablet)
- **browser**: Browser name and version
- **country**: Country from IP geolocation
- **city**: City from IP geolocation
- **metadata**: Additional tracking metadata (JSON field)

### 2. Analytics Functions

#### get_survey_engagement_stats()
Returns overall survey engagement metrics:
- **total_sent**: Total number of surveys sent
- **total_opened**: Number of surveys that were opened
- **total_completed**: Number of surveys completed
- **open_rate**: Percentage of sent surveys that were opened
- **completion_rate**: Percentage of sent surveys that were completed
- **response_rate**: Percentage of opened surveys that were completed

#### get_patient_survey_timeline(patient_id)
Returns timeline of all surveys for a specific patient:
- When each survey was sent
- When it was opened
- When it was completed
- Time taken to complete each survey

#### get_survey_completion_times(template_id=None)
Returns completion time statistics:
- Average time to complete
- Fastest completion
- Slowest completion
- Can filter by survey template

#### get_survey_abandonment_analysis()
Analyzes survey abandonment:
- **total_abandoned**: Number of abandoned surveys
- **abandonment_rate**: Percentage of started surveys that were abandoned
- Common abandonment points
- **average_questions_before_abandonment**: Average questions answered before abandonment

#### get_hourly_survey_activity(days=7)
Returns hourly activity data:
- Surveys sent per hour
- Surveys opened per hour
- Surveys completed per hour
- Useful for identifying peak activity times

### 3. API Endpoints

#### Analytics Endpoints

**GET /api/surveys/api/analytics/engagement/**
```json
{
  "total_sent": 100,
  "total_opened": 75,
  "total_completed": 50,
  "open_rate": 75.0,
  "completion_rate": 50.0,
  "response_rate": 66.67
}
```

**GET /api/surveys/api/analytics/completion-times/?template_id=<id>**
```json
{
  "average_completion_time": 180.5,
  "fastest_completion": 45.0,
  "slowest_completion": 600.0,
  "total_completed": 50
}
```

**GET /api/surveys/api/analytics/abandonment/**
```json
{
  "total_abandoned": 15,
  "abandonment_rate": 23.08,
  "average_questions_before_abandonment": 3.5
}
```

**GET /api/surveys/api/analytics/hourly-activity/?days=7**
```json
[
  {
    "hour": 9,
    "surveys_sent": 10,
    "surveys_opened": 5,
    "surveys_completed": 3
  }
]
```

**GET /api/surveys/api/analytics/patient-timeline/<patient_id>/**
```json
[
  {
    "survey_id": "uuid",
    "survey_name": "Patient Satisfaction Survey",
    "sent_at": "2024-01-15T10:00:00Z",
    "opened_at": "2024-01-15T14:30:00Z",
    "completed_at": "2024-01-15T14:35:00Z",
    "time_to_open": "4h 30m",
    "time_to_complete": "5m",
    "status": "completed"
  }
]
```

#### Tracking Endpoints

**GET /api/surveys/api/tracking/<survey_instance_id>/**
Returns all tracking events for a survey instance

**POST /api/surveys/api/tracking/<survey_instance_id>/**
Submit tracking events (automatically done by frontend)

### 4. Admin Interface

Enhanced admin panels for survey tracking:

1. **SurveyInstance Admin** (http://localhost:8000/admin/surveys/surveyinstance/)
   - View open counts
   - View time spent
   - View last opened timestamp
   - Filter by status
   - Filter by time to complete

2. **SurveyTracking Admin** (http://localhost:8000/admin/surveys/surveytracking/)
   - View all tracking events
   - Filter by event type
   - Filter by device/browser
   - View geographic data
   - Export tracking data

## How Tracking Works

### Automatic Tracking Flow

1. **Survey Sent** (via Patient Journey)
   - SurveyInstance created with status='sent'
   - sent_at timestamp set

2. **Patient Opens Survey Link**
   - Frontend records page_view event
   - open_count incremented on SurveyInstance
   - last_opened_at updated
   - Status changes to 'viewed'

3. **Patient Starts Survey**
   - Frontend records survey_started event
   - Status changes to 'in_progress'
   - Time tracking begins

4. **Patient Answers Questions**
   - Each answer records question_answered event
   - Current question number tracked
   - Time spent on each question recorded

5. **Patient Completes Survey**
   - Frontend records survey_completed event
   - time_spent_seconds calculated and saved
   - Status changes to 'completed'
   - Completion time calculated

6. **Patient Abandons Survey**
   - If patient leaves without completing
   - Frontend records survey_abandoned event (after timeout)
   - Status changes to 'abandoned'
   - Questions answered saved

### Device & Browser Tracking

The system automatically detects:
- Device type (desktop, mobile, tablet)
- Browser name and version
- Operating system
- User agent string
- IP address
- Country and city (via geolocation)

## Key Metrics You Can Now Track

### 1. Delivery Metrics
- **When the survey link is sent** (sent_at timestamp)
- Total surveys sent per campaign
- Sent status tracking

### 2. Open Metrics
- **How many patients opened the link** (open_count > 0)
- **When they opened it** (last_opened_at timestamp)
- Time from send to first open
- Open rate (opened / sent)

### 3. Completion Metrics
- **How many patients filled the survey** (status='completed')
- **When they completed it** (completed_at timestamp)
- Time from send to completion
- Time from open to completion (time_spent_seconds)
- Completion rate (completed / sent)
- Response rate (completed / opened)

### 4. Abandonment Metrics
- **How many opened but didn't complete** (status='abandoned')
- Abandonment rate (abandoned / started)
- Average questions answered before abandonment
- Common abandonment points

### 5. Timing Metrics
- Average time to complete
- Fastest completion time
- Slowest completion time
- Peak engagement hours

## Usage Examples

### Example 1: Get Overall Survey Performance

```python
from apps.surveys.analytics import get_survey_engagement_stats

stats = get_survey_engagement_stats()
print(f"Total sent: {stats['total_sent']}")
print(f"Open rate: {stats['open_rate']}%")
print(f"Completion rate: {stats['completion_rate']}%")
```

### Example 2: Track Specific Patient's Survey Journey

```python
from apps.surveys.analytics import get_patient_survey_timeline

timeline = get_patient_survey_timeline(patient_id="123")
for survey in timeline:
    print(f"Survey: {survey['survey_name']}")
    print(f"Sent: {survey['sent_at']}")
    print(f"Opened: {survey['opened_at']}")
    print(f"Completed: {survey['completed_at']}")
    print(f"Time to complete: {survey['time_to_complete']}")
```

### Example 3: Analyze Completion Times

```python
from apps.surveys.analytics import get_survey_completion_times

times = get_survey_completion_times()
print(f"Average time: {times['average_completion_time']} seconds")
print(f"Fastest: {times['fastest_completion']} seconds")
print(f"Slowest: {times['slowest_completion']} seconds")
```

### Example 4: Find Abandonment Patterns

```python
from apps.surveys.analytics import get_survey_abandonment_analysis

abandonment = get_survey_abandonment_analysis()
print(f"Abandonment rate: {abandonment['abandonment_rate']}%")
print(f"Avg questions before abandon: {abandonment['average_questions_before_abandonment']}")
```

## Testing

Run the test script to verify the system:

```bash
uv run python test_survey_tracking.py
```

Expected output:
- ✓ All models loaded successfully
- ✓ All tracking fields present
- ✓ All analytics functions working
- ✓ API endpoints ready

## Frontend Integration

The public survey form template (`templates/surveys/public_form.html`) includes automatic tracking:

- Page view events are recorded on load
- Survey start events are recorded on first interaction
- Question answer events are recorded on each submission
- Completion events are recorded on final submission
- Device/browser info automatically captured

## Reports Available

### Via Admin
1. Go to /admin/surveys/
2. Use filters to view:
   - Surveys by status
   - Surveys by time to complete
   - Survey tracking events by type
   - Surveys by device/browser

### Via API
Access comprehensive analytics through the API endpoints listed above.

### Custom Reports
You can create custom reports using the analytics functions in `apps/surveys/analytics.py`.

## Performance Considerations

- Database indexes on tracking fields for fast queries
- Efficient aggregation queries for statistics
- No impact on survey performance (tracking is asynchronous)

## Privacy & Data Protection

- IP addresses stored for geographic analysis only
- User agent strings used for device detection
- No personally identifiable information stored in tracking
- All data stored securely in database

## Next Steps

1. **Start Sending Surveys**: Use patient journeys to send surveys
2. **Monitor Engagement**: Check admin panel for real-time stats
3. **Analyze Data**: Use API endpoints for detailed analysis
4. **Optimize**: Use abandonment analysis to improve survey design
5. **Report**: Create custom dashboards based on the metrics

## Support

For questions or issues:
- Check the implementation guide: `docs/SURVEY_TRACKING_IMPLEMENTATION.md`
- Review the analytics module: `apps/surveys/analytics.py`
- Check API views: `apps/surveys/analytics_views.py`

---

**Status**: ✅ Complete and Tested
**Date**: January 21, 2026
**Version**: 1.0