PixelPilot uiux-analytics-setup.instructions.md

Analytics Setup Skill

Configure error tracking, product analytics, and web analytics with proper consent management.

---

CRITICAL RULES

1. Never load analytics scripts before user consent (GDPR/CCPA).
2. Store API keys in .env — never hardcode.
3. Use design tokens for any error UI (toasts, banners).
4. Respect prefers-reduced-motion in any animated feedback.

---

ENVIRONMENT VARIABLES

# .env (never commit this file)

# Sentry
SENTRY_DSN=https://[email protected]/xxx
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

# PostHog
POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxx
POSTHOG_HOST=https://app.posthog.com

# Google Analytics 4
GA_MEASUREMENT_ID=G-XXXXXXXXXX

---

1. SENTRY (Error Tracking)

Installation

npm install @sentry/browser
# Or for frameworks:
npm install @sentry/react @sentry/nextjs @sentry/vue

Vanilla JS Setup

// sentry.js
import * as Sentry from '@sentry/browser';

export function initSentry() {
  // Only init if user consented and DSN exists
  const hasConsent = localStorage.getItem('analytics-consent') === 'true';
  const dsn = import.meta.env.VITE_SENTRY_DSN; // or process.env
  
  if (!hasConsent || !dsn) {
    console.log('Sentry: Skipped (no consent or DSN)');
    return;
  }

  Sentry.init({
    dsn,
    environment: import.meta.env.VITE_SENTRY_ENVIRONMENT || 'development',
    release: import.meta.env.VITE_SENTRY_RELEASE,
    
    // Performance monitoring (optional)
    integrations: [
      Sentry.browserTracingIntegration(),
    ],
    tracesSampleRate: 0.1, // 10% of transactions
    
    // Filter out noisy errors
    ignoreErrors: [
      'ResizeObserver loop limit exceeded',
      'Non-Error promise rejection',
      /Loading chunk \d+ failed/,
    ],
    
    // Sanitize sensitive data
    beforeSend(event) {
      // Remove PII from breadcrumbs
      if (event.breadcrumbs) {
        event.breadcrumbs = event.breadcrumbs.map(crumb => {
          if (crumb.data?.url) {
            crumb.data.url = sanitizeUrl(crumb.data.url);
          }
          return crumb;
        });
      }
      return event;
    }
  });

  // Set user context (anonymized)
  Sentry.setUser({
    id: getAnonymousId(), // Hash of user ID, not actual ID
  });
}

function sanitizeUrl(url) {
  try {
    const parsed = new URL(url);
    // Remove sensitive query params
    ['token', 'key', 'password', 'secret'].forEach(param => {
      parsed.searchParams.delete(param);
    });
    return parsed.toString();
  } catch {
    return '[invalid-url]';
  }
}