Cómo compilar una etiqueta de servidor

En Introducción al etiquetado del servidor 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 el resto del contenedor los use. En este artículo, se describe cómo procesar esos datos en etiquetas del servidor.

En un contenedor de servidor, las etiquetas reciben los 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 a donde quieras. Siempre que el destino acepte solicitudes HTTP, también puede aceptar datos de un contenedor de servidor.

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

• Google Analytics
• Solicitud HTTP

Si deseas enviar datos a un lugar que no sea Google Analytics o necesitas más funciones de 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 escribir tus propias etiquetas. En este instructivo, aprenderás los aspectos básicos para escribir tus propias etiquetas para un contenedor de servidor.

Objetivos

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

Requisitos previos

• Un contenedor de servidor implementado
• Conocimientos de Tag Manager, contenedores de servidor, y sus conceptos básicos, como clientes, etiquetas, activadores, y variables
• Conocimientos básicos para escribir plantillas para etiquetas y variables

La 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 ingiere datos a través de solicitudes HTTP GET a https://example.com/baz_analytics. Tiene los siguientes parámetros:

Configuración de la etiqueta

Lo primero que debes hacer es crear la plantilla de etiqueta. Ve a la sección Plantillas de tu contenedor y haz clic en Nueva 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 para agregar las diferentes opciones de configuración de tu etiqueta. La siguiente pregunta obvia es: ¿qué opciones necesitas? Hay tres formas en las que puedes elegir compilar la etiqueta:

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

Tener campos para cada parámetro es muy flexible y le da al usuario el control total sobre la configuración de su etiqueta. Sin embargo, en la práctica, esto suele generar mucho trabajo duplicado. En particular, elementos como el parámetro l de Baz Analytics, que contiene la URL de la página, son inequívocos y universales. Ingresar el mismo dato inmutable cada vez que se configura la etiqueta es algo que es mejor dejarle a la computadora.

Tal vez la respuesta sea tener una etiqueta que solo tome datos de un evento. Esta es la etiqueta más simple posible para que un usuario la configure, ya que no tiene que hacer nada. 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, incluso si lo necesitan. Por ejemplo, tal vez llamen a un evento purchase en su sitio web y en Google Analytics, pero Baz Analytics lo llama buy. O tal vez las suposiciones que hace la etiqueta sobre la estructura de los datos de eventos entrantes no coincidan con la realidad. En cualquier caso, el usuario está atascado.

Al igual que con muchas cosas, la respuesta se encuentra en algún punto entre los dos extremos. Tiene sentido tomar algunos datos siempre del evento. El usuario debe configurar otros datos. ¿Cómo decides cuál es cuál? Para responder esa pregunta, deberemos analizar más de cerca los datos que ingresan al contenedor.

¿De dónde provienen los datos?

Los datos que ingresan a un contenedor de servidor desde la etiqueta de Google Analytics 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, un comando como este:

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

Dará como resultado los siguientes parámetros en el contenedor de servidor:

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

Es bastante simple, pero, desde la perspectiva de la etiqueta, es muy difícil trabajar con ella. Debido a que el usuario ingresa estos datos, pueden 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 para que lo haga. Con la importante excepción 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.

Afortunadamente, 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 recopila automáticamente en el navegador. Eso 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 pueden estar disponibles los datos de las cookies del navegador a través de la API de getCookieValue.

En conjunto, estos constituyen los datos recopilados automáticamente que mencionamos anteriormente. En general, consisten en datos universales y semánticamente inequívocos. Cuando ingresa una solicitud desde una etiqueta de Google Analytics en el 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 qué datos se deben especificar en la etiqueta. Es seguro leer directamente los datos recopilados automáticamente del evento. El usuario debe configurar todo lo demás.

Teniendo esto en cuenta, vuelve a consultar los parámetros de la etiqueta de Baz Analytics.

• ID de medición, id: Debido a que no se recopila automáticamente, es un ejemplo claro de un valor que el usuario debe ingresar 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 page_location parámetro, que la etiqueta de navegador de Google Analytics recopila automáticamente en cada evento. Por lo tanto, no debes exigir que el usuario ingrese un valor de forma manual.
• ID de usuario, u: En la etiqueta de servidor de Baz Analytics, el parámetro u no está especificado por el usuario ni recopilado 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 a continuación, es la etiqueta de servidor de Baz Analytics la que usa la setCookie API para establecer 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 u parámetro se debe recopilar automáticamente.

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

Implementación de etiquetas

Ahora que la configuración de la etiqueta está lista, puedes pasar a implementar su comportamiento en JavaScript en un entorno de pruebas.

La etiqueta debe hacer cuatro cosas:

1. Obtener el nombre del evento de la configuración de la etiqueta
2. Obtener la URL de la página de la propiedad page_location del evento
3. Calcular un ID de usuario (la etiqueta buscará el ID de usuario en una cookie llamada _bauid) (si esa cookie no está presente, la etiqueta calculará un valor nuevo y lo almacenará para solicitudes posteriores)
4. Crear una URL y realizar una solicitud al servidor de recopilación de Baz Analytics

También vale la pena tomarse un momento para pensar en cómo encaja la etiqueta en el contenedor en su totalidad. Los diferentes componentes del contenedor desempeñan diferentes roles, por lo que también hay cosas que la etiqueta no hace o no debería hacer. Tu etiqueta:

• No debe examinar el evento para determinar si debe ejecutarse. Para eso, se usa un activador.
• No debe ejecutar el contenedor con la API de runContainer. Esa es la tarea del cliente.
• Con la importante excepción de las cookies, no debe intentar interactuar directamente con la solicitud o la respuesta. Esa también es la tarea del cliente.

Escribir una plantilla de etiqueta que haga cualquiera de estas cosas generaría un comportamiento confuso para los usuarios de tu etiqueta. Por ejemplo, una etiqueta que envía una respuesta a la solicitud entrante impediría que el cliente haga lo mismo. Eso rompería las expectativas de los usuarios sobre cómo se supone que debe comportarse el contenedor.

Teniendo todo eso en cuenta, a continuación, se muestra una implementación anotada de la etiqueta en JS en un entorno 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 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;
}

Con eso, se implementa la etiqueta. Antes de poder usar la etiqueta, deberás establecer sus permisos de API correctamente. Ve a la pestaña Permisos del Editor de plantillas y especifica los siguientes permisos:

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

También debes escribir pruebas para tu etiqueta. Para obtener más información sobre las pruebas de plantillas, lee 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 Ejecutar código al menos una vez. Eso evitará que muchos errores simples lleguen a tu servidor.

Envía tu etiqueta a la Galería de plantillas de la comunidad

Como ya realizaste todo el trabajo para crear, probar e implementar una etiqueta nueva, no hay motivos para quedártela. Si crees que tu nueva etiqueta sería útil para otras personas, considera enviar la a la Galería de plantillas de la comunidad.

Conclusión

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

• Qué APIs usar para leer datos de eventos, enviar solicitudes HTTP y establecer 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é es importante esa distinción
• El rol 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.