Referencia de la API de la etiqueta de Google

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:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> son los parámetros que puedes pasar a gtag(). Los parámetros de los comandos varían según el comando. Consulta la referencia de comandos.

Puedes invocar comandos de gtag() en cualquier lugar de tu página, siempre y cuando 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 para todos los eventos. Esto se logra con los comandos event, config y set.

Los valores de los parámetros 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 de campaign_id que se asignó anteriormente 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 diferentes alcances, solo se usará un valor cuando se procesen los eventos. Los valores de los parámetros que se definen para event tendrán prioridad sobre los parámetros definidos para config, y los parámetros de config tendrán prioridad sobre los parámetros que se definen de forma global con 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, se trata de un parámetro de configuración específico del producto, pero solo debes configurarlo una vez si usas Google Ads y Google Analytics.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

Puntos clave sobre <TARGET_ID>:

• El <TARGET_ID> en el comando gtag('config', <TARGET_ID>, ...) es un ID de etiqueta que identifica dónde gtag.js debe enviar los datos del evento. Puede ser un destino, como una propiedad de Google Analytics, una cuenta de Google Ads, una configuración de Floodlight o una etiqueta de Google que tenga varios destinos.

• Un ID de etiqueta, como GT-XXXXXX, G-XXXXXX o AW-YYYYYY, es un identificador de tu etiqueta de Google. Agrega este ID al código de tu sitio web para cargar la etiqueta de Google.

• Una sola etiqueta de Google (identificada por su ID de etiqueta) se puede configurar para enviar datos a varios destinos. Si bien algunos IDs de etiqueta pueden parecer idénticos a los IDs de destino, como G-XXXXXX para una propiedad de Google Analytics o AW-YYYYYY para una cuenta de Google Ads, el <TARGET_ID> del comando config hace referencia a la instancia particular de la etiqueta de Google cargada en la página.

• El comando gtag('config', ...) configura el comportamiento de la etiqueta de Google asociada a ese <TARGET_ID> específico. Si bien el ID de etiqueta incluido en el script src suele cargar la etiqueta de Google, puedes usar cualquier ID de etiqueta válido asociado a tu cuenta en el comando gtag('config').

• Una sola etiqueta de Google puede tener varios IDs de etiqueta asociados, a menudo debido a la combinación de etiquetas. Cualquiera de estos IDs asociados se puede usar en el parámetro src de la secuencia de comandos para cargar la etiqueta de Google.

• Si envías datos a varios destinos o usas varias etiquetas, solo debes incluir un fragmento de la etiqueta de Google con un solo ID de etiqueta en el script src. Luego, incluye un comando gtag('config') para cada ID de etiqueta o destino adicional.

<additional_config_info> son 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');

donde "TAG_ID" es el ID de la etiqueta de la etiqueta de Google.

Para demostrar cómo enviar información de configuración adicional, aquí tienes 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	Es el destino del que se recuperarán los valores.
<field_name>	FieldName	client_id	Nombre del campo que se obtendrá.
callback	Function	(field) => console.log(field)	Función que se invocará con el campo solicitado o undefined si no está configurado.

FieldName

El nombre del campo puede ser el de un campo personalizado que establezcas con el comando gtag('set') o uno de los siguientes valores:

Nombre del campo	Segmentaciones admitidas
client_id	Google Analytics 4
session_id	Google Analytics 4
session_number	Google Analytics 4
gclid	Google Ads Floodlight

Nota: Si usas el comando set con estos nombres de campo, tendrá prioridad el valor que establezcas.

Ejemplos

Cómo obtener un 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 Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Cómo obtener un valor que estableciste

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 parámetros que se asociarán con cada evento posterior en la página.

Nota: Te recomendamos que uses los comandos config o event siempre que sea posible.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

Por ejemplo, puedes compartir parámetros de campaña para que varias etiquetas de la misma página puedan acceder a ellos.

En el siguiente ejemplo, se muestra cómo establecer un nombre y un ID de campaña para un evento de compras del Black Friday. Como usaste set, todas las demás etiquetas, por ejemplo, las etiquetas de eventos 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> puede ser uno de los siguientes:

• Un evento recomendado Cada evento recomendado puede tomar parámetros recomendados.
• Es un evento personalizado. Un evento personalizado es un nombre de evento arbitrario que inventas, con parámetros arbitrarios. Para obtener más información, consulta Cómo configurar eventos.

<event_params> son uno o más pares parámetro-valor. Cada par está 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'
});

Importante: El fragmento de la etiqueta de Google debe aparecer en la misma página, sobre los comandos event, o no se enviarán tus datos.

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 se deben usar, y 'update' se usa para actualizar estos parámetros una vez que el 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 cookies (Web) o identificadores de dispositivos (aplicaciones), relacionado con la publicidad.
ad_user_data	'granted' | 'denied'	Establece el consentimiento para enviar los 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 del consentimiento.