[GA4] Configure o fragmento do código (Gestor de Etiquetas)

Esta funcionalidade faz parte de uma versão beta aberta e está sujeita a alterações.

Estas instruções destinam-se a administradores e editores que querem saber como configurar o fragmento do código para a recolha de dados fornecidos pelos utilizadores nos respetivos Websites através do Gestor de Etiquetas da Google.

A atualização do código, em comparação com outras opções de configuração, ajuda a garantir que os endereços de email, os números de telefone e/ou os nomes e as moradas estão disponíveis na página quando o Analytics recolhe dados fornecidos pelos utilizadores.

Vista geral

Para configurar o fragmento do código com o Gestor de Etiquetas da Google, conclua estes passos:

1. Identifique e defina campos de dados fornecidos pelos utilizadores no código do seu Website
2. Transmita cada campo de dados fornecidos pelos utilizadores numa variável JavaScript personalizada ao Google Analytics

Nota: pode enviar dados de clientes com ou sem hash para o Google Analytics. Quando envia dados sem hash, a Google aplica-lhes hash antes de os armazenar nos respetivos servidores. Contudo, também pode aplicar hash aos dados antes de os enviar para a Google.

Antes de começar

Estas instruções pressupõem que:

• Tem acesso ao código-fonte do seu Website
• Ativou a recolha de dados fornecidos pelos utilizadores e permitiu as capacidades de dados fornecidos pelos utilizadores
• Configurou uma etiqueta Google Analytics: evento do GA4 no contentor do Gestor de Etiquetas da Google
• Tem a função de administradorna 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.

Atualize a etiqueta de eventos com uma variável de JavaScript personalizada

Antes de atualizar o contentor do Gestor de Etiquetas, leia sobre como atualizar o código JavaScript personalizado que vai adicionar ao contentor.

1. Inicie sessão no Gestor de Etiquetas da Google.
2. No separador Espaço de trabalho, clique em Etiquetas à esquerda.
3. Abra a etiqueta Google Analytics: evento do GA4 onde recolhe dados de clientes. Certifique-se de que a etiqueta de eventos usa o ID de medição da stream Web onde os dados do utilizador são recolhidos.
4. Expanda a secção Parâmetros de eventos e clique em Adicionar parâmetro.
5. Introduza user_data no campo "Parâmetro de evento". 
6. No campo "Valor", selecione ou crie uma variável de dados fornecidos pelos utilizadores.
7. Na variável de dados fornecidos pelos utilizadores, se está a criar uma nova variável, selecione Código.

1. No menu pendente Origem de dados, clique em Nova variável….
2. Clique em Configuração da variável > JavaScript personalizado.
3. Introduza um nome para a variável de JavaScript personalizada na parte superior da página.
4. Na caixa de texto JavaScript personalizado, introduza o fragmento do código. Saiba como.
5. Guarde as novas variáveis e, em seguida, guarde a etiqueta de eventos.
6. Na parte superior direita, clique em Enviar para publicar as alterações.

Crie o fragmento do código para recolher dados fornecidos pelos utilizadores

Pode usar o seguinte código quando configurar a variável de JavaScript personalizada no passo 10:

function () {

return {

"email": yourEmailVariable , // substitua yourEmailVariable pelo nome da variável que captura o email do seu utilizador

"phone_number": yourPhoneVariable , // repita o mesmo para yourPhoneVariable, bem como para os seguintes nomes de variáveis

"address": {

"first_name": yourFirstNameVariable ,

"last_name": yourLastNameVariable ,

"street": yourStreetAddressVariable ,

"city": yourCityVariable ,

"region": yourRegionVariable ,

"postal_code": yourPostalCodeVariable ,

"country": yourCountryVariable

}

}

}

Para cada tipo de dados do utilizador no exemplo de código, substitua as variáveis dos marcadores de posição (por exemplo, yourEmailVariable) pelo nome da variável JavaScript global que contém esse fragmento de dados. Se o seu site não recolher um desses campos, deve remover o campo por completo em vez de o deixar em branco.

Em alternativa, pode codificar o campo com uma string ou usar uma função em vez de usar 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 utilizador com hash, pode usar o seguinte fragmento 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 tem de estar no formato E.164, o que significa que tem de ter entre 11 e 15 dígitos, incluindo um prefixo de sinal de adição (+) e o código do país sem traços, parênteses retos ou espaços.

Next steps

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