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 comando varían según el comando. Consulta la referencia de comandos que se incluye a continuación.

Puedes invocar comandos gtag() en cualquier lugar de tu página, siempre que 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 específico <TARGET_ID>, o de forma global para todos los eventos. Para ello, se usan 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 asignado anteriormente 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' });

Precedencia de los parámetros

Si se asignan valores diferentes al mismo parámetro en diferentes alcances, solo se usa un valor cuando se procesan los eventos. Los valores de los parámetros definidos para event tendrán prioridad sobre los parámetros definidos para config, y los parámetros config tendrán prioridad sobre los parámetros definidos 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 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 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 o una cuenta de Google Ads, o bien una etiqueta de Google que tenga varios destinos. <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 mostrar 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 send_page_view parámetro que pasa un valor de false y un groups parámetro 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 set comando.

gtag('get', '<target>', '<field_name>', callback)

Argumento	Tipo	Ejemplo	Descripción
<target>	`string`	G-XXXXXXXXXX	El destino del que se recuperarán los valores.
<field_name>	FieldName	client_id	El nombre del campo que se debe obtener.
callback	`Function`	`(field) => console.log(field)`	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 establezcas con el gtag('set') comando o uno de los siguientes valores:

Nombre del campo	Destinos 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 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.

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

Un evento recomendado. Cada evento recomendado puede tomar parámetros recomendados.
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> 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'
});

`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 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 cookies (Web) o identificadores de dispositivos (apps), 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 apps (apps), relacionado con 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.