How to Set User Properties in GA4

Table of Contents

1. Introduction
2. Prerequisites
3. How to Use gtag to Add User Properties
4. Configure Custom Definitions for User Properties
5. What About the page_view Events for User Properties
6. GTAG Sample Code
7. Page Load Events Don't Contain the user_properties
8. Conclusion

Introduction

This blog shows how to add user properties to Google Analytics 4 (GA4). We'll demonstrate how to use gtag or Google Tag Manager to achieve this. For each approach, we'll also show how the actual user properties data appears in BigQuery for GA4.

Prerequisites

This blog assumes your website is already set up with GA4 via Google Tag Manager, and the gtag and dataLayer global variables are available on your page.

• Website is set up with GA4.
• https://www.googletagmanager.com/gtag/js is loaded.

How to Use gtag to Add User Properties

Here we'll start with how to use gtag to add user properties to GA4, and we'll verify the results in BigQuery as well.

The following is an example code snippet that fires a GA4 event with user properties. The first line of code sets the user_properties with the key favorite_color. We assume favorite_color is a user-specific attribute related to your site, so we set it to "blue". The next line sends the GA4 event test_up_data1 to GA4.

gtag("set", "user_properties", {favorite_color: "blue"});
gtag("event", "test_up_data1", {other_data: "test up properties"});

When you run the above code from your browser console, you should see a GA4 event being sent from your browser as shown below. ep is event parameters, and up is user properties.

How does the above appear in BigQuery? You can see in the BigQuery table that the event we just fired from our browser has been received, and the user_properties contain favorite_color with the value present. Also, you'll notice the page_view and user_engagement events don't have that value. These two events are fired by GA4 and are automatically collected.

Now, if you run the same code again in the same browser, you'll notice the browser fires the event but without the user properties favorite_color field.

gtag("set", "user_properties", {favorite_color: "blue"});
gtag("event", "test_up_data1", {other_data: "test up properties"});

This is the BigQuery result after we made the second gtag request from the browser. Although we included the set with user properties, no user properties were added to the same event.

Configure Custom Definitions for User Properties

It's not clear why using gtag with set for user properties has the above behavior, where only the first event sent to BigQuery contains the user_properties. It appears we need to configure the user property in GA4's Custom definitions section.

The following shows how to configure the user property in Custom definitions. As you can see below, we create a dimension named favorite_color with the Scope set to User.

After setting the custom dimensions in the GA4 property, it might take some time for the results to take effect. We performed the following test. The user_pseudo_id is stored in the GA4 BigQuery table. You can see that when we load the page, the browser fires several events — first_visit, scroll, session_start, and page_view — and none of them have favorite_color in the user_properties table. After the page loads, we fired the same event test_up_data1 a few times, and you can see they all have the favorite_color record.

Next, you can see that we fired test_up_data which contains favorite_color, and then we also fired another event test_up_data2. You'll notice this custom event also contains the user property favorite_color. So it appears that after we use gtag to set the user properties along with the configuration in the GA4 property, any custom event after the set will also include the same user properties. This makes sense as it's the user scope of events.

What About the page_view Events for User Properties

We also performed another test as shown below. You can see that we start a new session (since the user_pseudo_id changed). When we first load the page, the page_view's user_properties is empty. But once we manually run the code above, you can see events with the favorite_color user property filled into the automatically collected events. Any other event will also include the same user properties. In addition, you can see that when we load the page again within the same session, the user properties still contain the same favorite_color value.

GTAG Sample Code

The following is the sample code from above. Once you click the button, the subsequent events including page_view will also include the user property favorite_color. Also, you need to add favorite_color to the custom dimensions in the GA4 property.

<button
  className="ga4"
>
test_up_data1
</button>

<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '{Measurement ID}', {
      send_page_view: false
});

var buttonEle = document.querySelector(".ga4");
buttonEle.addEventListener('click', function(e) {
    gtag("set", "user_properties", {favorite_color: "blue"});
    gtag("event", "test_up_data1", {other_data: "test up properties"});
});
</script>

Page Load Events Don't Contain the user_properties

There's one issue with the above code. If you start the page from a new session, the page view events don't contain the user_properties we set earlier. To solve this, we can use dataLayer along with user properties in the GA4 configuration.

Here, we define a dataLayer variable as favorite_color, then create a user property favorite_color in the GA4 configuration.

Now, we just need to add the code to the page during page load. Make sure the code below is placed before the GTM scripts.

// place this code before gtm load scripts.
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
    favorite_color: "green"
})

Conclusion

In summary, if you have GA4 fields that are user properties, the following looks like the correct implementation:

• Create a custom dimension in the GA4 property with the type set to User.
• Create a dataLayer variable for your property.
• Create a GA4 configuration and set the dataLayer variable as a user property.
• In your code, set the dataLayer value before the GTM script loads.

Now, page view and any subsequent events' user_properties should contain your new user property.