[GA4] Set up the code snippet (Tag Manager)

This feature is part of an open beta. Keep in mind that the feature is subject to change.

These instructions are for administrators and editors who want to learn how to set up the code snippet for user-provided data collection on their website using Google Tag Manager.

Updating your code, when compared to the other configuration options, helps to ensure that the email addresses, phone numbers, and/or names and addresses are available on the page when Analytics collects user-provided data.

Overview

To set up the code snippet using Google Tag Manager, complete these steps:

1. Identify and define user-provided-data fields in your website code
2. Pass each user-provided-data field in a custom JavaScript variable to Google Analytics

Note: You can send hashed or unhashed customer data to Google Analytics. When you send unhashed data, Google hashes the data for you before storing the data in Google's servers. But you can also hash the data on your end before sending the data to Google.

Before you begin

These instructions assume that you have the following:

• Access to your website source code
• Activated user-provided data collection and allowed user-provided data capabilities
• Set up a Google Analytics: GA4 Event tag in your Google Tag Manager container
• The Administrator role to the Google Analytics property​

Hashing the data

You can send hashed or unhashed data from a website. If you send unhashed data, Google normalizes and hashes the data before the data reaches Google's servers. To ensure Analytics interprets the data correctly and to comply with the User-provided data policy, you must use the correct key name (in the next section).

To hash the data:

• Use hex SHA256.

To normalize the data:

• Remove leading or trailing whitespaces.
• Convert the text to lowercase.
• Format phone numbers according to the E.164 standard.

Defining the fields in your code

You must provide at least one of these fields:

• Email (preferred).
• Address (first name, last name, postal code, and country are required). You can optionally provide street address, city, and region as additional match keys.
• A phone number can also be provided along with an email or full name and address.

Make sure the data is available when the Google tag fires. If the data is collected on a previous page, make sure it’s available in your code on the current page so you can configure the field.

Fields to set

The following table describes each field you can set. The key name shows how you must reference the field in your code. You must pass the data as a String type. When defining name and address, make sure to define each component as an individual variable (for example, first name, last name, and so on).

Note: If you want to send unhashed data and let Google normalize and hash the data, use the first key name for each data field. For example, email in the Email address data field below. If you want to send hashed data, use the key name that begins with sha256_.

Data Field	Key Name	Description
Email address	email	User email. Example: ‘[e-mail]’
	sha256_email_address	Hashed user email. Example: ‘a8af8341993604f29cd4e0e5a5a4b5d48c575436c38b28abbfd7d481f345d5db’
Phone number	phone_number	User phone number. Must be in E.164 format, which means it must be 11 to 15 digits including a plus sign (+) prefix and country code with no dashes, parentheses, or spaces. Example: ‘[phone]’
	sha256_phone_number	Hashed user phone number. Example: ‘e9d3eef677f9a3b19820f92696be53d646ac4cea500e5f8fd08b00bc6ac773b1’
First name	address.first_name	User first name. Example: 'John'
	address.sha256_first_name	Hashed user first name. Example: ‘96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a’
Surname	address.last_name	User last name. Example: 'Doe'
	address.sha256_last_name	Hashed user last name. Example: ‘799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f’
Street address	address.street	User street address. Example: '123 New Rd'
City	address.city	User city name. Example: `Southampton’
Region	address.region	User province, state, or region. Example: `Hampshire’
Postal code	address.postal_code	User post code. Example: 'SO99 9XX'
Country	address.country	User country code. Example: 'UK'. Use 2-letter country codes, per the ISO 3166-1 alpha-2 standard.

Update the event tag with a custom JavaScript variable

Before you update your Tag Manager container, read about how to update the custom JavaScript code you'll add to your container.

1. Sign in to Google Tag Manager.
2. From the Workspace tab, click Tags on the left.
3. Open the Google Analytics: GA4 Event tag where you collect customer data. Make sure the event tag uses the measurement ID for the web stream where the user data is collected.
4. Select Include user-provided data from your website.
   
5. In the User Data drop-down menu, select or create a User-Provided Data variable.
6. If you're creating a new variable, in the User-Provided Data variable, select Code.
   
7. In the Data Source drop-down menu, click New Variable....
8. Click Variable Configuration > Custom JavaScript.
9. Enter a name for the custom JavaScript variable at the top of the page.
10. In the Custom JavaScript text box, enter the code snippet. Learn how.
11. Save the new variables, then save the event tag.
12. In the top right, click Submit to publish the changes.

Create the code snippet to collect user-provided data

You can use the following code when you're setting up the custom JavaScript variable in step 10:

function () {

return {

"email": yourEmailVariable , // replace yourEmailVariable with variable name that captures your user’s email

"phone_number": yourPhoneVariable , // repeat for yourPhoneVariable and following variable names below

"address": {

"first_name": yourFirstNameVariable ,

"last_name": yourLastNameVariable ,

"street": yourStreetAddressVariable ,

"city": yourCityVariable ,

"region": yourRegionVariable ,

"postal_code": yourPostalCodeVariable ,

"country": yourCountryVariable

}

}

}

For each type of user data in the code sample, replace the placeholder variables (e.g., yourEmailVariable) with the name of the global javascript variable containing that piece of data. If your site doesn't collect one of those fields, remove the field entirely rather than leaving it blank.

Alternatively, you can hardcode the field with a string or use a function instead of using variables.

// Implement
<script>
gtag('set', 'user_data', {
"sha256_email_address": yourNormalizedandHashedEmailVariable,
"sha256_phone_number": yourNormalizedandHashedPhoneVariable,
"address": {
"address.sha256_first_name": yourNormalizedandHashedFirstNameVariable,
"address.sha256_last_name": yourNormalizedandHashedLastNameVariable,
"city": yourCityVariable,
"region": yourRegionVariable,
"postal_code": yourPostalCodeVariable,
"country": yourCountryVariable
}
});
</script>

If you'd like to provide hashed user data values, you can use the following example snippet:

async function processUserData() {
const userData = {
'sha256_email_address': await hashEmail(email.trim()),
'sha256_phone_number': await hashPhoneNumber(phoneNumber),
'address': {
'address.sha256_first_name': await hashName(firstName),
'address.sha256_last_name': await hashName(lastName),
'city': city,
'region': region,
'postal_code': postalCode,
'country': country,
},
};
return userData;

The phone number must be in E.164 format, which means it must be 11 to 15 digits including a plus sign (+) prefix and country code with no dashes, brackets or spaces.

Next steps

Validate that user-provided data collection is set up correctly. Show me how.