La API de la etiqueta de Google (gtag.js) consta de una sola función, gtag()
, con
la siguiente sintaxis:
gtag(<command>, <command parameters>);
<command>
es uno de los siguientes comandos:<command parameters>
son los parámetros que puedes pasar agtag()
. Los parámetros del comando varían según el comando. Consulta la referencia del comando a continuación.
Puedes invocar comandos gtag()
en cualquier parte de la página, siempre que estos aparezcan debajo del fragmento de la etiqueta de Google. Para obtener información sobre cómo agregar el fragmento a una página, consulta la guía de instalación.
Alcance del parámetro
Puedes definir el alcance de los valores de los parámetros para eventos individuales, todos los eventos enviados a un
<TARGET_ID>
específico o de forma global a todos los eventos. Esto se logra con los comandos event
, config
y set
.
Los valores del parámetro establecidos en un alcance no modifican los valores establecidos para el mismo parámetro en un alcance diferente. En el siguiente ejemplo, el comando config
no modifica el valor global para campaign_id
que se asignó antes con el comando set
. Después de ejecutar ambos comandos, el valor global de campaign_id
sigue siendo '1234'
.
// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });
// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });
Prioridad de los parámetros
Si se asignan valores diferentes al mismo parámetro en distintos alcances, solo se utiliza un valor cuando se procesan los eventos. Los valores de parámetros con alcance
event
tendrán prioridad sobre los parámetros con alcance config
, y los parámetros config
tendrán prioridad sobre los parámetros con alcance global mediante set
.
// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });
// 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>' });
config
Te permite agregar información de configuración adicional a los destinos. Por lo general, esta es una configuración específica del producto, pero solo debes configurarla una vez si usas Google Ads y Google Analytics.
gtag('config', '<TARGET_ID>', {<additional_config_info>});
<TARGET_ID>
es un identificador que identifica de forma única el objetivo de los hits, como una propiedad de Google Analytics o una cuenta de Google Ads.
<additional_config_info>
es uno o más pares parámetro-valor.
En este ejemplo, se configura una etiqueta para enviar datos a una cuenta de Google Ads:
gtag('config', 'TAG_ID');
En el ejemplo anterior, "TAG_ID" es el ID de etiqueta de la etiqueta de Google.
Para demostrar cómo enviar información de configuración adicional, a continuación se muestra un ejemplo
que configura una etiqueta para enviar datos a una cuenta de Analytics con un
parámetro send_page_view
que pasa un valor de false
y un parámetro groups
que pasa un valor de 'agency'
.
gtag('config', 'TAG_ID', {
'send_page_view': false,
'groups': 'agency'
});
get
Te permite obtener varios valores de gtag.js
, incluidos los valores establecidos con el comando set
.
gtag('get', '<target>', '<field_name>', callback)
Argumento | Tipo | Ejemplo | Descripción |
---|---|---|---|
<target> | string |
G-XXXXXXXXXX |
El destino del que se recuperarán los valores. |
<nombre_campo> | FieldName | client_id | El nombre del campo que se obtendrá. |
callback | Function |
(field) => console.log(field) |
Una función que se invocará con el campo solicitado, o |
FieldName
El nombre del campo puede ser el nombre de un campo personalizado que hayas establecido con el comando gtag('set')
, o bien uno de los siguientes valores:
Nombre del campo | Destinos admitidos |
---|---|
client_id |
|
session_id |
|
gclid |
|
Ejemplos
Obtén valor en una promesa
const gclidPromise = new Promise(resolve => {
gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});
gclidPromise.then((gclid) => {
// Do something with gclid...
})
Envía un evento al Protocolo de medición
gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
sendOfflineEvent(clientID, "tutorial_begin")
});
function sendOfflineEvent(clientID, eventName, eventData) {
// Send necessary data to your server...
}
Obtén el valor que establezcas
gtag('set', {campaign_name: 'Spring_Sale'});
gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
// Do something with currency value you set earlier.
})
set
El comando set te permite definir los parámetros que se asociarán con cada evento posterior en la página.
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
Por ejemplo, puedes compartir los parámetros de una campaña para que varias etiquetas de la misma página puedan acceder a ellos.
En el siguiente ejemplo, se ilustra la configuración de un nombre y un ID de campaña para un evento de compras del Black Friday. Debido a que usaste set
, todas las demás etiquetas, por ejemplo, las etiquetas de evento de GA4 o las etiquetas de remarketing de Google Ads, pueden acceder a estos datos.
gtag('set', 'campaign', {
'id': 'abc',
'source': 'google',
'name': 'black_friday_promotion',
'term': 'running+shoes',
});
event
Usa el comando event
para enviar datos de eventos.
gtag('event', '<event_name>', {<event_params>});
<event_name>
es uno de los siguientes:
- Un evento recomendado. Cada evento recomendado puede tener parámetros recomendados.
- Un evento personalizado Un evento personalizado es un nombre de evento arbitrario que creas, con parámetros arbitrarios (es decir, personalizados). Por ejemplo, consulta cómo se usan los eventos personalizados en Google Analytics.
<event_params>
es uno o más pares parámetro-valor. Cada par separado por una coma.
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
Usa el comando consent
para configurar el consentimiento.
gtag('consent', {<consent_arg>}, {<consent_params>});
Consulta consentimiento en el Centro de ayuda para obtener más información sobre el comportamiento que configuran estos parámetros.
<consent_arg>
es uno de 'default'
o 'update'
. 'default'
se usa para establecer los parámetros de consentimiento predeterminados que deben usarse, y 'update'
se usa para actualizar estos parámetros una vez que un usuario indica su consentimiento.
Se admiten los siguientes <consent_params>
:
Nombre del campo | Valores permitidos | Descripción |
---|---|---|
ad_storage |
'granted' | 'denied' |
Habilita el almacenamiento, como las cookies (Web) o los identificadores de dispositivos (aplicaciones), relacionado con la publicidad. |
ad_user_data |
'granted' | 'denied' |
Establece el consentimiento para enviar datos del usuario a Google con fines publicitarios. |
ad_personalization |
'granted' | 'denied' |
Establece el consentimiento para la publicidad personalizada. |
analytics_storage |
'granted' | 'denied' |
Habilita el almacenamiento, como las cookies (Web) o los identificadores de aplicaciones (aplicaciones), relacionados con las estadísticas, p.ej., la duración de las visitas. |
wait_for_update |
cualquier número entero positivo | Establece un tiempo en milisegundos para esperar una llamada de actualización de consentimiento. |