CompanySite/.agents/seo-specialist/ANALYTICS_SETUP.md

# Analytics & Tracking Setup

**Agent:** seo-specialist
**Date:** 2026-03-21
**Status:** Complete

---

## Overview

This document describes the analytics and event tracking implementation for the WorkRoot IT Solutions website. The setup supports both **Google Analytics 4 (GA4)** and **Plausible Analytics** (privacy-focused alternative), configurable via environment variables.

---

## Files Created / Modified

| File | Action | Purpose |
|------|--------|---------|
| `src/components/Analytics.astro` | Created | Injects GA4 or Plausible scripts based on env vars |
| `src/utils/analytics.ts` | Created | Client-side event tracking utilities |
| `src/layouts/BaseLayout.astro` | Modified | Imports and renders Analytics component; adds global external link tracking |
| `src/pages/contact.astro` | Modified | Added form submission event tracking |
| `src/components/Footer.astro` | Modified | Added newsletter signup event tracking |
| `src/pages/portfolio.astro` | Modified | Added portfolio filter and case study view tracking |
| `src/middleware.ts` | Modified | Updated CSP to allow GA4 and Plausible domains |
| `.env.example` | Modified | Added GA4 (G-XXXXXXXXXX format) and Plausible vars |

---

## Configuration

### Option A: Google Analytics 4

```env
# .env
GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX
```

Get your Measurement ID: **Google Analytics → Admin → Data Streams → Web → Measurement ID**

> **Important:** Use the new GA4 format `G-XXXXXXXXXX`, NOT the old Universal Analytics format `UA-XXXXXXXXX-X`.

### Option B: Plausible Analytics (privacy-focused)

```env
# .env
PLAUSIBLE_DOMAIN=workroot.in
```

Sign up at [plausible.io](https://plausible.io). Add your domain, then set `PLAUSIBLE_DOMAIN` to your site's hostname (without `https://`).

### Both simultaneously

Both variables can be set at the same time — events will be sent to both platforms.

---

## Event Tracking Reference

All events are fired via `src/utils/analytics.ts`. The helper functions work silently if analytics is not configured.

| Event Name | Trigger | Parameters |
|-----------|---------|-----------|
| `form_submit_success` | Contact form submitted successfully | `form_name: 'contact'` |
| `form_submit_error` | Contact form submission failed | `form_name: 'contact'` |
| `contact_form_submit` | Contact form success (detailed) | `subject_category: <value>` |
| `newsletter_signup_success` | Newsletter subscribed successfully | `form_name: 'newsletter'` |
| `newsletter_signup_error` | Newsletter subscription failed | `form_name: 'newsletter'` |
| `portfolio_filter` | Portfolio category filter clicked | `filter_category: all\|web\|mobile\|ai` |
| `case_study_view` | Portfolio case study modal opened | `project_id`, `project_title` |
| `external_link_click` | Any external link clicked (auto-tracked) | `link_url`, `link_label`, `outbound: true` |

---

## Privacy & Compliance

### Do Not Track (DNT)
The implementation respects the browser's **Do Not Track** setting. If `navigator.doNotTrack === '1'`, no events are sent.

### GA4 Privacy Settings
GA4 is configured with:
- `anonymize_ip: true` — anonymizes the last octet of IP addresses (GDPR compliance)
- `allow_google_signals: false` — disables demographic reporting
- `allow_ad_personalization_signals: false` — disables ad personalization

### Plausible
Plausible is inherently privacy-focused: no cookies, no personal data, GDPR/CCPA compliant by design. This is the recommended option for privacy-first deployments.

---

## Content Security Policy

The following domains were added to `src/middleware.ts`:

```
script-src: https://www.googletagmanager.com https://www.google-analytics.com https://plausible.io
img-src: https://www.google-analytics.com https://www.googletagmanager.com
connect-src: https://www.google-analytics.com https://analytics.google.com https://stats.g.doubleclick.net https://plausible.io
```

---

## Using the Analytics Utility

```typescript
import {
  trackEvent,
  trackExternalLink,
  trackFormSubmit,
  trackNewsletterSignup,
  trackPortfolioFilter,
  trackCaseStudyView,
  bindExternalLinkTracking,
} from '../utils/analytics';

// Generic event
trackEvent('button_click', { button_id: 'hero-cta' });

// Form tracking
trackFormSubmit('contact', true);     // success
trackFormSubmit('contact', false);    // failure

// Newsletter
trackNewsletterSignup(true);

// Portfolio
trackPortfolioFilter('web');
trackCaseStudyView('ecommerce-platform', 'E-Commerce Platform');

// External links (auto-bound in BaseLayout, or call manually)
trackExternalLink('https://github.com/workroot', 'GitHub');
```

---

## Recommended GA4 Configuration

After setting up GA4, configure these in the Google Analytics dashboard:

### Conversions (Mark as Key Events)
- `form_submit_success` → "Contact Form Lead"
- `newsletter_signup_success` → "Newsletter Signup"

### Custom Dimensions
| Dimension | Scope | Parameter |
|-----------|-------|-----------|
| Subject Category | Event | `subject_category` |
| Filter Category | Event | `filter_category` |
| Project ID | Event | `project_id` |

### Goals / Funnels
- **Lead funnel:** Page view → Contact page view → Form start → `form_submit_success`
- **Content funnel:** Portfolio filter → Case study view → Contact CTA click

---

## Verification

### GA4
1. Install [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/) Chrome extension
2. Open DevTools → Console → look for `Firing event: <event_name>`
3. Check **GA4 → Realtime** report for live event data

### Plausible
1. Open Plausible dashboard for your domain
2. Navigate to site and check the **Realtime** tab
3. Trigger events (form submit, filter click) and verify they appear under **Goals**

---

## Future Improvements

- [ ] Add cookie consent banner before initializing GA4 (GDPR strict mode)
- [ ] Track blog post read depth with scroll depth events
- [ ] Add `page_scroll` events at 25%, 50%, 75%, 100% thresholds
- [ ] Track CTA button clicks site-wide (hero, services, about sections)
- [ ] Set up Google Search Console integration with GA4
- [ ] Create GA4 Looker Studio dashboard for reporting