[GA4] Configurar o snippet de código (Gerenciador de tags)

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

Estas instruções são destinadas a administradores e editores que querem configurar o snippet de código para coleta de dados fornecidos pelo usuário no site usando o Gerenciador de tags do Google.

Em comparação com as outras opções de configuração, atualizar o código ajuda a garantir que os endereços de e-mail, números de telefone e/ou nomes e endereços estejam disponíveis na página quando o Google Analytics coleta dados fornecidos pelo usuário.

Visão geral

Para configurar o snippet de código usando o Gerenciador de tags do Google, siga estas etapas:

1. Identifique e defina os campos de dados fornecidos pelo usuário no código do site.
2. Transmita cada campo de dados fornecidos pelo usuário em uma variável JavaScript personalizada para o Google Analytics.

Observação: é possível enviar dados do cliente com ou sem hash para o Google Analytics. Quando você envia dados sem hash, o Google gera o hash antes de armazenar as informações nos nossos servidores. Mas também é possível gerar um hash dos dados antes de enviá-los ao Google.

Antes de começar

Estas instruções consideram que:

• você tenha acesso ao código-fonte do site
• a coleta de dados fornecidos pelo usuário esteja ativada e que os recursos desses dados tenham sido permitidos
• haja uma tag de evento do Google Analytics: GA4 configurada no seu contêiner do Gerenciador de tags
• o papel de administrador seja da propriedade do Google Analytics

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.

Atualizar a tag de evento com uma variável JavaScript personalizada

Antes de atualizar o contêiner do Gerenciador de tags, saiba como fazer update do código JavaScript personalizado que você vai adicionar ao contêiner.

1. Faça login no Gerenciador de tags do Google.
2. Na guia Espaço de trabalho, clique em Tags à esquerda.
3. Abra a tag Google Analytics: evento do GA4 em que você coleta dados do cliente. Verifique se a tag de evento usa o ID de métricas para o fluxo da Web em que os dados do usuário são coletados.
4. Selecione Incluir dados do seu site fornecidos pelo usuário.
   
5. No menu suspenso Dados do usuário, selecione ou crie uma variável de dados fornecidos pelo usuário.
6. Ao criar uma nova variável, selecione Código em "Dados fornecidos pelo usuário".
   
7. No menu suspenso Origem de dados, clique em Nova variável....
8. Clique em Configuração da variável > JavaScript personalizado.
9. Insira um nome para a variável personalizada de JavaScript na parte de cima da página.
10. Na caixa de texto JavaScript personalizado, insira o snippet de código. Saiba como.
11. Salve as novas variáveis e a tag de evento.
12. No canto superior direito, clique em Enviar para publicar as mudanças.

Criar o snippet de código para coletar dados fornecidos pelo usuário

Você pode usar o seguinte código ao configurar a variável JavaScript personalizada na etapa 10:

function () {

return {

"email": yourEmailVariable , // substitua "yourEmailVariable" pelo nome da variável que captura o e-mail do usuário

"phone_number": yourPhoneVariable , // repita para "yourPhoneVariable" e para os nomes de variáveis abaixo

"address": {

"first_name": yourFirstNameVariable ,

"last_name": yourLastNameVariable ,

"street": yourStreetAddressVariable ,

"city": yourCityVariable ,

"region": yourRegionVariable ,

"postal_code": yourPostalCodeVariable ,

"country": yourCountryVariable

}

}

}

Para cada tipo de dados do usuário no exemplo de código, substitua as variáveis de marcador de posição (por exemplo, "yourEmailVariable") pelo nome da variável JavaScript global que contém essa parte dos dados. Se o site não coletar um desses campos, remova o campo totalmente em vez de deixar essa parte em branco.

Outra opção é fixar o campo no código com uma string ou usar uma função em vez de variáveis.

// 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>

Se quiser fornecer valores de dados do usuário com hash, use o seguinte snippet de exemplo:

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;

O número de telefone precisa estar no formato E.164, isto é, ter de 11 a 15 dígitos e incluir um prefixo de sinal de adição (+) e um código de país sem traços, parênteses ou espaços.

Next steps

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