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 o 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 datos concretos sobre algún producto, como información de seguimiento de 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 AdWords. <additional_config_info> se corresponde a 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-TRACKING_ID');

Para saber cómo enviar 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 indica el valor false, y un parámetro groups que indica el valor 'agency'.

gtag('config', 'GA-TRACKING_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 'US' a country y el valor 'USD' a currency para todos los eventos posteriores que ocurran en la página.

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

Usar el comando set no es lo mismo que indicar valores concretos al comando event. Cuando se indican valores concretos para el 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 aplican 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 parámetro method del evento login, pero no se establecerá ningún parámetro para el evento share. En el segundo, se asignarán tanto login como share con el valor de 'Google' en method.

event

El comando event sirve para enviar datos de eventos.

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

El valor del parámetro <event_name> debe ser de uno de los siguientes:

<event_params> se corresponde a 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'
});

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 ámbito no modifican los valores que se hayan configurado para el mismo parámetro en otro ámbito. En el siguiente ejemplo, 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 ámbitos, 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 parámetros configurados para el alcance config, y los parámetros config tendrán prioridad sobre los parámetros 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>' });