Referencia de la API de la etiqueta de Google

La API de la etiqueta de Google (gtag.js) solo tiene una función, gtag(), que tiene 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 enviar a gtag(). Los parámetros aplicables varían en función del comando que se use. Para obtener más información, consulta la guía de referencia de comandos que encontrarás más abajo.

Puedes invocar comandos gtag() en cualquier lugar de tu página, siempre que aparezcan debajo del fragmento de la etiqueta de Google. Consulta cómo añadir el fragmento a una página en la guía de instalación.

Ámbito de los parámetros

Puedes asociar el valor de los parámetros a eventos concretos, a todos los eventos enviados a un elemento <TARGET_ID> específico o a todos los eventos de forma global. Para ello, se utilizan los comandos event, config y set.

Los valores de un parámetro definidos con un ámbito determinado no modifican los valores del mismo parámetro definidos para tener otro ámbito. En el ejemplo siguiente, el comando config no modifica el valor global de campaign_id que se había asignado previamente 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 diferentes valores al mismo parámetro de forma que tengan diferentes ámbitos, se utilizará un solo valor cuando se procesen eventos. Los valores de parámetros que se hayan configurado con un ámbito event tendrán prioridad sobre que tengan un ámbito config, y los parámetros config tendrán prioridad sobre los que se hayan configurado con un ámbito global utilizando el comando 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`

Permite añadir información de configuración a los objetivos. Por lo general, se trata de una configuración específica de un producto concreto, pero solo es necesaria una vez si usas Google Ads y Google Analytics.

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

<TARGET_ID> es el identificador único de los objetivos que se usarán para atribuir los hits, como propiedades de Google Analytics o cuentas de Google Ads. <additional_config_info> es uno o varios pares parámetro-valor.

En este ejemplo se configura una etiqueta para enviar datos a una cuenta de Google Ads.

gtag('config', 'TAG_ID');

Debes sustituir "TAG_ID" por el ID de etiqueta de la etiqueta de Google.

Para explicar cómo se envía información de configuración adicional, en este ejemplo se muestra cómo configurar una etiqueta para enviar datos a una cuenta de Analytics con un parámetro send_page_view que pasa un valor false, y un parámetro groups que pasa un valor 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

`get`

Te permite obtener varios valores de gtag.js, incluidos valores definidos con el comando set.

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

Argumento	Tipo	Ejemplo	Descripción
<target>	`string`	G-XXXXXXXXXX	Objetivo del que se obtienen los valores.
<field_name>	FieldName	client_id	Nombre del campo que se va a obtener.
retrollamada	`Function`	`(field) => console.log(field)`	Función que se invocará con el campo solicitado, o con `undefined` si no se ha definido.

FieldName

El nombre del campo puede ser el nombre del campo personalizado que has definido con el comando gtag('set'), o bien uno de estos valores:

Nombre del campo	Objetivos admitidos
client_id	Google Analytics 4 Universal Analytics de Google Analytics
session_id	Google Analytics 4
gclid	Google Ads Floodlight

Ejemplos

Asignar un valor a una Promesa

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Enviar 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...
}

Obtener un valor que se ha definido

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 asociar parámetros de campaña para que distintas etiquetas de la misma página puedan acceder a ellos.

En el siguiente ejemplo vemos cómo se define un nombre de campaña y un ID para un evento de compra de Black Friday. Como se ha usado set, las demás etiquetas (como etiquetas de evento de GA4 o etiquetas de remarketing de Google Ads) pueden acceder a los datos.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

`event`

El comando event sirve para enviar datos de eventos.

gtag('event', '<event_name>', {<event_params>});

<event_name> puede ser uno de los siguientes tipos de evento:

Un evento recomendado. Se pueden aplicar parámetros recomendados a los eventos recomendados.
Un evento personalizado. Los eventos personalizados son eventos con nombres arbitrarios inventados a los que se aplican parámetros arbitrarios, es decir, personalizados. Si quieres ver ejemplos, consulta cómo se usan los eventos personalizados en Google Analytics.

<event_params> es uno o varios pares parámetro-valor. Si hay más de uno, deben separarse con comas.

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`

Utiliza el comando consent para configurar el consentimiento.

gtag('consent', {<consent_arg>}, {<consent_params>});

Consulta el artículo sobre consentimiento del Centro de Ayuda para obtener más información sobre el comportamiento de las etiquetas, que se define a través de estos parámetros.

El valor de <consent_arg> puede ser 'default' o 'update'. Al asignar el valor 'default' a los parámetros de consentimiento que se deben usar, se indica que son predeterminados. Al asignar el valor 'update', se indica que esos parámetros deben actualizarse una vez que un usuario indica su consentimiento.

Estos son los parámetros <consent_params> y valores que se pueden usar:

Nombre del campo	Valores permitidos	Descripción
`ad_storage`	`'granted'` \| `'denied'`	Habilita el almacenamiento (por ejemplo, el de las cookies en la Web o el de los identificadores de dispositivo en las aplicaciones) relacionado con la publicidad.
`ad_user_data`	`'granted'` \| `'denied'`	Define el consentimiento sobre el envío a Google de datos de usuario con fines publicitarios.
`ad_personalization`	`'granted'` \| `'denied'`	Define el consentimiento sobre la publicidad personalizada.
`analytics_storage`	`'granted'` \| `'denied'`	Habilita el almacenamiento (por ejemplo, el de las cookies en la Web o el de los identificadores de aplicaciones en las aplicaciones) relacionado con las analíticas (por ejemplo, la duración de las visitas).
`wait_for_update`	Cualquier número entero positivo	Establece un tiempo en milisegundos para esperar a una llamada de actualización del consentimiento.