
## Table of Contents

1. [Introduction](#introduction)
2. [Prerequisites](#prerequisites)
3. [How to Use gtag to Add User Properties](#how-to-use-gtag-to-add-user-properties)
4. [Configure Custom Definitions for User Properties](#configure-custom-definitions-for-user-properties)
5. [What About the page_view Events for User Properties](#what-about-the-page_view-events-for-user-properties)
6. [GTAG Sample Code](#gtag-sample-code)
7. [Page Load Events Don't Contain the user_properties](#page-load-events-dont-contain-the-user_properties)
8. [Conclusion](#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.
![send ga4 user_properties event](/images/send-user-properties/img1.png)

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.
![send ga4 user_properties and big query](/images/send-user-properties/img2.png)

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.
![big query with user properties](/images/send-user-properties/img3.png)

## 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`.
![Config Custom Dimensions for User Properties](/images/send-user-properties/img4.png)

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.
![User Properties at Big Query](/images/send-user-properties/img5.png)

### 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.
![User Properties at Big Query](/images/send-user-properties/img6.png)

## 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.
![Big Query User Property - First Visit](/images/send-user-properties/img7.png)

Here, we define a dataLayer variable as favorite_color, then create a user property `favorite_color` in the GA4 configuration.
![GA4 Configuration - User Properties](/images/send-user-properties/img7.png)

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.


User-scoped custom dimensions in GA4. This blog shows how to set user properties in GA4 by using gtag or Google Tag Manager.

GTM

How to Set User Properties in GA4