FrenoCorp/plans/FRE-632-A5-utm-tracking.md

# FRE-632-A5: UTM Tracking Specification for Hacker News

**Owner:** CTO  
**Requestor:** CMO  
**Due:** T-1 day before HN submission  
**Status:** Ready to Implement  
**Priority:** High

---

## Overview

Configure analytics tracking to measure Hacker News referral traffic, conversions, and user behavior. This enables accurate ROI measurement and optimization.

---

## UTM Parameters

### Primary HN Campaign

All HN traffic should use these UTM parameters:

```
utm_source=hackernews
utm_campaign=showhn
utm_medium=social
utm_content={content_type}
```

### Content Variations

| Content Type | utm_content Value | Use Case |
|--------------|-------------------|----------|
| Main post | `showhn_post` | Primary HN submission link |
| First comment | `showhn_comment` | Link in first comment |
| Follow-up comment | `showhn_followup` | Links in subsequent comments |
| Milestone update | `showhn_milestone` | "We hit 100 points!" updates |

### Example URLs

**Homepage:**
```
https://scripter.app?utm_source=hackernews&utm_campaign=showhn&utm_medium=social&utm_content=showhn_post
```

**Signup Page:**
```
https://scripter.app/signup?utm_source=hackernews&utm_campaign=showhn&utm_medium=social&utm_content=showhn_post
```

**Pricing Page:**
```
https://scripter.app/pricing?utm_source=hackernews&utm_campaign=showhn&utm_medium=social&utm_content=showhn_post
```

---

## Analytics Implementation

### 1. Google Analytics 4 (GA4)

**Required Events:**

| Event Name | Trigger | Parameters |
|------------|---------|------------|
| `page_view` | All page views | `page_location`, `page_referrer`, `utm_*` |
| `sign_up` | Signup completion | `method`, `utm_*` |
| `login` | User login | `method`, `utm_*` |
| `create_project` | First project created | `project_type`, `utm_*` |
| `export_script` | Script exported | `format`, `utm_*` |
| `upgrade_to_pro` | Paid conversion | `plan`, `price`, `utm_*` |

**GA4 Configuration:**

```javascript
// gtag.js configuration
gtag('config', 'G-XXXXXXXXXX', {
  cookie_flags: 'samesite=none;secure',
  allow_enhanced_conversions: true
});

// Track UTM parameters automatically
gtag('event', 'page_view', {
  send_to: 'G-XXXXXXXXXX',
  page_location: window.location.href,
  page_referrer: document.referrer
});
```

**Custom Dimensions (User Properties):**

| Property Name | Scope | Description |
|---------------|-------|-------------|
| `traffic_source` | User | First touch source (e.g., "hackernews") |
| `signup_campaign` | User | Campaign at signup (e.g., "showhn") |
| `user_type` | User | Free vs. Pro vs. Premium |

---

### 2. Database Tracking

**User Table Additions:**

```sql
ALTER TABLE users ADD COLUMN signup_source VARCHAR(50);
ALTER TABLE users ADD COLUMN signup_campaign VARCHAR(50);
ALTER TABLE users ADD COLUMN signup_referrer TEXT;
ALTER TABLE users ADD COLUMN signup_utms JSONB;
```

**Signup Flow Capture:**

```typescript
// On signup completion
await db.users.update(userId, {
  signup_source: utmParams.source, // "hackernews"
  signup_campaign: utmParams.campaign, // "showhn"
  signup_referrer: document.referrer,
  signup_utms: {
    source: utmParams.source,
    medium: utmParams.medium,
    campaign: utmParams.campaign,
    content: utmParams.content,
    term: utmParams.term
  }
});
```

---

### 3. Real-Time Dashboard

**Dashboard Requirements:**

Create a real-time dashboard showing HN campaign performance.

**Metrics to Display:**

| Metric | Update Frequency | Target |
|--------|------------------|--------|
| HN referral sessions | Real-time (1 min) | 5,000+ day 1 |
| HN signup conversions | Real-time (5 min) | 500+ day 1 |
| Conversion rate (HN) | Hourly | 10%+ |
| Active users from HN | Hourly | 2,000+ day 1 |
| Projects created | Hourly | 1,000+ day 1 |
| Upgrades to Pro | Daily | 50+ day 1 |

**Dashboard SQL Query:**

```sql
-- HN signups today
SELECT 
  COUNT(*) as total_signups,
  COUNT(*) FILTER (WHERE created_at > NOW() - INTERVAL '1 hour') as last_hour,
  COUNT(*) FILTER (WHERE signup_campaign = 'showhn') as hn_signups
FROM users
WHERE created_at > CURRENT_DATE;

-- HN conversion funnel
SELECT 
  'sessions' as stage, COUNT(*) as count
FROM sessions 
WHERE utm_source = 'hackernews' AND session_date = CURRENT_DATE
UNION ALL
SELECT 
  'signups' as stage, COUNT(*) as count
FROM users 
WHERE signup_source = 'hackernews' AND created_at > CURRENT_DATE
UNION ALL
SELECT 
  'active_users' as stage, COUNT(*) as count
FROM users 
WHERE signup_source = 'hackernews' 
  AND last_active_at > NOW() - INTERVAL '24 hours'
UNION ALL
SELECT 
  'projects_created' as stage, COUNT(*) as count
FROM projects 
WHERE created_at > CURRENT_DATE 
  AND user_id IN (SELECT id FROM users WHERE signup_source = 'hackernews');
```

---

## Implementation Checklist

### Frontend (CTO)

- [ ] Add UTM parameter capture to signup flow
- [ ] Configure GA4 with custom dimensions
- [ ] Implement event tracking (sign_up, create_project, upgrade_to_pro)
- [ ] Test UTM persistence across sessions
- [ ] Verify referrer passing works correctly

### Backend (CTO)

- [ ] Add UTM columns to users table
- [ ] Capture UTM params on signup API endpoint
- [ ] Store UTM data in user record
- [ ] Create HN campaign analytics queries
- [ ] Set up automated daily reports

### Dashboard (CTO + CMO)

- [ ] Create real-time dashboard (Retool, Metabase, or custom)
- [ ] Configure auto-refresh (1-5 min intervals)
- [ ] Set up milestone alerts (100 signups, 500 signups, etc.)
- [ ] Test dashboard before launch day
- [ ] Share dashboard access with CMO

### Testing (CMO + CTO)

- [ ] Test UTM tracking with sample URLs
- [ ] Verify GA4 events fire correctly
- [ ] Confirm database capture works
- [ ] Test dashboard displays correct data
- [ ] Run end-to-end test before launch day

---

## Testing Plan

### Test Scenarios

**Test 1: Direct HN Link**
```
URL: https://scripter.app?utm_source=hackernews&utm_campaign=showhn
Expected: GA4 session with utm_source=hackernews, database capture on signup
```

**Test 2: HN Link to Signup**
```
URL: https://scripter.app/signup?utm_source=hackernews&utm_campaign=showhn
Expected: Signup attributed to HN campaign
```

**Test 3: Multi-Session Persistence**
```
Flow: Click HN link → Browse → Return next day → Signup
Expected: Signup still attributed to HN (UTM persisted in cookie/localStorage)
```

### Test Acceptance Criteria

- [ ] 100% of HN signups correctly attributed
- [ ] UTM parameters persist across sessions (7-day window)
- [ ] GA4 dashboard shows HN traffic in real-time
- [ ] Database queries return accurate HN conversion data
- [ ] No data loss or double-counting

---

## Success Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| Tracking accuracy | 100% | Audit sample of signups |
| Data latency | <5 min | Time from event to dashboard |
| Dashboard uptime | 99.9% | Launch day monitoring |
| Attribution window | 7 days | Return user attribution |

---

## Timeline

| Milestone | Due Date | Owner | Status |
|-----------|----------|-------|--------|
| Implement UTM capture | T-3 days | CTO | ⏳ Pending |
| Configure GA4 events | T-3 days | CTO | ⏳ Pending |
| Create dashboard | T-2 days | CTO | ⏳ Pending |
| End-to-end testing | T-1 day | CMO+CTO | ⏳ Pending |
| Go-live readiness | T-1 day | CTO | ⏳ Pending |

---

## Related Documents

- `/plans/hacker-news-showhn-submission.md` - Full HN submission strategy
- `/plans/FRE-632-hn-submission-checklist.md` - Master execution checklist
- `/marketing/analytics-dashboard.md` - General analytics specification

---

**Next Action:** CTO to implement UTM tracking and dashboard by T-1 day

**Questions for CTO:**
1. What analytics stack are we using? (GA4, Plausible, Mixpanel, etc.)
2. Do we have existing UTM capture infrastructure?
3. What dashboard tool should we use? (Retool, Metabase, custom?)
4. When can this be implemented relative to launch date?