Copied to Clipboard
In GTM, create Data Layer Variables for article_category and author_name, then add them as parameters on your GA4 event tag. The parameter name you send must match the name you register exactly — article_category is not the same as articleCategory.
Step 2 — register it in GA4 Admin
Go to Admin → Custom definitions → Custom dimensions → Create custom dimension. Enter a Dimension name (the readable label in reports, e.g. "Article Category"), pick the Scope (Event), and type the Event parameter name exactly as it arrives (article_category). Save. That registration tells GA4 — and connected tools like Looker Studio — to expect the parameter and surface it as a dimension.
Step 3 — verify in DebugView, then wait
Before trusting anything, open DebugView and confirm the parameter is arriving with the right value on the right event. A common agency mistake is registering a dimension before confirming the event actually fires. Once verified, data takes 24–48 hours to populate in standard reports — DebugView is immediate, reports are not.
Real examples by scope
Event-scoped: content category and form name
Event-scoped is right for data that describes a single action. Sending article_category on an article_view lets you see which topics drive engagement. Sending form_name on a form_submit lets you compare your newsletter form against your contact form. Both describe that one interaction and should not persist — which is exactly what event scope does.
User-scoped: membership tier
For stable attributes that should follow the user everywhere, use a user property. Set it on the first event after login, when you have the identity context:
gtag('set', 'user_properties', {
membership_tier: 'premium'
});
Now every subsequent event — page views, purchases, conversions — carries membership_tier, so you can segment any report by plan. The classic mistake is sending this as an event parameter on the login event only, which leaves every later event blank.
Item-scoped: product attributes
Item scope answers product-level questions like revenue per colour or margin tier. The custom parameters go inside each object in the items array of an ecommerce event:
dataLayer.push({
event: 'add_to_cart',
ecommerce: {
items: [{
item_id: 'SKU_12345',
item_name: 'Running Shoes',
item_color: 'blue',
margin_tier: 'high'
}]
}
});
Remember that item-scoped dimensions only appear in Explorations, not standard reports. If you are wiring up ecommerce tracking from scratch, the GA4 ecommerce events guide covers the full items array first.
Common mistakes that silently break your data
The most dangerous mistakes produce no error — your dimension just stays empty or wrong while you assume it works.
-
Wrong scope: event scope for something stable like membership tier (data only on one event), or user scope for something transient like a search term (every future event inherits the wrong value).
-
Name mismatch: the registered name and the sent parameter must be identical, character for character.
-
Passing PII: never send emails, phone numbers, or names as dimension values — it violates Google's Terms and can get your property permanently deleted.
-
High cardinality: dimensions with thousands of unique values (full URLs, user IDs, timestamps) overflow into an aggregated
(other) row and become useless — keep values to a bounded set of categories.
-
Hoarding slots: registering every parameter you ever send. Audit quarterly and retire anything not queried in 90 days.
Also remember the 100-character value limit (with a few exceptions like page_location at 1,000), and that raw exports keep everything regardless — so if you need full history or unregistered fields, lean on BigQuery or server-side tracking.
Which scope should you use?
Work backwards from the question you want to answer rather than from the data you happen to have. If the answer is "per action," reach for event scope; "per person," user scope; "per product," item scope.
-
Event scope — the value describes a single action: content category, button label, form name, video title.
-
User scope — the value is a stable trait of the person: subscription tier, customer type, company size, signup source.
-
Item scope — the value describes a product inside an ecommerce event: colour, size, brand, margin tier.
-
Custom metric instead — the value is numeric and you want to sum or average it: loyalty points, scores, credits.
-
Nothing — if GA4 already captures it; check the built-in dimensions before spending a slot.
Conclusion
Custom dimensions are what turn GA4 from a generic report into a tool that answers your specific questions — but only if you get the fundamentals right. Send the parameter and register it together, pick the scope deliberately, respect the per-property limits, verify in DebugView, and never pass PII. Start with two or three high-value dimensions rather than registering everything, keep a small register of what each one is for, and audit quarterly.
FAQ
Are GA4 custom dimensions retroactive?
No. Data only appears from the moment you register the dimension forward — there is no backfill. If you send a parameter for a week before registering it, reports will miss that week. Raw data streamed to BigQuery keeps the parameter regardless.
What is the difference between an event parameter and a custom dimension?
The parameter is the key-value data sent with an event at collection time. The custom dimension is the GA4 Admin registration that maps that parameter to a readable name and scope, making it visible in reports. Without registration the parameter exists in raw data but not in the GA4 interface.
How many custom dimensions can I create?
On a standard property: 50 event-scoped, 25 user-scoped, 10 item-scoped, plus 50 custom metrics, all per property. Analytics 360 raises these to 125, 100, and 25. Deleting an event-scoped dimension frees its slot after 48 hours; archiving a user-scoped one does not.
Why is my custom dimension showing no data?
Usually one of three reasons: the parameter name does not match the registered name exactly, the event is not actually firing (check DebugView), or you registered it less than 24–48 hours ago. Item-scoped dimensions also only show in Explorations, not standard reports.
Should membership tier be event-scoped or user-scoped?
User-scoped. It is a stable attribute that should follow the user across every event, so set it as a user property after login. As an event parameter on the login event only, it will be blank on all later events.
Can I send personal data as a custom dimension?
No. Passing emails, phone numbers, full names, or other PII violates Google's Terms of Service and can result in your property being permanently deleted. Use non-identifying values like tiers, categories, or hashed identifiers.
A GA4 custom dimension = an event parameter (or user property) you send + a registration in GA4 Admin that maps it to a name and scope. Both are required, and registration is not retroactive (no backfill). Pick scope by the question: per action → event, per person → user, per product → item. Limits per property: 50 event / 25 user / 10 item / 50 metrics — and archiving a user-scoped one never frees the slot. Match parameter names exactly, verify in DebugView, wait 24–48h, and never send PII.