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:
  • <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.

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 UA-XXXXXXXX-Y

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', 'UA-XXXXXXXX-Y', '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', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

Permite establecer valores que se mantienen en todas las llamadas de gtag() que se hagan después de ejecutar este comando en la página.

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

<parameter-value-pair> indica un nombre clave concreto y el valor fijo que debe tener en las llamadas siguientes de gtag(). Por ejemplo, el código que aparece a continuación asigna el valor 'US' a country y el valor 'USD' a currency en todos los eventos posteriores que ocurran en la página. 

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

Utilizar el comando set no es lo mismo que pasar valores directamente al comando event. Cuando se pasan valores concretos al comando event, solo se aplican en el momento de activar dicho evento. Al usar set, los valores persisten en la página que esté activa en ese momento y se pasan a todos los eventos posteriores. Para ver cómo funciona, compara los dos ejemplos siguientes:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

y

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

En el primer ejemplo, se pasará el evento login con un valor method que será 'Google', y el evento share se pasará sin ningún parámetro. En el segundo ejemplo, ambos eventos login y share se pasarán con un valor method que será 'Google'.

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:

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

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
ad_storage 'granted' | 'denied'
analytics_storage 'granted' | 'denied'
wait_for_update Cualquier número entero positivo

Á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 que se hayan configurado para tener un ámbito determinado no modifican los valores del mismo parámetro que se hayan configurado para tener otro ámbito. En el ejemplo siguiente, el comando config no modifica el valor global de currency que se había asignado previamente con el comando set. Después de ejecutar ambos comandos, el valor global de currency sigue siendo 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

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 global currency to Euros
gtag('set', { 'currency': 'EUR' });

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