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

Puedes invocar comandos de gtag() en cualquier parte 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 permiso no modifican los valores establecidos para el mismo parámetro en un permiso diferente. En el siguiente ejemplo, el comando config no modifica el valor global de campaign_id asignado antes con el comando set. Después de que se ejecutan 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 permisos, solo se usa un valor cuando se procesan los eventos. Los valores de los parámetros con alcance de event tendrán prioridad sobre los parámetros con alcance de config, y los parámetros de config tendrán prioridad sobre los parámetros con alcance global que usen 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 de un producto, pero solo debes establecerla 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 de eventos. Puede ser un destino, como una propiedad de Google Analytics, una cuenta de Google Ads, un parámetro de 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.

  • Se puede configurar una sola etiqueta de Google (identificada por su ID de etiqueta) para enviar datos a varios destinos. Aunque 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> en el 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 con ese <TARGET_ID> específico. Si bien el ID de etiqueta incluido en la secuencia de comandos src suele cargar la etiqueta de Google, puedes usar cualquier ID de etiqueta válido asociado con tu cuenta en el comando gtag('config').

  • Una sola etiqueta de Google puede tener varios IDs de etiqueta asociados, lo que suele deberse 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 necesitas incluir un único fragmento de la etiqueta de Google con un ID de etiqueta en la secuencia de comandos src. Luego, incluye un comando gtag('config') para cada ID de etiqueta o destino adicional.

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

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

Para demostrar cómo enviar información de configuración adicional, aquí tienes un ejemplo en el que se 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 Es el nombre del campo que se obtendrá.
callback Function (field) => console.log(field)

Es una función que se invocará con el campo solicitado o undefined si no está configurado.

FieldName

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

Nombre del campo Objetivos admitidos
client_id
  • Google Analytics 4
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Ejemplos

Obtén 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 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 un valor que hayas establecido 

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 de la página.

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

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

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 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> puede ser una de las siguientes opciones:

<event_params> es 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'
});

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 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 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 cookies (Web) o identificadores de aplicaciones (aplicaciones), relacionado 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.