analytics-tracking

What this skill does

# Analytics Tracking - Implementation & Auditing

**Category:** Marketing
**Tags:** GA4, Google Tag Manager, event tracking, conversion tracking, UTM, analytics audit, consent mode

## Overview

Analytics Tracking is the implementation layer for marketing measurement. Bad tracking is worse than no tracking -- duplicate events, missing parameters, unconsented data, and broken conversions lead to decisions based on bad data. This skill covers building tracking right the first time and finding what is broken when it is not.

This skill handles implementation only. For analyzing campaign performance data, use campaign-analytics. For product analytics and in-app behavior, use the product-team skills.

---

## Operating Modes

### Mode 1: Build From Scratch
No analytics in place. Build the tracking plan, implement GA4 + GTM, define event taxonomy, configure conversions.

### Mode 2: Audit Existing Tracking
Tracking exists but data cannot be trusted. Audit coverage, identify gaps, clean up duplicates, fix consent issues.

### Mode 3: Debug Specific Issues
Events are missing, conversions do not match, GTM preview shows fires but GA4 does not record. Structured debugging workflow.

---

## Event Taxonomy Design

Get this right before touching GA4 or GTM. Retrofitting taxonomy is painful and expensive.

### Naming Convention

**Format:** `object_action` (snake_case, past tense verb)

| Correct | Wrong | Why Wrong |
|---------|-------|-----------|
| `form_submitted` | `submitForm` | camelCase, verb-first |
| `plan_selected` | `clickPricingPlan` | Implementation detail, not user action |
| `video_started` | `VideoStart` | PascalCase, inconsistent tense |
| `checkout_completed` | `purchase` | Ambiguous, not a verb phrase |

**Rules:**
1. Always `noun_verb` order, never `verb_noun`
2. Snake_case only -- no camelCase, no hyphens, no PascalCase
3. Past tense verbs: `_started`, `_completed`, `_failed`, `_viewed`
4. Specific enough to be unambiguous, not so verbose it is a sentence
5. Prefix with domain when needed: `onboarding_step_completed`, `billing_plan_selected`

### Standard Event Parameters

Every custom event should include applicable parameters from this table:

| Parameter | Type | Example | Required When |
|-----------|------|---------|---------------|
| `user_id` | string | `usr_abc123` | Always (if authenticated) |
| `plan_name` | string | `professional` | Billing/pricing events |
| `value` | number | `99.00` | Revenue events |
| `currency` | string | `USD` | Always with value |
| `content_group` | string | `onboarding` | Page/flow grouping |
| `method` | string | `google_oauth` | Signup/login events |
| `step_name` | string | `connect_account` | Multi-step flows |
| `step_number` | number | `3` | Multi-step flows |
| `source` | string | `pricing_page` | CTA click events |

### SaaS Event Taxonomy (Reference)

**Core Funnel:**
```
visitor_arrived              (automatic page_view in GA4)
signup_started               (user clicked "Sign up")
signup_completed             (account created)
trial_started                (free trial began)
onboarding_step_completed    (params: step_name, step_number)
feature_activated            (params: feature_name)
plan_selected                (params: plan_name, billing_period)
checkout_started             (params: value, currency, plan_name)
checkout_completed           (params: value, currency, transaction_id)
subscription_renewed         (params: value, plan_name)
subscription_cancelled       (params: cancel_reason, plan_name)
```

**Micro-Conversions:**
```
pricing_viewed
demo_requested               (params: source)
form_submitted               (params: form_name, form_location)
content_downloaded           (params: content_name, content_type)
video_started                (params: video_title)
video_completed              (params: video_title, percent_watched)
chat_opened
help_article_viewed          (params: article_name)
invite_sent                  (params: recipient_role)
integration_connected        (params: integration_name)
```

---

## GA4 Configuration

### Data Stream Setup

1. Create property: GA4 Admin > Properties > Create
2. Add web data stream with your domain
3. Enhanced Measurement -- review each:
   - Page views: Keep enabled
   - Scrolls: Keep enabled
   - Outbound clicks: Keep enabled
   - Site search: Enable if you have search
   - Video engagement: Disable if tracking videos manually (avoids duplicates)
   - File downloads: Disable if tracking via GTM (for better parameters)
4. Configure domains: add all subdomains in your funnel
5. Data retention: Set to 14 months (maximum for free GA4)

### Conversion Events

Mark as conversions in GA4 Admin > Conversions:
- `signup_completed`
- `checkout_completed`
- `demo_requested`
- `trial_started`

**Rules:**
- Maximum 30 conversion events per property -- curate carefully
- GA4 conversions are retroactive for 6 months when enabled
- Do not mark micro-conversions as conversions unless optimizing ad campaigns for them
- Conversion counting: set to "once per session" for lead events, "every" for purchase events

### Custom Dimensions

Register custom dimensions for any event parameter you want to filter/segment by:

| Parameter | Scope | Dimension Name |
|-----------|-------|----------------|
| `plan_name` | Event | Plan Name |
| `user_id` | User | User ID |
| `content_group` | Event | Content Group |
| `feature_name` | Event | Feature Name |

Register in GA4 Admin > Custom definitions > Create custom dimension.

---

## Google Tag Manager Implementation

### Container Architecture

```
GTM Container
├── Tags
│   ├── GA4 Configuration (All Pages trigger)
│   ├── GA4 Event Tags (one per custom event)
│   ├── Google Ads Conversion Tags (per conversion action)
│   └── Meta Pixel / LinkedIn Insight (if running ads)
├── Triggers
│   ├── All Pages (Page View)
│   ├── DOM Ready
│   ├── Custom Event triggers (one per dataLayer event)
│   └── Element Click triggers (CSS selector based)
└── Variables
    ├── Data Layer Variables (one per dataLayer key)
    ├── Constants (GA4 Measurement ID, etc.)
    └── Lookup Tables (if needed for mapping)
```

### Implementation Pattern: Data Layer Push

Your application pushes events to the data layer. GTM picks them up and sends to GA4.

**Application code:**
```javascript
// Push event when user completes signup
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'signup_completed',
  method: 'email',
  user_id: userId,
  plan_name: 'trial'
});
```

**GTM configuration:**
```
Trigger:
  Type: Custom Event
  Event name: signup_completed

Tag:
  Type: GA4 Event
  Event name: signup_completed
  Parameters:
    method:    {{DLV - method}}
    user_id:   {{DLV - user_id}}
    plan_name: {{DLV - plan_name}}
```

### SPA Handling

Single Page Applications need special attention because page views do not fire automatically on route changes.

**Option A: History change trigger (GTM built-in)**
- Enable "History Change" trigger in GTM
- Fires GA4 page_view on every pushState/popState

**Option B: DataLayer push on route change (more control)**
```javascript
// In your router (React Router, Next.js, etc.)
router.events.on('routeChangeComplete', (url) => {
  window.dataLayer.push({
    event: 'page_view',
    page_location: url,
    page_title: document.title
  });
});
```

---

## Conversion Tracking: Ad Platforms

### Google Ads

**Recommended approach:** Import GA4 conversions into Google Ads (single source of truth).

1. Link GA4 and Google Ads accounts
2. In Google Ads > Goals > Conversions > Import > Google Analytics
3. Select GA4 conversion events to import
4. Set attribution model: Data-driven (if 50+ conversions/month), otherwise Last-click
5. Conversion window: 30 days for lead gen, 90 days for high-consideration B2B

**Enhanced Conversions:** Enable for 15-30% better conversion measurement. Sends hashed first-party data (email, phone) to match conversions that cookies miss.

### Meta (Facebook/Instagram)