# Attribution Analytics

## Overview

The Attribution page shows which marketing campaigns, sources, mediums, and landing pages are producing form submissions — and, where available, which of those submissions became qualified leads or won/lost opportunities in CareHQ.

## Features

### KPI Cards
- **Total Submissions** — form submissions in the date range
- **Total Leads** — submissions with a lead status (qualified, won, or lost)
- **Qualified Rate** — percentage of submissions that became qualified leads
- **Won Rate** — percentage of submissions that converted to won deals
- **Total Value** — sum of lead values for won deals

### Summary Table
Group submissions by:
- **Campaign** (`utm_campaign`)
- **Source** (`utm_source`)
- **Medium** (`utm_medium`)
- **Landing Page** — the page where the form was submitted
- **Form** — the form name
- **Location** — the CareHQ home/location

Each row shows submissions, qualified, won, lost, conversion rate, and total value. Click a row to drill down into individual submissions.

### Time-Series Chart
A simple bar chart showing daily submission volume for the selected date range.

### CSV Export
Export the current filtered summary view as a CSV file.

## Data Collection

Attribution data is recorded automatically when a form submission is successfully sent to CareHQ. The following data is captured:

- **UTM parameters** from the existing UTM tracking module
- **Referrer and landing page** from the page context
- **Click IDs** (`gclid`, `fbclid`, `msclkid`) from form fields or cookies
- **CareHQ contact ID** from the API response
- **Location/home** from the mapping configuration

## Lead Status Updates

Lead status can be updated in two ways:

### 1. CareHQ Webhook (recommended)
Configure CareHQ to send `contact.status_changed` or `lead.status_changed` webhook events to your site. The plugin will automatically update the lead status in the attribution table.

### 2. Manual Update
Use the REST API endpoint:
```
POST /wp-json/fc/v1/attribution/lead-status
{
  "contact_id": "carehq_contact_id",
  "status": "won",
  "value": 5000
}
```

Valid statuses: `new`, `qualified`, `won`, `lost`, `unknown`

## Privacy / GDPR

- Attribution data contains no PII beyond what's already captured by UTM tracking
- The `carehq_contact_id` is an opaque identifier — no names, emails, or personal data
- Attribution records are automatically deleted when a user requests data erasure (via the existing privacy/erasure hooks)

## Database

Attribution data is stored in the `{prefix}_fc_attribution` table, created on plugin activation. The table includes indexes for common query patterns (date range, UTM fields, lead status).
