La API de la etiqueta de Google (gtag.js) solo tiene una función, gtag()
, que tiene la siguiente sintaxis:
gtag(<command>, <command parameters>);
<command>
es uno de los siguientes comandos:<command parameters>
son los parámetros que puedes enviar agtag()
. Los parámetros aplicables varían en función del comando que se use. Para obtener más información, consulta la guía de referencia de comandos que encontrarás más abajo.
Puedes invocar comandos gtag()
en cualquier lugar de tu página, siempre que aparezcan debajo del fragmento de la etiqueta de Google. Consulta cómo añadir el fragmento a una página en la guía de instalación.
config
Permite añadir información de configuración a los objetivos. Por lo general, se trata de una configuración específica de un producto concreto, pero solo es necesaria una vez si usas Google Ads y Google Analytics.
gtag('config', '<TARGET_ID>', {<additional_config_info>});
<TARGET_ID>
es el identificador único de los objetivos que se usarán para atribuir los hits, como propiedades de Google Analytics o cuentas de Google Ads.
<additional_config_info>
es uno o varios pares parámetro-valor.
En este ejemplo se configura una etiqueta para enviar datos a una cuenta de Google Ads.
gtag('config', 'TAG_ID');
Debes sustituir "TAG_ID" por el ID de etiqueta de la etiqueta de Google.
Para explicar cómo se envía información de configuración adicional, en este ejemplo se muestra cómo configurar una etiqueta para enviar datos a una cuenta de Analytics con un parámetro send_page_view
que pasa un valor false
, y un parámetro groups
que pasa un valor 'agency'
.
gtag('config', 'TAG_ID', {
'send_page_view': false,
'groups': 'agency'
});
get
Te permite obtener varios valores de gtag.js
, incluidos valores definidos con el comando set
.
gtag('get', '<target>', '<field_name>', callback)
Argumento | Tipo | Ejemplo | Descripción |
---|---|---|---|
<target> | string |
UA-XXXXXXXX-Y |
Objetivo del que se obtienen los valores. |
<field_name> | FieldName | client_id | Nombre del campo que se va a obtener. |
retrollamada | Function |
(field) => console.log(field) |
Función que se invocará con el campo solicitado, o
con |
FieldName
El nombre del campo puede ser el nombre del campo personalizado que has definido con el comando gtag('set')
, o bien uno de estos valores:
Nombre del campo | Objetivos admitidos |
---|---|
client_id |
|
session_id |
|
gclid |
|
Ejemplos
Asignar un valor a una Promesa
const gclidPromise = new Promise(resolve => {
gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});
gclidPromise.then((gclid) => {
// Do something with gclid...
})
Enviar un evento al Protocolo de medición
gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
sendOfflineEvent(clientID, "tutorial_begin")
});
function sendOfflineEvent(clientID, eventName, eventData) {
// Send necessary data to your server...
}
Obtener un valor que se ha definido
gtag('set', {currency: 'USD'});
gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
// Do something with currency value you set earlier.
})
set
Permite establecer valores que se mantienen en todas las llamadas de gtag()
que se hagan después de ejecutar este comando en la página.
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
<parameter-value-pair>
indica un nombre clave concreto y el valor fijo que debe tener en las llamadas siguientes de gtag()
. Por ejemplo, el código que aparece a continuación asigna el valor 'US'
a country
y el valor 'USD'
a currency
en todos los eventos posteriores que ocurran en la página.
gtag('set', {
'country': 'US',
'currency': 'USD'
});
Utilizar el comando set
no es lo mismo que pasar valores directamente al comando event
. Cuando se pasan valores concretos al comando event
, solo se aplican en el momento de activar dicho evento. Al usar set
, los valores persisten en la página que esté activa en ese momento y se pasan a todos los eventos posteriores. Para ver cómo funciona, compara los dos ejemplos siguientes:
gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');
y
gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');
En el primer ejemplo, se pasará el evento login
con un valor method
que será 'Google'
, y el evento share
se pasará sin ningún parámetro. En el segundo ejemplo, ambos eventos login
y share
se pasarán con un valor method
que será 'Google'
.
event
El comando event
sirve para enviar datos de eventos.
gtag('event', '<event_name>', {<event_params>});
<event_name>
puede ser uno de los siguientes tipos de evento:
- Un evento recomendado. Se pueden aplicar parámetros recomendados a los eventos recomendados.
- Un evento personalizado. Los eventos personalizados son eventos con nombres arbitrarios inventados a los que se aplican parámetros arbitrarios, es decir, personalizados. Si quieres ver ejemplos, consulta cómo se usan los eventos personalizados en Google Analytics.
<event_params>
es uno o varios pares parámetro-valor. Si hay más de uno, deben separarse con comas.
El siguiente comando event
activa el evento recomendado screen_view
con dos parámetros: app_name
y screen_name
.
gtag('event', 'screen_view', {
'app_name': 'myAppName',
'screen_name': 'Home'
});
consent
Utiliza el comando consent
para configurar el consentimiento.
gtag('consent', {<consent_arg>}, {<consent_params>});
Consulta el artículo sobre consentimiento del Centro de Ayuda para obtener más información sobre el comportamiento de las etiquetas, que se define a través de estos parámetros.
El valor de <consent_arg>
puede ser 'default'
o 'update'
. Al asignar el valor 'default'
a los parámetros de consentimiento que se deben usar, se indica que son predeterminados. Al asignar el valor 'update'
, se indica que esos parámetros deben actualizarse una vez que un usuario indica su consentimiento.
Estos son los parámetros <consent_params>
y valores que se pueden usar:
Nombre del campo | Valores permitidos |
---|---|
ad_storage |
'granted' | 'denied' |
analytics_storage |
'granted' | 'denied' |
wait_for_update |
Cualquier número entero positivo |
Ámbito de los parámetros
Puedes asociar el valor de los parámetros a eventos concretos, a todos los eventos enviados a un elemento <TARGET_ID>
específico o a todos los eventos de forma global. Para ello, se utilizan los comandos event
, config
y set
.
Los valores de un parámetro que se hayan configurado para tener un ámbito determinado no modifican los valores del mismo parámetro que se hayan configurado para tener otro ámbito. En el ejemplo siguiente, el comando config
no modifica el valor global de currency
que se había asignado previamente con el comando set
. Después de ejecutar ambos comandos, el valor global de currency
sigue siendo 'EUR'
.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });
Prioridad de los parámetros
Si se asignan diferentes valores al mismo parámetro de forma que tengan diferentes ámbitos, se utilizará un solo valor cuando se procesen eventos. Los valores de parámetros que se hayan configurado con un ámbito event
tendrán prioridad sobre que tengan un ámbito config
, y los parámetros config
tendrán prioridad sobre los que se hayan configurado con un ámbito global utilizando el comando 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>' });