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 are setting up user-provided data collection and want to learn how to add a code snippet to their website using gtag.js. Updating the code on your website helps to ensure that email addresses, phone numbers, and/or names and addresses are available on the page when Analytics collects user-provided data.
Overview
To update your website code, you must set the user_data value along with each user-provided data field within an event, config, or set command using the gtag( ) function.
If you pass the same data within two or more command types (for example, event and config), then the event command overrides the config command and the config command overrides the set command. Learn about the Google tag's parameter precedence.
You should update the code on any pages where you collect user-provided data, such as a sign up page, lead generation page, checkout page, or something similar. You can send the data more than once within a session to ensure that the data is sent to Analytics.
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
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: ‘jdoe@example.com’ |
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: ‘+11231234567’ |
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. |
Implementing the fields in your code
On each page where you collect customer data, configure the user_data parameter with each field you want to define.
See an example
The following sample includes variable names for the customer data. Make sure that the variable names in your code match the attributes on your website. For example, if you store email in a variable named “email_address”, then you should update the snippet with that name (for example, where it says yourEmailVariable).
You can also hardcode the field with a string or use a function instead of using variables.
// Implement
<script>
gtag('set', 'user_data', {
"email": yourEmailVariable, ***Change yourEmailVariable to the actual Javascript variable name where you are storing the user’s email data. Do the same for the other variables below. Make sure the values aren't hashed.
"phone_number": yourPhoneVariable,
"address": {
"first_name": yourFirstNameVariable,
"last_name": yourLastNameVariable,
"street": yourStreetAddressVariable,
"city":yourCityVariable,
"region": yourRegionVariable,
"postal_code": yourPostalCodeVariable,
"country": yourCountryVariable
}
});
</script>
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, parentheses, or spaces.
Remove blank fields
If you don't collect certain fields from the previous sample code, remove the fields entirely from the code, rather than leaving them blank. For example, the following shows what a website that only collects email addresses and phone numbers would look like:
<script>
gtag('set', 'user_data', {
"email": {{ yourEmailVariable }},
"phone_number": {{ yourPhoneVariable }}
});
</script>
Add multiple values
You can provide multiple values (up to 3 phone numbers and email addresses, and 2 addresses) using an array. If you capture more than one value, providing this will increase the likelihood of a match.
gtag('set', 'user_data', {
"email": [yourEmailVariable1, yourEmailVariable2],
"phone_number": [yourPhoneVariable1, yourPhoneVariable2],
"address": [
{
{
]
});
</script>