Gracias por consultar la versión preliminar de la nueva documentación sobre plataformas de etiquetas de Google. Este sitio web está en versión beta pública. (Comentarios)

Referencia de la API de la etiqueta global de sitio web

La API de la etiqueta global de sitio web (gtag.js) consta de una sola 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 se pasarán con 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 global. Si quieres obtener información sobre cómo añadir el fragmento global a una página, consulta la guía de instalación.

config

Permite añadir información de configuración a los objetivos. Normalmente se usa para añadir la configuración específica de un producto, como Google Ads o 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', 'AW-CONVERSION_ID');

El comando config también se puede utilizar con cuentas de Google Analytics:

gtag('config', 'GA_MEASUREMENT_ID');

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', 'GA_MEASUREMENT_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 más 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 'allowed' | 'denied'
analytics_storage 'allowed' | 'denied'
wait_for_update Cualquier número entero positivo

Alcance de los parámetros

Los valores de los parámetros pueden tener diferentes alcances. Se pueden aplicar a un evento en particular, a todos los eventos enviados a un <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 alcance determinado no modifican los valores del mismo parámetro que se hayan configurado para tener otro alcance. 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 alcances, se utilizará un solo valor cuando se procesen eventos. Los valores de parámetros que se hayan configurado con un alcance event tendrán prioridad sobre que tienen un alcance config, y los parámetros config tendrán prioridad sobre los que se hayan configurado con un alcance 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>' });