User scoped custom dimensions in Google Analytics 4 using gtag

A user parameter in the GA4 debug view

Given that everything in Google Analytics 4 is an event I expected user scoped custom dimensions to be a regular event parameter as well. They're not. And most of the documentation both from Google and others talks about Google Tag Manager which doesn't help if you're just using gtag. It's not that hard to implement, but figuring out all the pieces was way harder than it should be. I hope this helps the next person...

To create a user scoped custom dimension you need a user property. This is different from an event property. In gtag you need to call set on user_properties with an object containing the user properties to set like this:

If you want the user property on the hit sent with page load do this right before the config call when loading your gtag (you can do it as part of the config call if you're just setting up one tag, or as above before the config call which is helpful if using more than one tag). If you don't know the value of the user property at page load time you can also set it and then send an event.

From the client you can inspect the beacon sent to GA4 for an event, for example:

Event parameters get a prefix of ep or epn. In this case I'm using a parameter rc_score set to 0.9 which appears in the beacon as epn.rc_score=0.9. GA auto-detects numeric values and uses epn for these. The user parameter gets a up prefix and in this case is up.user_quality=low. (In this specific case I'm sending a recapture score as both a custom metric and a user scoped dimension so I can segment out high and low quality users, at least from the perspective of recapture).

More visually you can use the debug view in the configure section of GA4 (why there are settings in the reporting interface as well as the settings interface I have no idea). To use this pass { 'debug_mode':true } to your gtag config call. To confirm that you're getting user properties look for an orange icon in the timeline (see screenshot at the top of this post). There is also a helpful user properties active now box at the bottom right of this screen.

Once you have this working you still need to wire it up in GA4. Wait 24 hours... then go to Configure -> Custom definitions. Add a new custom dimension, make sure you pick user scoped and you should then be able to select the user property to use to populate the dimension.

(Related: Using the Azure Monitor REST API from Google Apps Script; Automate Google PageSpeed Insights and Core Web Vitals Logging with Apps Script; Export Google Fit Daily Steps, Weight and Distance to a Google Sheet)

(You might also like: Catfood: WebCamSaver and PdfScan; Richards Fire Road; Get an email if your site stops being mobile friendly)

(All Code Posts)

Add Comment

All comments are moderated. Your email address is used to display a Gravatar and optionally for notification of new comments and to sign up for the newsletter.

I Thought He Came With You is Robert Ellison's blog.



Average Server Response Time in Azure Metrics