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(), que contiene la siguiente sintaxis:

gtag(<command>, <command parameters>);
  • <command> es uno de los siguientes comandos:
  • <command parameters> son los parámetros que puedes pasar a gtag(). Comando los parámetros varían según el comando; consulta la referencia de comandos, a continuación.

Puedes invocar comandos gtag() en cualquier parte de la página, siempre y cuando tus comandos aparecen debajo del fragmento de la etiqueta de Google. Para aprender a agregar el fragmento a una 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, es decir, todos los eventos enviados a un <TARGET_ID> específica , o bien de forma global a todos los eventos. Esto se logra usando los comandos event, config y set

Los valores del parámetro 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 realiza No modifiques el valor global de campaign_id que se asignó anteriormente con el set. kubectl. Después de que se ejecutan ambos comandos, el valor global de campaign_id se sigue '1234'.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Orden de precedencia de los parámetros

Si se asignan valores diferentes al mismo parámetro en distintos alcances, solo se usa un solo valor cuando se procesan eventos. Valores del parámetro establecidos en event tendrá prioridad sobre los parámetros con alcance a config y config. Estos parámetros tienen prioridad sobre los que tienen alcance global cuando usan 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. Este es normalmente una configuración específica de un producto, pero solo debes configura esta opción una vez si utilizas Google Ads y Google Analytics.

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

<TARGET_ID> es un identificador que identifica de forma única el objetivo de los hits. como una propiedad de Google Analytics o una cuenta de Google Ads. <additional_config_info> es 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 etiqueta de la etiqueta de Google.

Para demostrar cómo enviar información de configuración adicional, aquí hay un ejemplo que configura una etiqueta para enviar datos a una cuenta de Analytics con una Parámetro send_page_view que pasa un valor de false y un 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)
Argumento Tipo Ejemplo Descripción
&lt;target&gt; string G-XXXXXXXXXX

El objetivo del que se recuperarán los valores.

&lt;field_name&gt; FieldName client_id El nombre del campo que se debe obtener.
callback Function (field) => console.log(field)

Una función que se invocará con el campo solicitado Es undefined si no está configurada.

FieldName

El nombre del campo puede ser el de un campo personalizado que configures con el parámetro gtag('set') o uno de los siguientes valores:

Nombre del campo Destinos compatibles
client_id
  • Google Analytics 4
  • Universal Analytics de Google Analytics
session_id
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Ejemplos

Convierte el valor en una promesa

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

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

Enviar 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...
}

Obtén un valor que establezcas

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 los 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 campaign. parámetros para que se pueda acceder a ellos a través de varias etiquetas en la misma página.

El siguiente ejemplo ilustra cómo configurar un nombre y un ID de campaña para un Black Friday de un evento de Shopping. Como usaste set, todas las demás etiquetas, Las etiquetas del 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 del evento.

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

<event_name> es una de las siguientes opciones:

<event_params> es uno o más pares parámetro-valor. Cada par 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'
});

Usa el comando consent para configurar el consentimiento.

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

Consulte la sección consentimiento en el Centro de ayuda para obtener más información sobre el comportamiento que parámetros configurados.

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

Se admiten los siguientes <consent_params>:

Nombre del campo Valores permitidos Descripción
ad_storage 'granted' | 'denied' Habilita el almacenamiento, como cookies (Web) o identificadores de dispositivos (aplicaciones), en relación con la publicidad.
ad_user_data 'granted' | 'denied' Establece el consentimiento para enviar los datos del usuario a Google con fines publicitarios.
ad_personalization 'granted' | 'denied' Establece el consentimiento para la publicidad personalizada.
analytics_storage 'granted' | 'denied' Habilita el almacenamiento, como cookies (Web) o identificadores de aplicaciones (aplicaciones), relacionado con las estadísticas, p.ej., la duración de la visita.
wait_for_update cualquier número entero positivo Establece el tiempo en milisegundos de espera de una llamada de actualización del consentimiento.