debugging-analytics-tracking

name	debugging-analytics-tracking
description	Debug analytics tracking that silently fails. Use when: (1) Analytics events fire in console but data doesn't appear in dashboard, (2) sendBeacon requests invisible in Network tab, (3) API returns "Failed to record event" with no details, (4) Database insert fails silently. Covers sendBeacon debugging, schema mismatch diagnosis, and silent failure patterns.
author	Claude Code
version	1.0.0
date	"2026-01-28T00:00:00.000Z"

Debugging Analytics Tracking

Problem

Analytics tracking appears to work (console logs fire) but data never appears in the dashboard. The tracking code silently swallows errors, making it hard to find the actual issue.

Context / Trigger Conditions

• Console shows tracking events firing (e.g., [Landing Event] cta_click {...})
• But NO network request visible in DevTools Network tab
• Or API returns generic error like {"error": "Failed to record event"}
• Data doesn't appear in admin dashboard
• No obvious errors in browser console

Solution

Step 1: Check if sendBeacon is hiding requests

navigator.sendBeacon() requests often don't appear in DevTools Network tab like regular fetch/XHR.

To debug:

// Temporarily replace sendBeacon with fetch
// Before:
if (useBeacon && navigator.sendBeacon) {
  navigator.sendBeacon('/api/analytics/...', blob);
}

// After (for debugging):
fetch('/api/analytics/...', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
})
  .then(res => console.log('API response:', res.status))
  .then(data => console.log('API data:', data))
  .catch(err => console.error('API error:', err));

Step 2: Check terminal for database errors

Analytics APIs often return generic errors to clients but log details server-side.

Look for in terminal:

[Landing Event API] Insert error: { code: '42703', message: 'column "device_type" does not exist' }

Step 3: Compare migration schema vs API insert

Common cause: API tries to insert columns that don't exist in the database.

Check migration file:

-- What columns does the table have?
SELECT column_name FROM information_schema.columns
WHERE table_name = 'landing_page_events';

Compare with API insert:

// Does the insert include columns not in the table?
await supabase.from('landing_page_events').insert({
  visitor_hash,    // ✓ exists
  session_id,      // ✓ exists
  device_type,     // ✗ MISSING - causes error!
  browser_family,  // ✗ MISSING
  ...
});

Step 4: Add missing columns

ALTER TABLE landing_page_events
ADD COLUMN IF NOT EXISTS device_type VARCHAR(20) DEFAULT 'desktop';
-- etc.

Verification

1. Click tracking element on the page
2. Console shows: API response: 200 and {"success": true}
3. Data appears in admin dashboard

Example

Symptom: Landing page CTA tracking not working

• Console: [Landing Event] cta_click {ctaLocation: 'hero', ...} ✓
• Network tab: No request visible (sendBeacon)
• Dashboard: No data

Debug steps:

1. Replaced sendBeacon with fetch → saw {"error": "Failed to record event"}
2. Checked terminal → column "device_type" does not exist
3. Compared migration vs API → migration missing 6 columns
4. Ran ALTER TABLE to add columns → Success!

Notes

• sendBeacon quirks: May appear as type "ping" in Network tab, or be filtered out entirely. Try removing filters or using "All" instead of "Fetch/XHR"
• Silent failures are intentional: Analytics shouldn't break the app, so errors are caught. Always add temporary logging when debugging.
• Schema drift: When adding features to tracking, easy to forget to update the database schema. Keep migration files in sync with API code.
• Environment column: If using prodOnly filter, ensure events have correct environment value or they'll be filtered out.

Related Patterns

• Supabase insert errors often return code 42703 for missing columns
• sendBeacon is fire-and-forget - no response handling possible
• keepalive fetch option helps with page unload tracking but still shows in Network tab