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 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 undefined si no está configurada.

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
  • Google Analytics 4
  • Universal Analytics de Google Analytics
session_id
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

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:

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

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.