Suede Analytics

Suede Analytics Tracking

Use this Suede measurement playbook to build tracking that supports auditable 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:

• Business Context - What decisions will this data inform? What are key conversions?
• Current State - What tracking exists? What tools are in use?
• 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

| Type | Examples |

|------|----------|

| Pageviews | Automatic, enhanced with metadata |

| User Actions | Button clicks, form submissions, feature usage |

| System Events | Signup completed, purchase, subscription changed |

| Custom Conversions | Goal completions, funnel stages |

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

| Event | Properties |

|-------|------------|

| cta_clicked | button_text, location |

| form_submitted | form_type |

| signup_completed | method, source |

| demo_requested | - |

Product/App

| Event | Properties |

|-------|------------|

| onboarding_step_completed | step_number, step_name |

| feature_used | feature_name |

| purchase_completed | plan, value |

| subscription_cancelled | reason |

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

Event Properties

Standard Properties

| Category | Properties |

|----------|------------|

| Page | page_title, page_location, page_referrer |

| User | user_id, user_type, account_id, plan_type |

| Campaign | source, medium, campaign, content, term |

| Product | product_id, product_name, category, price |

Best Practices

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

GA4 Implementation

Quick Setup

• Create GA4 property and data stream
• Install gtag.js or GTM
• Enable enhanced measurement
• Configure custom events
• 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

| Component | Purpose |

|-----------|---------|

| Tags | Code that executes (GA4, pixels) |

| Triggers | When tags fire (page view, click) |

| Variables | Dynamic values (click text, data layer) |

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

| Parameter | Purpose | Example |

|-----------|---------|---------|

| utm_source | Traffic source | google, newsletter |

| utm_medium | Marketing medium | cpc, email, social |

| utm_campaign | Campaign name | spring_sale |

| utm_content | Differentiate versions | hero_cta |

| utm_term | Paid search keywords | running+shoes |

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

| Tool | Use For |

|------|---------|

| GA4 DebugView | Real-time event monitoring |

| GTM Preview Mode | Test triggers before publish |

| Browser Extensions | Tag Assistant, dataLayer Inspector |

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

| Issue | Check |

|-------|-------|

| Events not firing | Trigger config, GTM loaded |

| Wrong values | Variable path, data layer structure |

| Duplicate events | Multiple containers, trigger firing twice |

Privacy and Compliance

Privacy, consent, retention, deletion, and identifier rules vary by

jurisdiction, audience, data type, contract, and platform configuration. Do not

treat this skill as legal advice or declare a universal consent rule.

Before implementation:

• Identify the actual markets, audience age, data categories, vendors,

purposes, and data flows in scope.

• Review current official regulator and platform requirements for those

jurisdictions and configurations; obtain qualified privacy or legal review

when the requirement is unclear or material.

• Document the approved lawful basis or consent state, retention and deletion

behavior, access controls, and prohibited properties.

• Collect only approved data, avoid direct personal identifiers unless the

reviewed design expressly allows them, and test both allowed and denied

consent paths.

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

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

Tool Integrations

This pack does not ship analytics connectors. Use the user's authorized

property UI, debugger, export, API, or installed connector and verify current

official documentation before constructing a call.

| Tool category | Typical use | Required current proof |

|---------------|-------------|------------------------|

| Web analytics | Sessions, acquisition, web conversions | Debug event plus property readback |

| Product analytics | Event funnels, cohorts, retention | Schema check plus sampled event readback |

| Tag manager | Controlled client-side deployment | Preview trace plus published-version ID |

| Customer data router | Send approved events to destinations | Source receipt plus destination receipt |

| Session replay | Diagnose interaction friction | Consent, masking, sampling, and replay verification |

Boundaries

• Do not claim an event, conversion, consent state, or attribution path works until a current debug or readback proves it.
• Do not mutate production tags, properties, destinations, or consent settings without explicit authorization and a rollback plan.
• Do not collect secrets, direct personal identifiers, or sensitive traits merely because a tool permits them.
• Do not decide business success from a single dashboard number; state the metric definition, window, denominator, and exclusions.

Routing

• Need experiment design or result interpretation -> use suede-ab-testing.
• Need paid-campaign decisions -> use suede-ads.
• Need pipeline and CRM attribution -> use suede-revops.
• Need organic visibility diagnosis -> use suede-seo-audit.
• From those skills, route instrumentation plans and firing verification back to suede-analytics.