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:

// 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:

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:

// 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:

-- 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?