Cómo gestionar scripts de seguimiento en sitios de Webflow con un cargador de Webflow Cloud

Las etiquetas de seguimiento pegadas en el código head de cada sitio pueden acabar desincronizadas. Cada cambio de proveedor se convierte en una ronda de ediciones en todos los proyectos y, al poco tiempo, nadie sabe qué versión de un snippet o de la comprobación de consentimiento tiene cada sitio.

Esta solución sustituye esos snippets por una sola línea de código head que carga un script desde una pequeña aplicación de Next.js en Webflow Cloud. El mismo repositorio se despliega en todos los sitios, y las variables de entorno de cada uno determinan qué scripts de proveedor se cargan y si requieren una cookie de consentimiento previa, verificada en el servidor antes de que cualquier URL de proveedor llegue al navegador.

¿Qué necesitas para gestionar scripts de seguimiento en Webflow?

Necesitas seis cosas para esta implementación:

• Sitios de Webflow: Un sitio de Webflow por cada propiedad que quieras cubrir con el repositorio compartido y su propia configuración.
• Next.js 15: La página de "bring-your-own-app" indica Next.js 15 o superior, la documentación de Webflow requiere Node.js 22 o posterior, y esta implementación utiliza Next.js 15.
• npm: Webflow Cloud solo admite npm, así que úsalo para instalar dependencias y confirmar su archivo de bloqueo (lockfile).
• Repositorio Git: Un único repositorio contiene la aplicación de carga independiente del sitio y se despliega sin cambios en todos los sitios cubiertos.
• Lista de scripts por sitio: Las URLs de los scripts que carga cada sitio y si ese sitio debe esperar al consentimiento antes de ejecutar nada. Esta lista se convierte en las variables de entorno.
• Banner de consentimiento: Uno que pueda establecer una cookie de origen (first-party) tracking_consent cuando un visitante lo acepte.

El cargador es una aplicación pequeña. La mayor parte del trabajo consiste en acordar qué debe cargar cada sitio.

6 pasos para gestionar scripts de seguimiento en varios sitios con Webflow Cloud

Utiliza un Route Handler para ensamblar el cargador de cada sitio a partir de variables de entorno y middleware para verificar el consentimiento en el servidor antes de enviar cualquier URL de proveedor; la configuración del repositorio lleva seis pasos.

Los pasos 1 a 4 se realizan una vez en el repositorio. Los pasos 5 y 6 se repiten para cada sitio que cubras.

1. Crea la estructura del cargador con npm

Crea la estructura del cargador con la configuración predeterminada de npm, lo cual deja next.config intacto y coincide con la página de configuración de Webflow Cloud: "No necesitas añadir un adaptador, una ruta base o un modo de salida". Cada línea que añadas a la configuración puede entrar en conflicto con la compilación de la plataforma.

Ejecuta la creación de la estructura desde el directorio donde guardas los repositorios de los clientes:

npx create-next-app@15 tracking-loader --ts --app --use-npm
cd tracking-loader

La etiqueta @15 fija la versión principal porque Next.js 16 recomienda renombrar middleware.ts a proxy.ts, y el control de consentimiento depende de permanecer en middleware.ts.

Acepta los valores predeterminados para el resto de las indicaciones. Si aceptas el directorio src, recuerda que middleware.ts va después en src/; el resto de esta compilación asume que no hay un directorio src. La página de muestra del andamiaje puede permanecer hasta que escribas la página de verificación.

Omite basePath de next.config. Webflow Cloud inyecta la ruta de montaje durante la compilación, por lo que leerla desde la configuración es el modelo incorrecto. Después de npm run dev, http://localhost:3000 sirve la página predeterminada de Next.js, y git status muestra un andamiaje limpio con un archivo de bloqueo npm y sin ediciones en la configuración.

2. Escribe el controlador de ruta que sirve la etiqueta

Crea app/tag/route.ts para ensamblar el cargador en cada solicitud. El controlador lee dos variables: TRACKING_SITE_NAME, una etiqueta que el cargador expone como window.__trackingSite para que puedas identificar rápidamente qué configuración recibió una página, y TRACKING_SCRIPTS, un objeto JSON con una matriz scripts de URL y una cadena inline opcional.

El resultado es una expresión de función invocada inmediatamente (IIFE) simple que añade una etiqueta de script asíncrono por cada URL. Trata esas variables como código: cualquiera que pueda editar el entorno puede ejecutar JavaScript en cada página del sitio, así que limita quién tiene ese acceso y enumera solo las URL de proveedores https:// de confianza.

Consideraciones y límites del controlador de ruta

Si el sitio envía una política de seguridad de contenido (Content-Security-Policy), añade cada host de proveedor a script-src. Cloudflare también limita cada variable a 5 KB, lo que restringe cuánto puede crecer inline.

Deja export const runtime = 'edge' fuera de este archivo. Webflow Cloud despliega Next.js a través del adaptador OpenNext Cloudflare, que no admite ese destino de tiempo de ejecución, y la compilación fallaría. El controlador ya se ejecuta en Cloudflare Workers sin ninguna directiva.

El ETag utiliza SHA-256 a través de crypto.subtle. Elijo el algoritmo Web Crypto estándar a propósito. Algunas API de tiempo de ejecución se comportan de manera diferente bajo next dev local y en el tiempo de ejecución de Workers desplegado, y un hash que solo existe en un lado es un error que descubrirás después del despliegue.

/tag es un punto final público sin autenticación ni límite de tasa, lo cual está bien para un script que no contiene nada secreto. El controlador también repite la verificación de consentimiento que el paso 3 coloca en el middleware, por lo que el cargador falla de forma segura: si el middleware deja de ejecutarse, los visitantes sin consentimiento siguen recibiendo el script vacío.

Código del controlador de ruta

Aquí tienes el controlador completo:

// app/tag/route.ts
import { NextRequest, NextResponse } from 'next/server';

type Registry = {
  scripts: string[];
  inline: string;
};

function readRegistry(): Registry {
  const raw = process.env.TRACKING_SCRIPTS;
  if (!raw) return { scripts: [], inline: '' };
  try {
    const parsed = JSON.parse(raw) as { scripts?: unknown; inline?: unknown };
    const scripts = Array.isArray(parsed.scripts)
      ? parsed.scripts.filter((s): s is string => typeof s === 'string')
      : [];
    const inline = typeof parsed.inline === 'string' ? parsed.inline : '';
    return { scripts, inline };
  } catch {
    return { scripts: [], inline: '' };
  }
}

function buildLoader(registry: Registry, siteName: string): string {
  const appends = registry.scripts
    .map(
      (src) =>
        `var s=d.createElement('script');s.async=true;s.src=${JSON.stringify(src)};d.head.appendChild(s);`
    )
    .join('\n');
  return [
    '(function(w,d){',
    `w.__trackingSite=${JSON.stringify(siteName)};`,
    appends,
    registry.inline,
    '})(window,document);',
  ].join('\n');
}

async function etagFor(body: string): Promise<string> {
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(body));
  const hex = Array.from(new Uint8Array(digest))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
  return `"${hex.slice(0, 32)}"`;
}

export async function GET(request: NextRequest) {
  // Repeat the consent check here so the loader fails closed if middleware ever stops running.
  const consentRequired = process.env.TRACKING_CONSENT_REQUIRED === 'true';
  if (consentRequired && request.cookies.get('tracking_consent')?.value !== 'granted') {
    return new NextResponse('/* tracking disabled: consent not granted */', {
      status: 200,
      headers: {
        'Content-Type': 'application/javascript; charset=utf-8',
        'Cache-Control': 'private, no-cache',
      },
    });
  }

  const registry = readRegistry();
  const siteName = process.env.TRACKING_SITE_NAME ?? 'unnamed';
  const body = buildLoader(registry, siteName);
  const etag = await etagFor(body);

  if (request.headers.get('if-none-match') === etag) {
    return new NextResponse(null, { status: 304, headers: { ETag: etag } });
  }

  return new NextResponse(body, {
    status: 200,
    headers: {
      'Content-Type': 'application/javascript; charset=utf-8',
      'Cache-Control': 'private, no-cache',
      Vary: 'Cookie',
      ETag: etag,
      'X-Tracking-Scripts': String(registry.scripts.length),
    },
  });
}

El acceso al cargador completo depende de la cookie de consentimiento del visitante, por lo que la respuesta se marca como private con Vary: Cookie para evitar que una caché compartida entregue el cargador completo a un visitante que no ha dado su consentimiento.

El controlador gestiona las entradas incorrectas sin generar errores: un TRACKING_SCRIPTS faltante o mal formado produce un cargador vacío y evita un error 500, y el encabezado X-Tracking-Scripts te indica cuántas URL encontró. Ese encabezado es el diagnóstico más rápido que tendrás una vez que la aplicación esté activa en varios sitios.

Prueba del controlador localmente

Para probarlo localmente, dale al controlador algo que leer:

# .env.local
TRACKING_SITE_NAME=marketing
TRACKING_SCRIPTS='{"scripts":["https://cdn.example.com/analytics.js","https://cdn.example.com/pixel.js"],"inline":"w.__trackingReady=true;"}'
TRACKING_CONSENT_REQUIRED=false

Reinicia npm run dev y ejecuta curl -i http://localhost:3000/tag. La respuesta es un 200 con Content-Type: application/javascript, X-Tracking-Scripts: 2, y un cuerpo que establece w.__trackingSite="marketing" antes de añadir las dos URL de ejemplo.

3. Protege la etiqueta con una cookie de consentimiento en middleware.ts

Añade middleware.ts en la raíz del proyecto para responder a /tag con un script vacío siempre que el sitio requiera consentimiento y el visitante no lo haya otorgado. El control lee TRACKING_CONSENT_REQUIRED y una cookie de origen llamada tracking_consent, que establece el controlador de aceptación de tu banner.

La página de personalización del marco de trabajo de Webflow establece la regla de tiempo de ejecución: "El middleware de tiempo de ejecución de Node.js no es compatible. Solo el middleware de tiempo de ejecución Edge funciona en el tiempo de ejecución de Workers". Mantén el middleware en el tiempo de ejecución Edge y deja el archivo con el nombre middleware.ts.

La respuesta vacía solicita Cache-Control: private, no-cache, lo cual Webflow Cloud aplica en cada respuesta, de modo que el navegador vuelve a validar después de que el visitante acepta. El comparador está escrito como /tag sin el prefijo de montaje porque Webflow Cloud inyecta la ruta de montaje en el momento de la compilación, por lo que la fuente hace referencia a las rutas sin él.

Código del middleware de la puerta de consentimiento

Coloca esto junto a package.json:

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const EMPTY_SCRIPT = '/* tracking disabled: consent not granted */';

export function middleware(request: NextRequest) {
  const consentRequired = process.env.TRACKING_CONSENT_REQUIRED === 'true';
  if (!consentRequired) return NextResponse.next();

  const consent = request.cookies.get('tracking_consent')?.value;
  if (consent === 'granted') return NextResponse.next();

  return new NextResponse(EMPTY_SCRIPT, {
    status: 200,
    headers: {
      'Content-Type': 'application/javascript; charset=utf-8',
      'Cache-Control': 'private, no-cache',
    },
  });
}

export const config = {
  matcher: ['/tag'],
};

La puerta intercepta la solicitud antes de que llegue al controlador, por lo que un sitio puede alternar entre abierto y consentimiento requerido cambiando una sola variable.

Cambia TRACKING_CONSENT_REQUIRED a true en .env.local, reinicia y curl -i http://localhost:3000/tag dos veces: una vez vacío, otra con -H 'Cookie: tracking_consent=granted'. La primera devuelve la línea de comentario única; la segunda devuelve el cargador completo.

4. Añade una página de verificación que respete la ruta de montaje

Reemplaza app/page.tsx con una página que solicite la etiqueta a través de NEXT_PUBLIC_BASE_PATH. La página de "trae tu propia aplicación" es explícita al indicar que "las llamadas fetch del lado del cliente deben incluir manualmente la ruta base", y una etiqueta de script renderizada por tu propia aplicación tiene el mismo requisito.

Una vez que la aplicación está montada en /tracking, una /tag codificada solicita la raíz del sitio de Webflow y no encuentra la aplicación montada.

La página lee la variable en el momento de la compilación y recurre a una cadena vacía localmente, donde no existe ninguna ruta de montaje. Eso te da una página que funciona bajo next dev y en cada sitio desplegado configurado con la misma ruta de montaje sin necesidad de una bifurcación en el código.

Código de la página de verificación

Reemplaza app/page.tsx con esta página:

// app/page.tsx
export default function Page() {
  const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
  const tagUrl = `${basePath}/tag`;

  return (
    <main style={{ fontFamily: 'sans-serif', padding: 24 }}>
      <h1>Tracking loader check</h1>
      <p>
        This page requests <code>{tagUrl}</code>. Open the Network tab and confirm the
        request returns 200. When consent allows the full loader, confirm it has an{' '}
        <code>X-Tracking-Scripts</code> header.
      </p>
      <script src={tagUrl} async />
    </main>
  );
}

Abre esta página primero después de cada despliegue para confirmar, en una sola solicitud, que la ruta de montaje se resuelve y el controlador responde a través de la puerta. Confirma todo, incluido el archivo de bloqueo, y envía los cambios. El repositorio ya está completo; los cambios posteriores específicos del sitio pertenecen a la configuración.

Localmente, la página imprime /tag porque la variable no está establecida. En un sitio desplegado, imprime /tracking/tag, y la pestaña de Red muestra que la solicitud se completa con el encabezado X-Tracking-Scripts.

5. Despliega el mismo repositorio en cada sitio con sus propias variables

Despliega el mismo repositorio en cada sitio con sus propias variables. Para el primer sitio, creo un proyecto de Webflow Cloud, lo conecto al repositorio de git, establezco la ruta de montaje en /tracking y añado las cuatro variables al entorno que despliego. Luego repito el proceso en todos los demás sitios.

La página de variables de entorno de Webflow indica: "Tanto las variables de entorno secretas como las no secretas están disponibles para el proceso de compilación de tu aplicación y para la aplicación desplegada en tiempo de ejecución".

Debido a eso, NEXT_PUBLIC_BASE_PATH puede consumirse en el momento de la compilación, mientras que el controlador y el middleware leen las tres variables de seguimiento por cada solicitud.

Lista de variables de entorno

Establece estas cuatro en el entorno de cada sitio:

• TRACKING_SITE_NAME: Una etiqueta corta como marketing o docs, única por sitio, para que el window.__trackingSite de una página te indique qué configuración recibió.
• TRACKING_SCRIPTS: El objeto JSON con scripts y inline para ese sitio. Una variable por sitio permite que la lista crezca sin necesidad de realizar cambios en el código.
• TRACKING_CONSENT_REQUIRED: La cadena true en sitios que atienden a visitantes que requieren un control de consentimiento, false en otros casos. El middleware compara la cadena de forma exacta.
• NEXT_PUBLIC_BASE_PATH: La ruta de montaje, /tracking, con una barra inclinada al principio y ninguna al final. El prefijo NEXT_PUBLIC_ la incluye en línea, así que nunca la uses para secretos.

Estos valores son configuraciones legibles y sin credenciales. Durante la entrega, la siguiente persona recibe la lista de scripts y el desarrollador de la agencia no conserva ningún token.

Antes de añadir código al encabezado, confirma que el plan del sitio permite publicar código personalizado y que cuenta con un plan Premium o superior si la aplicación está montada en un dominio personalizado. Despliega y mantén la ruta de montaje idéntica en todas partes, ya que la línea de código del encabezado es la misma en cada sitio.

Después de cada despliegue, curl -i https://<that site's domain>/tracking/tag devuelve un 200 cuyo X-Tracking-Scripts recuento coincide con la lista de ese sitio, y /tracking renderiza la página de verificación con /tracking/tag impreso en ella.

6. Haz referencia a la etiqueta desde el código del encabezado de cada sitio

Añade una etiqueta de script en Configuración del sitio > Código personalizado > Código del encabezado antes de publicar. La ruta es relativa, por lo que la misma línea se añade a cada sitio sin necesidad de ediciones.

Es la última vez que tocarás el código del encabezado para el seguimiento en ese sitio:

<script src="/tracking/tag" async></script>

Debido a que la solicitud es del mismo origen, la tracking_consent cookie que establece tu banner viaja con ella. Un despliegue por sitio permite que el control de cada sitio lea su propia cookie.

Configura la cookie para que las solicitudes a /tracking/tag la incluyan; establécela en el controlador de aceptación del banner y añade la etiqueta inmediatamente. Ninguna respuesta se almacena en caché sin revalidación, por lo que una nueva solicitud tras la aceptación supera el control.

Implementación del controlador del banner de consentimiento

Conecta el botón de aceptación del banner a una función como esta:

function grantTrackingConsent() {
  document.cookie = 'tracking_consent=granted; Path=/; Max-Age=15552000; Secure; SameSite=Lax';
  if (window.__trackingSite) return;
  var s = document.createElement('script');
  s.src = '/tracking/tag';
  s.async = true;
  document.head.appendChild(s);
}

Si la etiqueta del código del encabezado ya ejecutó el cargador completo, ya sea en un sitio sin requisito de consentimiento o para un visitante cuya cookie de consentimiento aún está presente, window.__trackingSite se establece y la función finaliza antes de tiempo.

Esto evita que la función añada el cargador una segunda vez. El cargador retiene los scripts de proveedores hasta obtener el consentimiento. La aceptación los carga en la misma vista de página antes de recargar. La cookie dura 180 días, por lo que un visitante recurrente cuyo banner permanece oculto sigue recibiendo el cargador completo.

La retirada funciona de la misma manera a la inversa: borra tracking_consent y recarga, pero los scripts que ya están en la página siguen ejecutándose hasta entonces, y las cookies de cada proveedor necesitan su propia limpieza. La mayoría de las plataformas de consentimiento no establecen esta cookie por ti, así que llama a grantTrackingConsent desde la devolución de llamada de aceptación de tu plataforma.

En una página publicada, utiliza la pestaña Red para confirmar que /tracking/tag devuelve 200, inspecciona si las solicitudes para cada URL de proveedor listada aparecen después, y confirma que window.__trackingSite en la consola devuelve la etiqueta de ese sitio.

¿Qué causa que los scripts de seguimiento fallen en Webflow Cloud?

Empiezo por la ruta de montaje y la configuración del tiempo de ejecución, incluido el nombre del archivo middleware. Un sitio que no cumple con el requisito del plan de dominio personalizado, o una variable de entorno faltante en un sitio, pueden causar otros fallos.

Los siguientes síntomas distinguen los fallos de montaje, tiempo de ejecución, middleware y entorno.

/tracking/tag devuelve un error 404 en el sitio activo, pero /tag funciona en next dev

Causa: La solicitud podría estar llegando al sitio de Webflow y perdiendo la aplicación montada debido al comportamiento de la ruta base que se explica en el paso 4. Una URL codificada de forma rígida o un valor no configurado en ese entorno pueden enviar la solicitud fuera de la aplicación montada y devolver un 404./tagNEXT_PUBLIC_BASE_PATH

El servidor local no tiene ruta de montaje, por lo que el mismo código parece correcto hasta que se implementa. Cuando el comportamiento difiere entre los dominios personalizados de los sitios, verifica si el sitio que falla cumple con el requisito del plan de dominio personalizado.

Solución: Confirma que la línea de código del encabezado sea , y verifica que esté configurado como en el entorno que falla (las variables son por entorno, así que un valor en el entorno del sitio de marketing no afecta al sitio de documentación)./tracking/tagNEXT_PUBLIC_BASE_PATH/tracking

Deja fuera de ; la página de "bring-your-own-app" de Webflow indica que Webflow Cloud lo establece en tiempo de compilación a partir de la ruta de montaje y sobrescribe lo que sea que hayas enviado. Vuelve a implementar y abre primero: cuando la página de verificación imprima , la variable es correcta, así que revisa el código del encabezado a continuación.basePathnext.config/tracking/tracking/tag

Si el plan es la causa, actualiza el sitio a Premium o superior, vuelve a implementar y ejecuta contra en el dominio personalizado; un 200 cuyo recuento de coincida con la lista de ese sitio confirma el montaje.curl -i/tracking/tagX-Tracking-Scripts

La compilación de implementación falla en app/tag/route.ts después de seguir la documentación de "bring-your-own-app"

Causa: El archivo de ruta puede contener la exportación que se explica en el paso 2. La página de "bring-your-own-app" todavía indica que debes agregar esa directiva a las rutas de la API, y seguirla produce una compilación que el adaptador de OpenNext Cloudflare no puede completar. La confusión surge porque una misma palabra tiene dos significados en la misma página.runtime = 'edge'

Webflow Cloud se ejecuta en Cloudflare Workers, una plataforma perimetral, y la documentación lo describe como una implementación "usando el tiempo de ejecución Edge". El objetivo de tiempo de ejecución de Next.js seleccionado por la directiva es un concepto separado que OpenNext no admite. Por lo tanto, la frase de la plataforma puede dar a entender que la directiva es necesaria, aunque sea incompatible.edge

Solución: Elimina la exportación de cada archivo de ruta y vuelve a implementar. El controlador ya se ejecuta en Workers porque es ahí donde Webflow Cloud coloca cada ruta. Si la compilación sigue fallando, busca en el repositorio la cadena por si el andamiaje o un fragmento copiado lo colocó en un diseño o en una segunda ruta.runtimeruntime

La verificación de consentimiento deja de funcionar después de una actualización de Next.js

Causa: El cambio de nombre de middleware-a-proxy de Next 16 entra en conflicto con la regla de tiempo de ejecución de Workers en el paso 3. se ejecuta en el tiempo de ejecución de Node. Al mismo tiempo, la página de personalización del marco indica que solo el middleware de tiempo de ejecución Edge funciona en el tiempo de ejecución de Workers.proxy

El archivo renombrado nunca se ejecuta en Webflow Cloud, por lo que el filtro se detiene silenciosamente. La verificación de consentimiento de la ruta del paso 2 sigue vigente, que es la razón por la que está ahí; sin ella, cada visitante recibiría el cargador completo.

Solución: Mantén el archivo llamado y déjalo en el tiempo de ejecución Edge predeterminado. Rechaza el cambio de nombre automático de un codemod durante una actualización de Next.js y verifica el comportamiento implementado después de cualquier actualización de versión principal solicitando sin la cookie en un sitio que requiera consentimiento; el cuerpo que solo contiene comentarios confirma que el filtro está funcionando.middleware.ts/tracking/tag

Mantén el nombre del archivo en el archivo README precisamente por esta razón: la próxima persona que actualice Next.js verá el cambio de nombre recomendado y no tendrá motivos para dudar de él.

El cargador devuelve 200 con un cuerpo vacío en un sitio y funciona en otro

Causa: El controlador está utilizando el entorno que recibió. Un valor ausente produce una respuesta que parece vacía. El JSON no válido tiene el mismo efecto; una comilla perdida al pegar es la causa habitual, y ignora el error de análisis por diseño.TRACKING_SCRIPTSreadRegistry

El filtro también devuelve una respuesta que parece vacía cuando es y el banner del sitio nunca establece la cookie. Debido a que cada sitio tiene su propio entorno, verifica los valores de cada sitio de forma independiente.TRACKING_CONSENT_REQUIREDtrue,

Solución: Lee los encabezados antes que el cuerpo. Ejecuta contra el de ese sitio sin cookie. Un cuerpo que sea la línea de comentario significa que el filtro se activó, así que configura como o arregla el banner.curl -i/tracking/tagTRACKING_CONSENT_REQUIREDfalse

Un IIFE completo con significa que el registro se analizó vacío: pega el JSON en un archivo temporal y analízalo con primero, luego vuelve a ingresar en ese entorno y vuelve a implementar. Si el recuento es correcto y el proveedor sigue sin mostrar datos, investiga el script del proveedor en sí.X-Tracking-Scripts: 0node -eTRACKING_SCRIPTS

Lo que puedes crear a continuación con scripts de seguimiento y Webflow

Los scripts de proveedores que requieren un fragmento de configuración además de una URL, como el script de sitio de Klaviyo, encajan en el mismo cargador: la URL va en scripts y el fragmento en inline.

Para obtener datos de rendimiento y comportamiento en el sitio sin necesidad de un script de terceros en la lista, Webflow Analyze es la opción integrada de Webflow; una integración con Google Analytics puede ser más exhaustiva, y cualquiera de las dos puede coexistir con este cargador.