Zaraz: support GA4 custom user scoped dimensions

Zaraz doesn’t currently support user scoped custom dimensions in GA4. When turning on zaraz debug ( you can inspect the URL posted by Zaraz to Google Analytics 4.

If you try

zaraz.set('user_properties', {subscription_type: 'test'});

and configure the GA4 tool to send a default field user_properties, the URL in the server-side network request in debugger will contain:

If you try

zaraz.set('subscription_type', 'test');

and configure the GA4 tool to send a default field ‘subscription_type’, the URL will contain

Neither of these will work since the user property in the URL needs to be prefixed with up instead of ep.

To verify, visit a website with gtag installed ( directly. Follow the google docs ( to set user properties, assuming you’ve already created the custom user scoped dimension (

gtag('set', 'user_properties', {subscription_type: 'test'});

then send an event using, say,

gtag('event', 'test_event');

and inspect the URL in the Network tab of the browser developer tools and find
&up.subscription_type=test in the URL sent to

Zaraz needs to send user properties prefixed with up instead of ep, and developers currently have no control over how Zaraz constructs the server-side URL.

Related issue report: GA4 Custom Dimensions - #4 by shaun16

1 Like

Hey @shaun16, I belive that all you should do is:

zaraz.set('subscription_type', 'test', {scope: 'persist'})

This should add subscription_type to every action the user triggered.

This doesn’t work. {scope: 'persist'} is the default for zaraz.set.
From zaraz.set · Cloudflare Zaraz docs

  • persist: To save the key across sessions. This is the default mode and uses localStorage to save the value.

In the URL sent to Google Analytics there is &ep.subscription_type=test as a query parameter. This prefixed with ep, which makes it an event property. In order to be a user property it needs to be prefixed with up. This remains a feature request for the Zaraz integration with GA4: support specifying user properties.

you can add any User Property to your GA4 actions by adding a custom field and naming it up.YOUR_PROPERTY_NAME. As long as your key starts with up., Zaraz will need prepend ep[n]. to it.