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/

{
  "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=

{
  "average_completion_time": 180.5,
  "fastest_completion": 45.0,
  "slowest_completion": 600.0,
  "total_completed": 50
}

GET /api/surveys/api/analytics/abandonment/

{
  "total_abandoned": 15,
  "abandonment_rate": 23.08,
  "average_questions_before_abandonment": 3.5
}

GET /api/surveys/api/analytics/hourly-activity/?days=7

[
  {
    "hour": 9,
    "surveys_sent": 10,
    "surveys_opened": 5,
    "surveys_completed": 3
  }
]

GET /api/surveys/api/analytics/patient-timeline/<patient_id>/

[
  {
    "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

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

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

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

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:

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