Analytics

Analytics Tracking

You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and product decisions.

Initial Assessment

Check for product marketing context first: If .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before implementing tracking, understand:

1. Business Context - What decisions will this data inform? What are key conversions? 2. Current State - What tracking exists? What tools are in use? 3. Technical Context - What's the tech stack? Any privacy/compliance requirements?

---

Core Principles

1. Track for Decisions, Not Data

• Every event should inform a decision
• Avoid vanity metrics
• Quality > quantity of events

2. Start with the Questions

• What do you need to know?
• What actions will you take based on this data?
• Work backwards to what you need to track

3. Name Things Consistently

• Naming conventions matter
• Establish patterns before implementing
• Document everything

4. Maintain Data Quality

• Validate implementation
• Monitor for issues
• Clean data > more data

---

Tracking Plan Framework

Structure

Event Name | Category | Properties | Trigger | Notes
---------- | -------- | ---------- | ------- | -----

Event Types

For comprehensive event lists: See references/event-library.md

---

Event Naming Conventions

Recommended Format: Object-Action

signup_completed
button_clicked
form_submitted
article_read
checkout_payment_completed

Best Practices

• Lowercase with underscores
• Be specific: cta_hero_clicked vs. button_clicked
• Include context in properties, not event name
• Avoid spaces and special characters
• Document decisions

---

Essential Events

Marketing Site

Product/App

For full event library by business type: See references/event-library.md

---

Event Properties

Standard Properties

Best Practices

• Use consistent property names
• Include relevant context
• Don't duplicate automatic properties
• Avoid PII in properties

---

GA4 Implementation

Quick Setup

1. Create GA4 property and data stream 2. Install gtag.js or GTM 3. Enable enhanced measurement 4. Configure custom events 5. Mark conversions in Admin

Custom Event Example

gtag('event', 'signup_completed', {
  'method': 'email',
  'plan': 'free'
});

For detailed GA4 implementation: See references/ga4-implementation.md

---

Google Tag Manager

Container Structure

Data Layer Pattern

dataLayer.push({
  'event': 'form_submitted',
  'form_name': 'contact',
  'form_location': 'footer'
});

For detailed GTM implementation: See references/gtm-implementation.md

---

UTM Parameter Strategy

Standard Parameters

Naming Conventions

• Lowercase everything
• Use underscores or hyphens consistently
• Be specific but concise: blog_footer_cta, not cta1
• Document all UTMs in a spreadsheet

---

Debugging and Validation

Testing Tools

Validation Checklist

• [ ] Events firing on correct triggers
• [ ] Property values populating correctly
• [ ] No duplicate events
• [ ] Works across browsers and mobile
• [ ] Conversions recorded correctly
• [ ] No PII leaking

Common Issues

---

Privacy and Compliance

Considerations

• Cookie consent required in EU/UK/CA
• No PII in analytics properties
• Data retention settings
• User deletion capabilities

Implementation

• Use consent mode (wait for consent)
• IP anonymization
• Only collect what you need
• Integrate with consent management platform

---

Output Format

Tracking Plan Document

# [Site/Product] Tracking Plan

## Overview
- Tools: GA4, GTM
- Last updated: [Date]

## Events

| Event Name | Description | Properties | Trigger |
|------------|-------------|------------|---------|
| signup_completed | User completes signup | method, plan | Success page |

## Custom Dimensions

| Name | Scope | Parameter |
|------|-------|-----------|
| user_type | User | user_type |

## Conversions

| Conversion | Event | Counting |
|------------|-------|----------|
| Signup | signup_completed | Once per session |

---

Task-Specific Questions

1. What tools are you using (GA4, Mixpanel, etc.)? 2. What key actions do you want to track? 3. What decisions will this data inform? 4. Who implements - dev team or marketing? 5. Are there privacy/consent requirements? 6. What's already tracked?

---

Tool Integrations

For implementation, see the tools registry. Key analytics tools:

Event Library Reference

Comprehensive list of events to track by business type and context.

Contents

• Marketing Site Events (navigation & engagement, CTA & form interactions, conversion events)
• Product/App Events (onboarding, core usage, errors & support)
• Monetization Events (pricing & checkout, subscription management)
• E-commerce Events (browsing, cart, checkout, post-purchase)
• B2B / SaaS Specific Events (team & collaboration, integration events, account events)
• Event Properties (Parameters)
• Funnel Event Sequences

Marketing Site Events

Navigation & Engagement

CTA & Form Interactions

Conversion Events

---

Product/App Events

Onboarding

Core Usage

Errors & Support

---

Monetization Events

Pricing & Checkout

Subscription Management

---

E-commerce Events

Browsing

Cart

Checkout

Post-Purchase

---

B2B / SaaS Specific Events

Team & Collaboration

Integration Events

Account Events

---

Event Properties (Parameters)

Standard Properties to Include

User Context:

user_id: "12345"
user_type: "free" | "trial" | "paid"
account_id: "acct_123"
plan_type: "starter" | "pro" | "enterprise"

Session Context:

session_id: "sess_abc"
session_number: 5
page: "/pricing"
referrer: "https://google.com"

Campaign Context:

source: "google"
medium: "cpc"
campaign: "spring_sale"
content: "hero_cta"

Product Context (E-commerce):

product_id: "SKU123"
product_name: "Product Name"
category: "Category"
price: 99.99
quantity: 1
currency: "USD"

Timing:

timestamp: "2024-01-15T10:30:00Z"
time_on_page: 45
session_duration: 300

---

Funnel Event Sequences

Signup Funnel

1. signup_started 2. signup_step_completed (email) 3. signup_step_completed (password) 4. signup_completed 5. onboarding_started

Purchase Funnel

1. pricing_viewed 2. plan_selected 3. checkout_started 4. payment_info_entered 5. purchase_completed

E-commerce Funnel

1. product_viewed 2. product_added_to_cart 3. cart_viewed 4. checkout_started 5. shipping_info_entered 6. payment_info_entered 7. purchase_completed

GA4 Implementation Reference

Detailed implementation guide for Google Analytics 4.

Contents

• Configuration (data streams, enhanced measurement events, recommended events)
• Custom Events (gtag.js implementation, Google Tag Manager)
• Conversions Setup (creating conversions, conversion values)
• Custom Dimensions and Metrics (when to use, setup steps, examples)
• Audiences (creating audiences, audience examples)
• Debugging (DebugView, real-time reports, common issues)
• Data Quality (filters, cross-domain tracking, session settings)
• Integration with Google Ads (linking, audience export)

Configuration

Data Streams

• One stream per platform (web, iOS, Android)
• Enable enhanced measurement for automatic tracking
• Configure data retention (2 months default, 14 months max)
• Enable Google Signals (for cross-device, if consented)

Enhanced Measurement Events (Automatic)

Recommended Events

Use Google's predefined events when possible for enhanced reporting:

All properties:

• login, sign_up
• share
• search

E-commerce:

• view_item, view_item_list
• add_to_cart, remove_from_cart
• begin_checkout
• add_payment_info
• purchase, refund

Games:

• level_up, unlock_achievement
• post_score, spend_virtual_currency

Reference: https://support.google.com/analytics/answer/9267735

---

Custom Events

gtag.js Implementation

// Basic event
gtag('event', 'signup_completed', {
  'method': 'email',
  'plan': 'free'
});

// Event with value
gtag('event', 'purchase', {
  'transaction_id': 'T12345',
  'value': 99.99,
  'currency': 'USD',
  'items': [{
    'item_id': 'SKU123',
    'item_name': 'Product Name',
    'price': 99.99
  }]
});

// User properties
gtag('set', 'user_properties', {
  'user_type': 'premium',
  'plan_name': 'pro'
});

// User ID (for logged-in users)
gtag('config', 'GA_MEASUREMENT_ID', {
  'user_id': 'USER_ID'
});

Google Tag Manager (dataLayer)

// Custom event
dataLayer.push({
  'event': 'signup_completed',
  'method': 'email',
  'plan': 'free'
});

// Set user properties
dataLayer.push({
  'user_id': '12345',
  'user_type': 'premium'
});

// E-commerce purchase
dataLayer.push({
  'event': 'purchase',
  'ecommerce': {
    'transaction_id': 'T12345',
    'value': 99.99,
    'currency': 'USD',
    'items': [{
      'item_id': 'SKU123',
      'item_name': 'Product Name',
      'price': 99.99,
      'quantity': 1
    }]
  }
});

// Clear ecommerce before sending (best practice)
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'view_item',
  'ecommerce': {
    // ...
  }
});

---

Conversions Setup

Creating Conversions

1. Collect the event - Ensure event is firing in GA4 2. Mark as conversion - Admin > Events > Mark as conversion 3. Set counting method:

• Once per session (leads, signups)
• Every event (purchases)

4. Import to Google Ads - For conversion-optimized bidding

Conversion Values

// Event with conversion value
gtag('event', 'purchase', {
  'value': 99.99,
  'currency': 'USD'
});

Or set default value in GA4 Admin when marking conversion.

---

Custom Dimensions and Metrics

When to Use

Custom dimensions:

• Properties you want to segment/filter by
• User attributes (plan type, industry)
• Content attributes (author, category)

Custom metrics:

• Numeric values to aggregate
• Scores, counts, durations

Setup Steps

1. Admin > Data display > Custom definitions 2. Create dimension or metric 3. Choose scope:

• Event: Per event (content_type)
• User: Per user (account_type)
• Item: Per product (product_category)

4. Enter parameter name (must match event parameter)

Examples

---

Audiences

Creating Audiences

Admin > Data display > Audiences

Use cases:

• Remarketing audiences (export to Ads)
• Segment analysis
• Trigger-based events

Audience Examples

High-intent visitors:

• Viewed pricing page
• Did not convert
• In last 7 days

Engaged users:

• 3+ sessions
• Or 5+ minutes total engagement

Purchasers:

• Purchase event
• For exclusion or lookalike

---

Debugging

DebugView

Enable with:

• URL parameter: ?debug_mode=true
• Chrome extension: GA Debugger
• gtag: 'debug_mode': true in config

View at: Reports > Configure > DebugView

Real-Time Reports

Check events within 30 minutes: Reports > Real-time

Common Issues

Events not appearing:

• Check DebugView first
• Verify gtag/GTM firing
• Check filter exclusions

Parameter values missing:

• Custom dimension not created
• Parameter name mismatch
• Data still processing (24-48 hrs)

Conversions not recording:

• Event not marked as conversion
• Event name doesn't match
• Counting method (once vs. every)

---

Data Quality

Filters

Admin > Data streams > [Stream] > Configure tag settings > Define internal traffic

Exclude:

• Internal IP addresses
• Developer traffic
• Testing environments

Cross-Domain Tracking

For multiple domains sharing analytics:

1. Admin > Data streams > [Stream] > Configure tag settings 2. Configure your domains 3. List all domains that should share sessions

Session Settings

Admin > Data streams > [Stream] > Configure tag settings

• Session timeout (default 30 min)
• Engaged session duration (10 sec default)

---

Integration with Google Ads

Linking

1. Admin > Product links > Google Ads links 2. Enable auto-tagging in Google Ads 3. Import conversions in Google Ads

Audience Export

Audiences created in GA4 can be used in Google Ads for:

• Remarketing campaigns
• Customer match
• Similar audiences

Google Tag Manager Implementation Reference

Detailed guide for implementing tracking via Google Tag Manager.

Contents

• Container Structure (tags, triggers, variables)
• Naming Conventions
• Data Layer Patterns
• Common Tag Configurations (GA4 configuration tag, GA4 event tag, Facebook pixel)
• Preview and Debug
• Workspaces and Versioning
• Consent Management
• Advanced Patterns (tag sequencing, exception handling, custom JavaScript variables)

Container Structure

Tags

Tags are code snippets that execute when triggered.

Common tag types:

• GA4 Configuration (base setup)
• GA4 Event (custom events)
• Google Ads Conversion
• Facebook Pixel
• LinkedIn Insight Tag
• Custom HTML (for other pixels)

Triggers

Triggers define when tags fire.

Built-in triggers:

• Page View: All Pages, DOM Ready, Window Loaded
• Click: All Elements, Just Links
• Form Submission
• Scroll Depth
• Timer
• Element Visibility

Custom triggers:

• Custom Event (from dataLayer)
• Trigger Groups (multiple conditions)

Variables

Variables capture dynamic values.

Built-in (enable as needed):

• Click Text, Click URL, Click ID, Click Classes
• Page Path, Page URL, Page Hostname
• Referrer
• Form Element, Form ID

User-defined:

• Data Layer variables
• JavaScript variables
• Lookup tables
• RegEx tables
• Constants

---

Naming Conventions

Recommended Format

[Type] - [Description] - [Detail]

Tags:
GA4 - Event - Signup Completed
GA4 - Config - Base Configuration
FB - Pixel - Page View
HTML - LiveChat Widget

Triggers:
Click - CTA Button
Submit - Contact Form
View - Pricing Page
Custom - signup_completed

Variables:
DL - user_id
JS - Current Timestamp
LT - Campaign Source Map

---

Data Layer Patterns

Basic Structure

// Initialize (in <head> before GTM)
window.dataLayer = window.dataLayer || [];

// Push event
dataLayer.push({
  'event': 'event_name',
  'property1': 'value1',
  'property2': 'value2'
});

Page Load Data

// Set on page load (before GTM container)
window.dataLayer = window.dataLayer || [];
dataLayer.push({
  'pageType': 'product',
  'contentGroup': 'products',
  'user': {
    'loggedIn': true,
    'userId': '12345',
    'userType': 'premium'
  }
});

Form Submission

document.querySelector('#contact-form').addEventListener('submit', function() {
  dataLayer.push({
    'event': 'form_submitted',
    'formName': 'contact',
    'formLocation': 'footer'
  });
});

Button Click

document.querySelector('.cta-button').addEventListener('click', function() {
  dataLayer.push({
    'event': 'cta_clicked',
    'ctaText': this.innerText,
    'ctaLocation': 'hero'
  });
});

E-commerce Events

// Product view
dataLayer.push({ ecommerce: null }); // Clear previous
dataLayer.push({
  'event': 'view_item',
  'ecommerce': {
    'items': [{
      'item_id': 'SKU123',
      'item_name': 'Product Name',
      'price': 99.99,
      'item_category': 'Category',
      'quantity': 1
    }]
  }
});

// Add to cart
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'add_to_cart',
  'ecommerce': {
    'items': [{
      'item_id': 'SKU123',
      'item_name': 'Product Name',
      'price': 99.99,
      'quantity': 1
    }]
  }
});

// Purchase
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'purchase',
  'ecommerce': {
    'transaction_id': 'T12345',
    'value': 99.99,
    'currency': 'USD',
    'tax': 5.00,
    'shipping': 10.00,
    'items': [{
      'item_id': 'SKU123',
      'item_name': 'Product Name',
      'price': 99.99,
      'quantity': 1
    }]
  }
});

---

Common Tag Configurations

GA4 Configuration Tag

Tag Type: Google Analytics: GA4 Configuration

Settings:

• Measurement ID: G-XXXXXXXX
• Send page view: Checked (for pageviews)
• User Properties: Add any user-level dimensions

Trigger: All Pages

GA4 Event Tag

Tag Type: Google Analytics: GA4 Event

Settings:

• Configuration Tag: Select your config tag
• Event Name: {{DL - event_name}} or hardcode
• Event Parameters: Add parameters from dataLayer

Trigger: Custom Event with event name match

Facebook Pixel - Base

Tag Type: Custom HTML

<script>
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>

Trigger: All Pages

Facebook Pixel - Event

Tag Type: Custom HTML

<script>
  fbq('track', 'Lead', {
    content_name: '{{DL - form_name}}'
  });
</script>

Trigger: Custom Event - form_submitted

---

Preview and Debug

Preview Mode

1. Click "Preview" in GTM 2. Enter site URL 3. GTM debug panel opens at bottom

What to check:

• Tags fired on this event
• Tags not fired (and why)
• Variables and their values
• Data layer contents

Debug Tips

Tag not firing:

• Check trigger conditions
• Verify data layer push
• Check tag sequencing

Wrong variable value:

• Check data layer structure
• Verify variable path (nested objects)
• Check timing (data may not exist yet)

Multiple firings:

• Check trigger uniqueness
• Look for duplicate tags
• Check tag firing options

---

Workspaces and Versioning

Workspaces

Use workspaces for team collaboration:

• Default workspace for production
• Separate workspaces for large changes
• Merge when ready

Version Management

Best practices:

• Name every version descriptively
• Add notes explaining changes
• Review changes before publish
• Keep production version noted

Version notes example:

v15: Added purchase conversion tracking
- New tag: GA4 - Event - Purchase
- New trigger: Custom Event - purchase
- New variables: DL - transaction_id, DL - value
- Tested: Chrome, Safari, Mobile

---

Consent Management

Consent Mode Integration

// Default state (before consent)
gtag('consent', 'default', {
  'analytics_storage': 'denied',
  'ad_storage': 'denied'
});

// Update on consent
function grantConsent() {
  gtag('consent', 'update', {
    'analytics_storage': 'granted',
    'ad_storage': 'granted'
  });
}

GTM Consent Overview

1. Enable Consent Overview in Admin 2. Configure consent for each tag 3. Tags respect consent state automatically

---

Advanced Patterns

Tag Sequencing

Setup tags to fire in order: Tag Configuration > Advanced Settings > Tag Sequencing

Use cases:

• Config tag before event tags
• Pixel initialization before tracking
• Cleanup after conversion

Exception Handling

Trigger exceptions - Prevent tag from firing:

• Exclude certain pages
• Exclude internal traffic
• Exclude during testing

Custom JavaScript Variables

// Get URL parameter
function() {
  var params = new URLSearchParams(window.location.search);
  return params.get('campaign') || '(not set)';
}

// Get cookie value
function() {
  var match = document.cookie.match('(^|;) ?user_id=([^;]*)(;|$)');
  return match ? match[2] : null;
}

// Get data from page
function() {
  var el = document.querySelector('.product-price');
  return el ? parseFloat(el.textContent.replace('$', '')) : 0;
}