Referencia de la API de la etiqueta de Google

La API de la etiqueta de Google (gtag.js) consta de una sola función, gtag(), con 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 pasar a gtag(). Los parámetros de los comandos varían según el comando. Consulta la referencia de comandos a continuación.

Puedes invocar comandos de gtag() en cualquier lugar de tu página, siempre y cuando aparezcan debajo del fragmento de la etiqueta de Google. Para obtener información sobre cómo agregar el fragmento a una página, consulta la guía de instalación.

Alcance del parámetro

Puedes definir el alcance de los valores de los parámetros para eventos individuales, todos los eventos enviados a un <TARGET_ID> específico o de forma global para todos los eventos. Esto se logra con los comandos event, config y set.

Los valores de los parámetros establecidos en un alcance no modifican los valores establecidos para el mismo parámetro en un alcance diferente. En el siguiente ejemplo, el comando config no modifica el valor global de campaign_id que se asignó anteriormente 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 valores diferentes al mismo parámetro en diferentes alcances, solo se usará un valor cuando se procesen los eventos. Los valores de los parámetros que se definen para event tendrán prioridad sobre los parámetros definidos para config, y los parámetros de config tendrán prioridad sobre los parámetros que se definen de forma global con 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

Te permite agregar información de configuración adicional a los destinos. Por lo general, se trata de un parámetro de configuración específico del producto, pero solo debes configurarlo una vez si usas Google Ads y Google Analytics.

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

<TARGET_ID> es un identificador que identifica de forma única el destino de los hits, como una propiedad de Google Analytics o una cuenta de Google Ads. <additional_config_info> son uno o más pares parámetro-valor.

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

gtag('config', 'TAG_ID');

donde "TAG_ID" es el ID de la etiqueta de la etiqueta de Google.

Para demostrar cómo enviar información de configuración adicional, aquí tienes un ejemplo que configura una etiqueta para enviar datos a una cuenta de Analytics con un parámetro send_page_view que pasa un valor de false y un parámetro groups que pasa un valor de 'agency'.

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

get

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

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

FieldName

El nombre del campo puede ser el de un campo personalizado que establezcas con el comando gtag('set') o uno de los siguientes valores:

Ejemplos

Cómo obtener un valor en una promesa

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

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

Envía 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...
}

Cómo obtener un valor que estableciste

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

En el siguiente ejemplo, se ilustra cómo establecer un nombre y un ID de campaña para un evento de compras del Black Friday. Como usaste set, todas las demás etiquetas, por ejemplo, las etiquetas de evento de GA4 o las etiquetas de remarketing de Google Ads, pueden acceder a estos datos.

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

event

Usa el comando event para enviar datos de eventos.

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

<event_name> puede ser uno de los siguientes:

• Un evento recomendado Cada evento recomendado puede tomar parámetros recomendados.
• Es un evento personalizado. Un evento personalizado es un nombre de evento arbitrario que inventas, con parámetros arbitrarios. Para obtener más información, consulta Cómo configurar eventos.

<event_params> son uno o más pares parámetro-valor. Cada par está separado por una coma.

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

Usa el comando consent para configurar el consentimiento.

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

Consulta Consentimiento en el Centro de ayuda para obtener más información sobre el comportamiento que configuran estos parámetros.

<consent_arg> es uno de 'default' o 'update'. 'default' se usa para establecer los parámetros de consentimiento predeterminados que se deben usar, y 'update' se usa para actualizar estos parámetros una vez que el usuario indica su consentimiento.

Se admiten los siguientes <consent_params>: