A API gtag.js consiste em uma única função, gtag()
, com a seguinte sintaxe:
gtag(<command>, <command parameters>);
<command>
é um dos seguintes comandos:<command parameters>
são os parâmetros a serem enviados para agtag()
. Esse tipo de parâmetro varia de acordo com o comando. Consulte a referência de comandos abaixo.
Você pode invocar comandos gtag em qualquer local da sua página, desde que estejam abaixo do snippet global. Para saber como adicionar o snippet global em uma página, consulte a orientação sobre snippet.
config
Permite incluir mais informações de configuração nos destinos. Essa configuração normalmente é específica para um produto, como o Google Ads ou o Google Analytics.
gtag('config', '<TARGET_ID>', {<additional_config_info>});
<TARGET_ID>
identifica exclusivamente o destino dos hits, como uma propriedade do Google Analytics ou uma conta do Google Ads.
<additional_config_info>
representa um ou mais pares de valor de parâmetro.
Neste exemplo, uma tag é configurada para enviar dados a uma conta do Google Ads:
gtag('config', 'AW-CONVERSION_ID');
O comando config
também pode ser usado com o Google Analytics:
gtag('config', 'GA_MEASUREMENT_ID');
Veja como enviar outras informações sobre "config" no exemplo abaixo, em que uma tag é configurada para enviar dados a uma conta do Google Analytics usando um parâmetro send_page_view
com um valor false
e um parâmetro groups
definido como 'agency'
.
gtag('config', 'GA_MEASUREMENT_ID', {
'send_page_view': false,
'groups': 'agency'
});
get
Permite enviar diversos valores da gtag.js
, incluindo conjuntos de valores com o comando set
.
gtag('get', '<target>', '<field_name>', callback)
Argumento | Tipo | Exemplo | Descrição |
---|---|---|---|
<target> | string |
UA-XXXXXXXX-Y |
Destino em que os valores serão buscados. |
<field_name> | FieldName | client_id | Nome do campo que será recebido. |
callback | Function |
(field) => console.log(field) |
Função que será invocada com o campo solicitado, ou |
FieldName
O nome do campo pode ser o nome de um campo personalizado definido com o comando gtag('set')
, ou um dos seguintes valores:
Nome do campo | Destinos compatíveis |
---|---|
client_id |
|
session_id |
|
gclid |
|
Exemplos
Ver um valor para um Promise
const gclidPromise = new Promise(resolve => {
gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});
gclidPromise.then((gclid) => {
// Do something with gclid...
})
Enviar evento para o Protocolo de avaliação
gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
sendOfflineEvent(clientID, "tutorial_begin")
});
function sendOfflineEvent(clientID, eventName, eventData) {
// Send necessary data to your server...
}
Ver um valor que você definiu
gtag('set', {currency: 'USD'});
gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
// Do something with currency value you set earlier.
})
set
Permite que você defina valores que permanecem em todas as chamadas da gtag()
subsequentes na página.
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
O valor do nome de chave <parameter-value-pair>
deve ser mantido nas chamadas de gtag()
. Por exemplo, o código abaixo define o valor de country
como 'US'
e de currency
como 'USD'
para todos os eventos subsequentes na página:
gtag('set', {
'country': 'US',
'currency': 'USD'
});
Há diferenças entre usar o comando set
e transmitir os valores diretamente para o event
. Quando você envia os valores diretamente para um comando event
, eles são aplicados apenas ao evento disparado. No entanto, ao usar set
, os valores permanecem na página atual e são transmitidos para todos os eventos subsequentes. Veja a seguir a diferença entre os dois exemplos:
gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');
e
gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');
No primeiro exemplo, o evento login
é enviado com um valor method
definido como 'Google'
, e o evento share
é transmitido sem parâmetros. No segundo, tanto login
quanto share
são transferidos com um valor method
'Google'
.
event
Use o comando event
para enviar dados de eventos.
gtag('event', '<event_name>', {<event_params>});
<event_name>
pode ser:
- um evento recomendado, que aceita parâmetros recomendados;
- um evento personalizado, ou seja, um nome de evento arbitrário criado por você, com parâmetros arbitrários (ou seja, personalizados). Por exemplo, veja como eventos personalizados são usados no Google Analytics.
<event_params>
representa um ou mais pares de valor de parâmetro, em que cada par é separado por uma vírgula.
O comando event
a seguir dispara o evento recomendado screen_view
com dois parâmetros: app_name
e screen_name
.
gtag('event', 'screen_view', {
'app_name': 'myAppName',
'screen_name': 'Home'
});
Escopo do parâmetro
É possível definir o escopo dos valores de parâmetro para um evento individual, além de enviar todos os eventos para um <TARGET_ID>
específico ou globalmente para todos os eventos. Se quiser fazer isso, use os comandos event
, config
e set
.
Os valores de parâmetro definidos em um escopo não modificam aqueles estabelecidos para o mesmo parâmetro em outro escopo. No exemplo abaixo, o comando config
não altera o valor global de currency
atribuído anteriormente com set
. Quando os dois comandos forem executados, o valor global de currency
ainda será 'EUR'
.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });
Precedência do parâmetro
Se valores diferentes forem atribuídos ao mesmo parâmetro em escopos diferentes, apenas um valor será usado durante o processamento de eventos. Os valores de parâmetros com escopo event
terão prioridade sobre aqueles com escopo config
. Além disso, os parâmetros config
prevalecerão sobre aqueles que têm escopo global e usam set
.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });
// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });
// Process a conversion event with currency: 'EUR'
gtag('event','conversion');
// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });