Published on 2025-06-22T07:23:33Z

What is a Custom Dimension in Analytics? Examples and Implementation

A custom dimension is a user-defined attribute you can attach to events in analytics platforms. It extends the built-in data model—such as page URL or browser type—allowing you to collect and analyze information tailored to your business needs. By defining custom dimensions, you can segment users more precisely, filter reports on unique attributes, and gain deeper insights into user behaviors. This article covers the concept of custom dimensions in both Google Analytics 4 (GA4) and PlainSignal, including setup, code examples, and best practices.

Illustration of Custom dimension
Illustration of Custom dimension

Custom dimension

Custom dimensions are user-defined attributes added to analytics events for tailored segmentation and reporting.

Overview of Custom Dimensions

Custom dimensions are user-defined attributes you can attach to events in analytics platforms. They extend the default data model, allowing you to collect and analyze customized information beyond built-in dimensions such as page URL or browser type. By defining custom dimensions, you can tailor your reporting to specific business needs, segment users more precisely, and gain deeper insights into user behavior.

  • Definition

    A custom dimension is a name-value pair that you define and send to your analytics tool with your event data. For example, you might capture “membership_level” or “user_type” as custom dimensions.

  • Scope types

    Custom dimensions can have different scopes—hit, session, user, or product—determining how they are aggregated and reported.

    • Hit scope

      Applies to a single event or pageview.

    • Session scope

      Persists for the duration of a session.

    • User scope

      Persists across all sessions for a user.

    • Product scope

      Specific to ecommerce items.

Implementing Custom Dimensions in GA4

In Google Analytics 4 (GA4), custom dimensions require both configuration in the GA4 interface and the sending of event parameters in your tracking code. Follow these steps to set up a custom dimension for your site or app.

  • Configure in GA4

    In the GA4 admin, navigate to Configure > Custom definitions and click “Create custom dimension.” Fill in the name, parameter name, scope, and description.

  • Send parameter via gtag.js

    Add the custom dimension as an event parameter in your gtag.js tracking code.

    • Example code

      gtag('event', 'purchase', {
  'item_id': 'SKU123',
  'membership_level': 'gold'
});

  • Register parameter

    After sending data, register the event parameter under GA4 custom definitions so it appears in your reports.

Implementing Custom Dimensions in PlainSignal

PlainSignal is a cookie-free analytics solution that offers a simple API for tracking events and custom dimensions. You can inject the tracking script directly into your site and use the PlainSignal JavaScript function to set custom dimensions.

  • Include PlainSignal script

    Embed the PlainSignal tracking snippet in your site’s <head> section to initialize data collection.

    • Script tag

      <link rel="preconnect" href="//eu.plainsignal.com/" crossorigin />
<script defer data-do="yourwebsitedomain.com" data-id="0GQV1xmtzQQ" data-api="//eu.plainsignal.com" src="//cdn.plainsignal.com/plainsignal-min.js"></script>

  • Set and track custom dimensions

    Use the PlainSignal API to attach custom dimensions to your events.

    • Example code

      PlainSignal('setCustomDimension', 'user_type', 'premium');
PlainSignal('track', 'page_view');

Best Practices

Follow these guidelines to ensure accurate and meaningful custom dimension data.

  • Consistent naming

    Use clear, descriptive names with a consistent format (e.g., snake_case) to avoid confusion.

  • Limit dimensions

    Track only necessary dimensions to reduce complexity and avoid hitting platform limits.

  • Validate data

    Regularly test your implementation to ensure data is sent correctly and appears in reports.

Related terms