Instalar con una etiqueta script

La etiqueta script funciona en cualquier sitio donde puedas añadir HTML. Cópiala desde Instalación y claves en tu proyecto y añádela a todas las páginas de tu web, antes de tus propios scripts. Viene ya con tu clave de navegador y una versión fija.

Pega el fragmento

La versión y la clave del ejemplo son marcadores; en Instalación y claves tienes los valores reales.

<script>
  (function(n){if(!n.TraceLog){var a=[],e={consent:{}},r=function(t,c){return function(){var o=arguments,i=function(u){(c?u[t][c]:u[t]).apply(u,o)};if(n.TraceLog!==e)return i(n.TraceLog);a.length<100&&a.push(i)}};e.init=r("init"),e.step=r("step"),e.conversion=r("conversion"),e.consent.grant=r("consent","grant"),e.consent.deny=r("consent","deny"),e.consent.state=function(){if(n.TraceLog!==e)return n.TraceLog.consent.state();try{if(n.localStorage.getItem("__tl.c")==="denied")return"denied"}catch(t){}return"unknown"},Object.defineProperty(n,"TraceLog",{configurable:!0,get:function(){return e},set:function(t){delete n.TraceLog,n.TraceLog=t;for(var c=a.splice(0),o=0;o<c.length;o++)try{c[o](t)}catch(i){}}})}})(window);
  TraceLog.init({ key: "tl_pk_xxxxxxxxxxxxxxxxxxxxxxxxxx", endpoint: "https://api.tracelog.io/v1/events" });
  // Captura solo con consentimiento: llama a TraceLog.consent.grant() cuando se haya concedido.
</script>
<script defer src="https://cdn.tracelog.io/v/2.4.0/tracelog.js"></script>

La versión queda fijada, así que tú decides cuándo actualizarla. Tu página nunca espera a que cargue TraceLog: lo que llame antes se guarda, en orden, y se le entrega en cuanto carga.

Concede el consentimiento

Mientras no haya una decisión de consentimiento, el código de captura no crea identificadores, no guarda nada en el navegador y no envía solicitudes. Una negativa se recuerda en una sola clave y nada más; la aceptación no se recuerda. La captura empieza al llamar a grant:

TraceLog.consent.grant();

Llámalo cuando el visitante acepte y otra vez en cada carga de página mientras su consentimiento siga vigente: conéctalo a la función que tu plataforma de consentimiento ejecuta siempre que hay consentimiento, no solo al clic en «aceptar». Si la normativa aplicable permite la captura propia sin aviso, llámalo en cada carga. En ningún caso TraceLog instala cookies de seguimiento ni cookies de ningún otro tipo; el identificador de sesión vive en el almacenamiento local del navegador.

Envía el recorrido declarado

El recorrido de conversión indica la conversión, el identificador estable que debe acompañarla y los pasos anteriores esperados. Envía cada paso cuando ocurra y la conversión al completarse:

TraceLog.step("view_item", undefined, {
  items: [{ id: product.sku, name: product.name, quantity: 1 }],
});

TraceLog.step("begin_checkout");

TraceLog.conversion("purchase", {
  identifier: order.number,
  value: order.total,
  currency: "EUR",
  items: order.lines.map((line) => ({
    id: line.sku,
    name: line.name,
    quantity: line.quantity,
    price: line.unitPrice,
  })),
});

Usa el identificador que ya tiene tu sistema: un número de pedido, de contacto o de reserva. Con él, TraceLog cuenta cada conversión una sola vez. Si falta, la verificación se bloquea.

Los artículos son opcionales: hasta 100, cada uno con un ID, un nombre, una categoría opcional, una cantidad y un precio unitario opcional. Si TraceLog no puede leer la lista, la descarta y la conversión sigue contando. Una reserva puede enviar scheduledFor, el día para el que es en formato AAAA-MM-DD, una suscripción o una donación, recurring, y cualquier conversión, first (más abajo). Todas las opciones están en la referencia del SDK.

Con Google Tag Manager

Si tu web carga sus etiquetas con Google Tag Manager, TraceLog puede ir en el contenedor en lugar de en tus páginas: de una forma o de la otra, nunca de las dos. Todas las etiquetas de aquí son de tipo HTML personalizado.

La etiqueta de TraceLog lo carga una vez por página y avisa a Tag Manager de cuándo está listo. Instalación y claves te da esta etiqueta con tu clave de navegador ya puesta; la clave de abajo es un marcador. Actívala con Inicialización: todas las páginas:

<script>
  (function () {
    var gtm = window.google_tag_manager[{{Container ID}}];
    var ready = function () {
      gtm.onHtmlSuccess({{HTML ID}});
    };
    if (window.TraceLog) return ready();
    var script = document.querySelector("script[data-tracelog]");
    if (!script) {
      script = document.createElement("script");
      script.src = "https://cdn.tracelog.io/v/2.4.0/tracelog.js";
      script.setAttribute("data-tracelog", "");
      script.addEventListener("load", function () {
        TraceLog.init({
          key: "tl_pk_xxxxxxxxxxxxxxxxxxxxxxxxxx",
          endpoint: "https://api.tracelog.io/v1/events",
        });
      });
      document.head.appendChild(script);
    }
    script.addEventListener("load", ready);
  })();
</script>

Concede el consentimiento desde una etiqueta que se active en cada página en la que el visitante haya dado su consentimiento —⁠con el activador que ofrece tu plataforma de consentimiento para eso, no con uno que solo salte al hacer clic⁠—⁠, o con Inicialización: todas las páginas si no hace falta banner. Si tu banner no ofrece ese activador ni envía ningún evento a la capa de datos, haz que el código que ejecuta al recibir el consentimiento envíe uno —⁠al aceptar y en cada carga de página mientras el consentimiento siga vigente⁠— y activa la etiqueta con ese evento. La configuración de consentimiento de Tag Manager no sirve de activador: una etiqueta que retiene no se activa después en esa página.

<script>
  TraceLog.consent.grant();
</script>

Después, añade una etiqueta por cada llamada del código de tu recorrido en Instalación y claves, con un activador de Evento personalizado sobre el evento que tu web envía a la capa de datos en ese momento: el mismo con el que ya se activa tu etiqueta de analítica. Los nombres de tu recorrido son tuyos y no tienen que coincidir con los de la capa de datos.

<script>
  TraceLog.step("add_to_cart");
</script>

En la etiqueta del consentimiento y en cada una de estas, abre Configuración avanzada, luego Secuenciación de etiquetas, y elige la etiqueta de TraceLog en Active una etiqueta antes de que se active esta etiqueta. Así ninguna llamada se ejecuta antes de que TraceLog esté cargado.

La conversión toma su identificador, su valor, su moneda y sus artículos de cuatro variables de tipo Capa de datos: las que ya lee tu etiqueta de compra. En una capa de datos con el formato de Google Analytics 4 —⁠cuyos eventos de comercio electrónico, view_item, add_to_cart, begin_checkout y purchase, son los nombres de la plantilla de compra⁠— son ecommerce.transaction_id, ecommerce.value, ecommerce.currency y ecommerce.items, llamadas aquí Order number, Order value, Order currency y Order items. El identificador va como texto, y String se asegura de ello:

<script>
  TraceLog.conversion("purchase", {
    identifier: String({{Order number}}),
    value: {{Order value}},
    currency: {{Order currency}},
    items: ({{Order items}} || []).map(function (item) {
      return {
        id: String(item.item_id || item.item_name),
        name: String(item.item_name || item.item_id),
        category: item.item_category,
        quantity: item.quantity || 1,
        price: item.price,
      };
    }),
  });
</script>

La capa de datos nombra a su manera los campos de cada artículo, así que la etiqueta los adapta.

Envía también los artículos en los pasos que los tienen. Las sesiones que vieron un artículo son aquellas en las que un paso lo llevaba: con artículos solo en la compra, sabes qué se vendió, pero no qué se vio. En una capa de datos de Google Analytics 4, view_item y add_to_cart traen su lista en el mismo ecommerce.items, así que la etiqueta de cada uno de esos pasos lee la misma variable Order items:

<script>
  TraceLog.step("add_to_cart", undefined, {
    items: ({{Order items}} || []).map(function (item) {
      return {
        id: String(item.item_id || item.item_name),
        name: String(item.item_name || item.item_id),
        category: item.item_category,
        quantity: item.quantity || 1,
        price: item.price,
      };
    }),
  });
</script>

Indica si un pedido es el primero del cliente

Una conversión puede indicar si es la primera de su tipo que hace esa persona: first: true si tus registros no tienen ninguna anterior de la misma persona, false si la tienen. A partir del plan Pro, Analítica muestra entonces la Proporción de primeras: de los pedidos que lo indicaron, qué parte fue el primero del cliente, también por canal o por campaña. Se calcula para compras, reservas y donaciones. El plugin de WooCommerce y el módulo de PrestaShop lo envían solos a partir de la versión 0.5.0; la app de TraceLog para Shopify no lo envía.

Tu web lo decide con sus propios registros, como los pedidos ya pagados del cliente, y solo envía true o false: a TraceLog no llega ningún identificador ni dato de esa persona. Si no lo sabes, como pasa en algunas compras sin cuenta, no lo envíes.

TraceLog.conversion("purchase", {
  identifier: order.number,
  value: order.total,
  currency: "EUR",
  first: customer.earlierPaidOrders === 0,
});

Solo cuentan true y false: el texto "true", un 1 o un valor vacío se descartan sin dar error, y la conversión sigue contando.

En Google Tag Manager, léelo con una variable más de tipo Capa de datos (aquí, First order) a partir del valor que tu web envía con purchase. Si tu web ya envía new_customer para Google Ads, usa esa: significa lo mismo, siempre que tu web lo calcule con todos sus pedidos anteriores. Si tu capa de datos no tiene ninguno de los dos, quien desarrolla tu web tiene que añadirlo al evento de compra. Después, añade a la etiqueta de compra, detrás de currency, esta línea, que además convierte el texto "true" o "false" en el true o false que lee TraceLog:

    first: {{First order}} === true || {{First order}} === "true" ? true
      : {{First order}} === false || {{First order}} === "false" ? false
      : undefined,

Varios dominios y staging

La clave de navegador solo se acepta desde las direcciones de tu web. Si el mismo proyecto funciona en más de un dominio, añade cada uno en Ajustes → Instalación y claves → Las direcciones de tu web, completo, como https://shop.example. Los eventos de cualquier otra dirección se rechazan.

Una copia de staging de tu web puede enviar al mismo proyecto. Añádela en dos sitios: su dirección completa en Ajustes → Instalación y claves → Las direcciones de tu web, como https://staging.shop.example, para que la clave se acepte desde ella, y su hostname en Ajustes → Tráfico de staging e interno → Hostnames de staging, como staging.shop.example, para que sus eventos no se tomen por reales. Las dos listas comparan la dirección exacta y no admiten comodines: cada entorno se añade por separado. Sus eventos son tráfico de staging: no cuentan para las cifras ni para el límite de sesiones, y Recorrido muestra, bajo cada paso, cuándo llegó su último evento de staging.

Verifica la instalación

Con Google Tag Manager, publica antes el contenedor: una etiqueta de un espacio de trabajo sin publicar no llega a ningún visitante.

Abre Instalación y claves en el proyecto y empieza la comprobación desde Abrir mi sitio. La pestaña que abre ese botón es la que TraceLog marca como tráfico de verificación. Acepta primero el banner de consentimiento en ella: desde ese momento, la pestaña sigue en la comprobación al pasar de una página a otra y al volver de un pago hecho fuera de tu web. Una conversión que completes en cualquier otra pestaña cuenta como real y entra en tus cifras.

Recorre el camino hasta la conversión en esa pestaña y deja Instalación y claves abierta al lado. La lista de Tu recorrido de conversión avanza a medida que TraceLog recibe cada evento declarado. El tráfico de verificación queda marcado, no cuenta para ningún límite y sigue visible después en la página Recorrido.

Si cierras esa pestaña, vuelve a abrir tu sitio desde Abrir mi sitio y repite el recorrido.

Si la lista no avanza

Si no llega ningún evento, las tres primeras filas se ven igual. En la pestaña que se abre al pulsar Abrir mi sitio, el código de captura informa de si está cargado, de su estado de consentimiento y de si su configuración es válida. Así Instalación y claves puede distinguir cada caso.