Key Insights - Custom Analytics Implementation

This guide explains the topic Custom analytics implementation with practical context. Pageviews only say that /docs received traffic; a custom analytics implementation says whether that traffic wanted API reference, migration steps or billing help, and which plan the reader was on.

Custom dimensions turn generic analytics into useful analytics. Pageviews tell you that /docs received traffic. A custom dimension can tell you whether that traffic was for API docs, migration docs, beginner guides, or enterprise setup pages.

The trick is to add business context without turning analytics into surveillance. Good custom dimensions are coarse, predictable, and tied to decisions. Bad custom dimensions are personal, free-form, and impossible to govern.

What Custom Dimensions Are

A custom dimension is an extra attribute attached to an analytics event, pageview, or visit. Instead of reporting only default fields such as path, referrer, browser, and country, you can report by fields that match your product or content model.

Examples:

• plan_tier: free, pro, business, enterprise
• content_type: blog, docs, comparison, changelog
• page_category: pricing, onboarding, support, integration
• account_age: new, active, mature
• role: owner, admin, member
• experiment_variant: a, b

These are powerful because they answer questions default analytics cannot answer: Do enterprise visitors read security pages before booking a demo? Do free-plan users reach activation docs? Which content categories drive trial signups?

Choose Dimensions From Decisions

Do not start by asking "what can we track?" Start with decisions:

• Which marketing channels bring qualified traffic?
• Which docs reduce support tickets?
• Which product areas drive activation?
• Which plan segment converts from trial to paid?
• Which campaigns attract visitors who actually use the product?

Then define the smallest dimensions needed.

Privacy Rules for Custom Dimensions

Custom dimensions are where analytics teams accidentally collect personal data. GDPR defines personal data broadly, and the CCPA covers information that can reasonably link to a consumer or household. A dimension does not need to be a name to create risk.

Avoid sending:

• email addresses
• names
• phone numbers
• account IDs
• raw user IDs
• wallet addresses
• IP addresses
• exact location
• invoice IDs
• support ticket text
• form field values

Prefer buckets and labels. Use company_size: 11-50 instead of an exact employee count. Use account_age: 30-90d instead of signup timestamp. Use country: DE instead of city-level location unless city is genuinely needed and lawful.

CNIL's audience measurement guidance is a useful benchmark: analytics data should not be combined with unrelated datasets or reused for targeting if you want to stay in low-risk territory.

Implementation Pattern

Define an event schema before shipping:

type AnalyticsContext = {
  content_type?: 'blog' | 'docs' | 'pricing' | 'support';
  plan_tier?: 'free' | 'pro' | 'business' | 'enterprise';
  role?: 'owner' | 'admin' | 'member';
  experiment_variant?: 'a' | 'b';
};

Then attach dimensions consistently:

analytics.track('signup_started', {
  plan_tier: 'pro',
  page_category: 'pricing',
  experiment_variant: 'b',
});

Keep values enumerable where possible. Free text is hard to validate, hard to translate, hard to aggregate, and easy to misuse.

Governance Checklist

Before adding a dimension, write down:

1. Owner: who requested it and who maintains it.
2. Question: what decision it supports.
3. Allowed values: exact list or bucket logic.
4. Privacy review: why it is not personal or why processing is lawful.
5. Retention: how long it remains useful.
6. Dashboard: where it will actually be used.

If nobody can name the dashboard or decision, do not add the dimension.

Common Use Cases

Content performance: Tag articles by topic, funnel stage, and content type. This shows whether privacy compliance guides, product tutorials, or comparison pages drive better conversions.

Product activation: Tag events by setup stage. For a SaaS product, workspace_created, integration_connected, and first_report_viewed often matter more than every click.

B2B qualification: Use coarse firmographic buckets from your own CRM only when appropriate. For example, compare self-serve, mid-market, and enterprise traffic without sending company names to analytics.

Experiments: Attach experiment name and variant to exposure and conversion events. Remove the dimension after the experiment ends if it has no ongoing value.

Reporting Tips

Do not slice every metric by every dimension. That creates tiny segments and false conclusions. Pick a primary dimension for each report:

• acquisition by utm_source
• conversion by page_category
• activation by plan_tier
• retention by account_age
• docs engagement by content_type

Watch for high-cardinality values. If a dimension has thousands of unique values, it may be too granular, too personal, or too messy.

Implementation Sign-Off Checklist

Use this article as the step-by-step implementation guide. Before shipping custom dimensions, confirm:

• Each dimension has an owner, decision, allowed values, and retention expectation.
• Values are enumerable or bucketed where possible.
• No email, name, phone number, account ID, full IP address, token, invoice ID, or free-text form value is sent.
• High-cardinality fields are intentional and reviewed.
• Dashboards actually use the dimension.
• QA confirms the payload matches the event dictionary.

Custom dimensions are powerful because they add context. They become risky when they quietly add identity.

The Bottom Line

Custom dimensions are best when they add context, not identity. Use them to understand groups, pages, campaigns, and product stages. Keep them small, governed, and privacy-aware, and your analytics will become more useful without becoming more invasive.

A naming and value standard

Write a short standard before implementation. Dimension names should be lowercase, readable, and stable, such as page_category, plan_tier, content_type, or signup_source. Values should come from an allowlist whenever possible: pricing, docs, blog, starter, business, enterprise. Avoid values that expose a person, company, exact revenue, email domain, or free-text input.

Also decide how missing values appear. Use unknown or leave the property unset consistently; do not mix blanks, nulls, and custom labels across events. Messy dimension values create reporting errors and privacy review headaches. A clean standard makes custom dimensions easier to query, translate, document, and delete later.

Frequently Asked Questions

What is a custom dimension in analytics?

A custom dimension is an extra attribute attached to an event, pageview, or visit, on top of default fields like path, referrer, browser, and country. It lets you report against your own product or content model, such as plan_tier or content_type. That context turns a generic pageview count into something you can act on.

How is a custom dimension different from a default analytics field?

Default fields come baked into the analytics tool: path, referrer, browser, country. Custom dimensions are ones you define yourself, matched to your product, like role, page_category, or experiment_variant. They answer questions the defaults were never built to answer.

How many custom dimensions should a site track?

Keep the count small and governed rather than tracking everything available. Each one needs an owner, a decision it supports, and a dashboard where it actually gets used. If nobody can name the dashboard or the decision, skip it.

Can a custom dimension carry a raw user ID?

Raw user IDs, account IDs, and similar identifiers belong on the avoid list because they turn a dimension into personal data. Use buckets and labels instead, like company_size: 11-50 rather than an exact count. The goal is context, not identity.

What's the difference between account_age and a signup timestamp?

A signup timestamp is exact and traceable back to one person. account_age bucketed as something like 30-90d gives the same analytical value, whether a user is new or established, without the precision that creates privacy risk. Buckets over exact values is the general rule for custom dimensions.

Who should own a custom dimension?

Every dimension needs a named owner, the person who requested it and maintains it going forward. That sits alongside the decision it supports, its allowed values, a privacy review, and a retention plan in the governance checklist. Without an owner a dimension drifts and nobody notices when it breaks.

Should a custom dimension be removed after an experiment ends?

Yes. Experiment name and variant are attached to exposure and conversion events while the test runs, but once it's over the dimension has no ongoing value. Removing it keeps the schema clean and avoids accumulating dimensions nobody checks anymore.

What is high cardinality and why does it matter for custom dimensions?

High cardinality means a dimension has thousands of unique values instead of a manageable set. That's a sign it's too granular, too personal, or too messy to be useful in a report. Watch for it and treat it as a signal to bucket the values or reconsider the dimension.

Is free text an acceptable value for a custom dimension?

Free text is hard to validate, hard to translate, hard to aggregate, and easy to misuse, so enumerable values are preferred wherever possible. An allowlist like pricing, docs, blog, starter, business, enterprise keeps a dimension queryable and easier to review for privacy. Support ticket text and other free-form fields are explicitly on the list of things to avoid sending.

How does CNIL's audience measurement guidance apply to custom dimensions?

CNIL's guidance treats analytics data as low-risk only when it isn't combined with unrelated datasets or reused for targeting. That's a useful benchmark for custom dimensions specifically, since it's easy to add a field that quietly turns analytics into something closer to profiling. Sticking to context that supports a decision, not identity, keeps a dimension inside that low-risk territory.