Referencia de la API gtag.js

La API gtag.js consta de una sola función, gtag(), que tiene la siguiente sintaxis.

gtag(<command>, <command parameters>);
  • <command> es uno de los tres comandos gtag: config, set y event.
  • <command parameters> son los parámetros que se usarán con gtag(). Los parámetros aplicables varían en función del comando que se use. Si quieres 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 fragmentos.

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 de valor de parámetro.

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 asigna el valor false, y un parámetro groups que asigna el valor 'agency'.

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

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 country a'US' y el valor currency a 'USD' para 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 asignar valores directamente al comando event. Cuando se asignan 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 actual y se asignan 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 asignará el valor 'Google' al method del evento login, pero no se definirá ningún parámetro para el evento share. En el segundo ejemplo, se asignará el valor 'Google' al method tanto del evento login como del evento share.

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 de valor de parámetro. 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'
});

Alcance de los parámetros

Los valores de parámetros 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 un alcance no modifican los valores que se hayan configurado para el mismo parámetro en 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 en diferentes alcances, solo se utilizará un valor cuando se procesen eventos. Los valores de parámetros que se hayan configurado para el alcance event tendrán prioridad sobre los del alcance config, y los parámetros config tendrán prioridad sobre los que se hayan configurado para un alcance global con 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>' });