FRE-709: Document duplicate recovery wake - FRE-635 already recovered via FRE-708
This commit is contained in:
290
plans/FRE-632-A5-utm-tracking.md
Normal file
290
plans/FRE-632-A5-utm-tracking.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 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?
|
||||
Reference in New Issue
Block a user