Custom Dimension

A custom dimension is a user-defined attribute you attach to analytics hits to slice metrics by business context that the default reports don’t know about. Think plan = Pro, customer_tier = Enterprise, content_topic = DevOps. Once sent, you can break down core metrics like sessions, users, pageviews, or conversion rate by these values.

Why it matters

Out of the box, tools track generic stuff (source, medium, device). Real analysis happens when you tag traffic with your vocabulary: product SKU, campaign cohort, feature flag, A/B variant, market region, etc. That turns raw events into decision-ready segments.

Scopes (where it “sticks”)

Scope	Attaches to…	Example key=value	Typical use
Hit	Single event/pageview	content_topic=pricing	Analyze engagement for specific pages/events
Session	One visit	landing_bucket=docs	Compare session KPIs by first-touch group
User	Person/device profile	plan=Pro	LTV, churn, retention by customer segment
Item	E-commerce line item	brand=Acme	Revenue by brand/category

Mini-example: Want signup conversion by plan?

1. Define user-scope dimension plan.
2. Send plan with every relevant event (including custom events).
3. Report: conversion_rate(plan) = signups(plan) / sessions(plan).

How to implement (conceptual)

1. Define the dimension (name, scope, allowed values).
2. Populate it on the client or server when the value is known (e.g., after login). Include it with each hit or persist it per scope.
3. Query it as a breakdown in reports, funnels, or cohorts. Combine with event parameters for deeper cuts.

Good practices

• Keep values discrete and stable. Avoid free-form text; prefer enums like plan ∈ {Free, Pro, Enterprise}.
• Minimize high cardinality. Thousands of unique values (e.g., raw URLs) fragment reports.
• Choose the right scope. Don’t store user traits at hit scope; you’ll misattribute metrics.
• Backfill strategy. When values change (plan upgrade), decide whether historical data should reflect the old or new value.

Common pitfalls

• Missing dimension on key events → segments don’t reconcile.
• Inconsistent casing (pro vs Pro) → duplicate segments.
• Late assignment (e.g., set after the conversion fires) → undercounted segments.