Cómo compilar una etiqueta de servidor

En Introducción al etiquetado del servidor, obtuviste una descripción general del etiquetado del servidor en Tag Manager. Aprendiste qué son los clientes y qué hacen: los clientes reciben datos de eventos de los dispositivos de tus usuarios y los adaptan para que los use el resto del contenedor. En este artículo, se describe cómo procesar esos datos en etiquetas del servidor.

En un contenedor de servidor, las etiquetas reciben datos de eventos entrantes de tus clientes, los transforman y los envían de vuelta para su recopilación y análisis. Las etiquetas pueden enviar los datos donde quieras. Siempre que el destino acepte solicitudes HTTP, también podrá aceptar datos de un contenedor de servidor.

Los contenedores de servidor tienen tres etiquetas integradas que están listas para usarse sin una configuración personalizada:

  • Google Analytics 4
  • Google Analytics: Universal Analytics
  • Solicitud HTTP

Si quieres enviar datos a un lugar que no sea Google Analytics o necesitas más funciones que las que proporciona la etiqueta de solicitud HTTP, deberás usar una etiqueta diferente. Puedes encontrar etiquetas adicionales en la Galería de plantillas de la comunidad o puedes escribir una propia. En este instructivo, aprenderás los conceptos básicos de escribir tus propias etiquetas para un contenedor de servidor.

Objetivos

  • Obtén información sobre qué APIs usar para leer datos de eventos, enviar solicitudes HTTP y configurar cookies en el navegador.
  • Conoce las prácticas recomendadas para diseñar las opciones de configuración de tu etiqueta.
  • Descubre la diferencia entre los datos especificados por el usuario y los datos recopilados automáticamente, y por qué esa distinción es importante.
  • Conoce el rol de una etiqueta en un contenedor de servidor. Comprende lo que una etiqueta debe hacer y lo que no.
  • Descubre cuándo considerar enviar una plantilla de etiqueta a la Galería de plantillas de la comunidad.

Requisitos previos

Etiqueta de Baz Analytics

En este instructivo, crearás una etiqueta que envíe datos de medición a un servicio llamado Baz Analytics.

Baz Analytics es un servicio de estadísticas hipotético y simple que transfiere datos a través de solicitudes HTTP GET a https://example.com/baz_analytics. Tiene los siguientes parámetros:

Parámetro Ejemplo Descripción
id BA-1234 El ID de tu cuenta de Baz Analytics.
en click Nombre del evento
l https://www.google.com/search?q=sgtm URL de la página donde ocurrió el evento.
u 2384294892 El ID del usuario que realiza la acción. Se usa para vincular varias acciones a un solo usuario.

Configuración de etiquetas

Lo primero que hay que hacer es crear la plantilla de etiqueta. Ve a la sección Plantillas del contenedor y haz clic en Nuevo en la sección Plantillas de etiquetas. Agrega un nombre y una descripción a tu etiqueta.

A continuación, ve a la sección Campos del editor de plantillas y agrega las diferentes opciones de configuración para tu etiqueta. La siguiente pregunta obvia es: ¿qué opciones necesitas? Existen tres formas de crear la etiqueta:

  1. Configuración total: Agrega un campo de configuración para cada parámetro. Exige que el usuario configure todo de forma explícita.
  2. Sin configuración: No tiene ninguna opción para configurar la etiqueta. Todos los datos se toman directamente del evento.
  3. Algunas configuraciones: Tienen campos para algunos parámetros y no para otros.

Tener campos para cada parámetro es muy flexible y le brinda al usuario control total sobre la configuración de la etiqueta. Sin embargo, en la práctica, esto suele dar como resultado mucho trabajo duplicado. En particular, algunos elementos, como el parámetro l de Baz Analytics, que contiene la URL de la página, no son ambiguos y universales. Ingresar los mismos datos inalterables cada vez que se configura la etiqueta es algo que mejor se deja en manos de la computadora.

Tal vez la respuesta sea tener una etiqueta que solo tome datos de un evento. Esta es la etiqueta más simple que un usuario puede configurar, ya que no tiene nada que hacer. Por otro lado, también es la opción más restrictiva y frágil. Los usuarios no pueden cambiar el comportamiento de la etiqueta aunque sea necesario. Por ejemplo, puede llamar a un evento purchase en su sitio web y en Google Analytics, pero Baz Analytics lo llama buy. También es posible que las suposiciones que haga la etiqueta sobre la estructura de los datos de eventos entrantes no coincidan con la realidad. En cualquier caso, el usuario no avanza.

Como con muchas otras cosas, la respuesta está en un punto medio entre los dos extremos. Tiene sentido tomar siempre del evento algunos datos. El usuario debe configurar otros datos. ¿Cómo decides cuál es cada una? Para responder a esa pregunta, tendremos que examinar con mayor detalle los datos que entran en el contenedor.

¿De dónde provienen los datos?

Los datos que llegan a un contenedor de servidor desde la etiqueta de Google Analytics 4 se pueden dividir en dos categorías: datos especificados por el usuario y datos recopilados automáticamente.

Los datos especificados por el usuario son todo lo que un usuario coloca en un comando event de gtag.js. Por ejemplo, puedes usar un comando como el siguiente:

gtag('event', 'search', {
  search_term: 'beets',
});

El contenedor del servidor tendrá los siguientes parámetros:

{
  event_name: 'search',
  search_term: 'beets',
}

Eso es bastante simple, pero desde la perspectiva de la etiqueta es muy difícil trabajar con él. Como el usuario ingresa estos datos, puede ser cualquier cosa. Tal vez, como se indicó anteriormente, el usuario solo envíe eventos y parámetros recomendados, pero no hay ningún requisito que lo haga. Con la excepción importante de la ubicación (pero no el valor) del parámetro event_name, no hay garantías sobre la forma o la estructura de los datos del usuario.

Por suerte, los datos ingresados por el usuario no son lo único que recibirá el contenedor. También obtendrá una gran cantidad de datos que la etiqueta de Google Analytics 4 recopila automáticamente en el navegador. Esto incluye lo siguiente:

  • ip_override
  • language
  • page_location
  • page_referrer
  • page_title
  • screen_resolution
  • user_agent

Además, si la solicitud del servidor proviene de un navegador web, también puede haber datos de cookies del navegador disponibles a través de la API de getCookieValue.

En conjunto, estos forman los datos recopilados automáticamente que mencionamos más arriba. En general, consta de datos que son universales y no ambiguos desde el punto de vista semántico. Cuando llega una solicitud desde una etiqueta de GA4 al navegador, estos datos siempre estarán disponibles y siempre tendrán el mismo formato. Para obtener más detalles sobre estos parámetros, consulta la referencia de eventos.

Esta clasificación nos brinda una herramienta útil para decidir qué datos debe configurar el usuario y cuáles se deben especificar en la etiqueta. Los datos recopilados automáticamente se pueden leer de forma segura directamente desde el evento. El usuario debe configurar todo lo demás.

Con esto en mente, vuelve a revisar los parámetros de la etiqueta de Baz Analytics.

  • ID de medición, id: Como no se recopila automáticamente, es un ejemplo claro de un valor que debe ingresar el usuario cuando configura la etiqueta.
  • Nombre del evento, en: Como se mencionó anteriormente, el nombre del evento siempre se puede tomar directamente del parámetro event_name. Sin embargo, debido a que su valor está definido por el usuario, es una buena idea ofrecer la capacidad de anular el nombre si es necesario.
  • URL de la página, l: Este valor se puede tomar del parámetro page_location, que la etiqueta del navegador GA4 de Google Analytics recopila automáticamente en cada evento. Por lo tanto, no debes pedirle al usuario que ingrese un valor de forma manual.
  • ID de usuario, u: En la etiqueta del servidor de Baz Analytics, el parámetro u no se especifica por el usuario ni se recopila automáticamente por la etiqueta en la página. En cambio, se almacena en una cookie del navegador para que se pueda identificar a los usuarios en varias visitas al sitio web. Como verás en la implementación más abajo, es la etiqueta del servidor de Baz Analytics la que usa la API de setCookie para configurar la cookie. Esto significa que la etiqueta de Baz Analytics es lo único que sabe dónde y cómo se almacena la cookie. Al igual que l, el parámetro u debe recopilarse automáticamente.

Una vez que termines de configurar la etiqueta, debería verse de la siguiente manera:

Instantánea de la configuración de la etiqueta de Baz Analytics.

Implementación de etiquetas

Ahora que la configuración de la etiqueta está cuadrada, puedes continuar con la implementación de su comportamiento en JavaScript de zona de pruebas.

La etiqueta debe cumplir con los siguientes cuatro pasos:

  1. Obtén el nombre del evento de la configuración de la etiqueta.
  2. Obtén la URL de la página de la propiedad page_location del evento.
  3. Calcula un ID de usuario. La etiqueta buscará el ID del usuario en una cookie denominada _bauid. Si esa cookie no está presente, la etiqueta calculará un valor nuevo y lo almacenará para solicitudes posteriores.
  4. Crea una URL y realiza una solicitud al servidor de colecciones de Baz Analytics.

También vale la pena tomarse un momento para pensar en cómo la etiqueta encaja en el contenedor como un todo. Los diferentes componentes del contenedor desempeñan diferentes funciones, por lo que también hay cosas que la etiqueta no debe o no debe cumplir. Tu etiqueta:

  • No debería examinar el evento para averiguar si debe ejecutarse. Para eso son los activadores.
  • No se debe ejecutar el contenedor con la API de runContainer. Ese es el trabajo del cliente.
  • Con la excepción importante de las cookies, no debería intentar interactuar directamente con la solicitud o respuesta. Eso también es trabajo del cliente.

Si escribes una plantilla de etiqueta que realice cualquiera de estas acciones, generaría un comportamiento confuso para los usuarios de tu etiqueta. Por ejemplo, una etiqueta que envía una respuesta a la solicitud entrante evitaría que el cliente haga lo mismo. Eso rompería las expectativas de los usuarios sobre cómo se supone que se comporta el contenedor.

Con todo esto en mente, a continuación se incluye una implementación anotada de la etiqueta en el JS de zona de pruebas.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

De esta forma, se implementa la etiqueta. Para poder usar la etiqueta, deberás configurar los permisos de API de forma correcta. Ve a la pestaña Permisos del Editor de plantillas y especifica los siguientes permisos:

  • Lee valores de cookies: _bauid
  • Lee datos de eventos: event_name y page_location
  • Envía solicitudes HTTP: https://www.example.com/*
  • Configura una cookie: _bauid

También debes escribir pruebas para tu etiqueta. Si quieres obtener más información sobre las pruebas de plantillas, consulta la sección de pruebas de la guía para desarrolladores de plantillas.

Por último, no olvides intentar ejecutar tu etiqueta con el botón Run Code al menos una vez. Eso evitará que se cometan muchos errores simples en tu servidor.

Dado que ya realizaste todo el trabajo para crear, probar e implementar una etiqueta nueva, no hay motivos para que la guardes. Si crees que la etiqueta nueva sería útil para otras personas, considera enviarla a la Galería de plantillas de la comunidad.

Conclusión

En este instructivo, aprendiste los conceptos básicos de escribir una etiqueta para un contenedor de servidor. Aprendiste lo siguiente:

  • Qué APIs usar para leer datos de eventos, enviar solicitudes HTTP y configurar cookies en el navegador
  • Prácticas recomendadas para diseñar las opciones de configuración de una etiqueta.
  • La diferencia entre los datos especificados por el usuario y los datos recopilados automáticamente, y por qué esa distinción es importante.
  • La función de una etiqueta en el contenedor; lo que debe y no debe hacer.
  • Cuándo y cómo enviar plantillas de etiquetas a la Galería de plantillas de la comunidad