Puppeteer
Puppeteer: cómo ve tu sitio un navegador headless
Cómo ve un navegador headless. Un script de Node puede abrir este sitio en Chrome sin ventana, hacer clic en Accept y leer el mismo dataLayer y los mismos hits de GA4 que enviaría un navegador. Esta página es ese recorrido, con la salida de una ejecución real.
Entender el laboratorioCómo usarlo y por qué querrías hacerlo
Por qué querrías hacerlo
Esta página muestra el script y la salida guardada de una ejecución de Chrome headless que abrió este sitio, pulsó Aceptar y leyó el dataLayer. La página no lanza un navegador.
Cómo usarlo
- Lee el lanzamiento en el script. No se está ejecutando ahora.
- El script escucha antes de la navegación y luego pulsa Aceptar.
- La salida guardada es el dataLayer leído dentro de esa página.
- Nada en esta visita inicia Chrome.
Qué es
Puppeteer es una biblioteca de Node.js que conduce Chrome. La construyó el equipo de Chrome en Google. La documentación está en pptr.dev.
«Headless» significa que Chrome sigue cargando la página, ejecutando el JavaScript y pintando los píxeles, pero no abre una ventana. El script pide un titular, un clic o una captura, y Chrome responde. Quien trabaja en analítica lo usa cuando una comprobación tiene que ver la página como la ve un navegador, no como la ve un cliente HTTP simple.
Abrir este laboratorio hace push de virtual_page_view después del consentimiento, con page_path igual a /lab/puppeteer. La etiqueta de GA4 en Google Tag Manager no debe enviar su propio page view, así que ese push es el evento de página. dataLayer muestra el mismo camino, de la cola al hit.
Cómo funciona
Node no habla con la página directamente. Habla con Chrome, y Chrome habla con la página.
Paso 1
Script de Node
El script llama a launch, goto, click y evaluate. Nunca dibuja la página él mismo.
Paso 2
DevTools Protocol
Cada llamada se convierte en un comando JSON por un WebSocket. Chrome responde por el mismo socket.
Paso 3
Chrome headless
Chrome carga el sitio, ejecuta su JavaScript y no tiene ventana en la pantalla.
Para qué lo usan los equipos de analítica
QA automatizado de etiquetas
Abre una página, acepta el consentimiento y haz fallar la ejecución si falta page_view en la cola o en /g/collect.
dataLayer después del consentimiento
Lee la cola antes de Accept y otra vez después. En este sitio las filas de evento aparecen solo cuando el consentimiento está concedido.
Capturas
Guarda los píxeles que pintó Chrome. Esa es la página que habría visto una persona, incluido el texto que escribió JavaScript.
Monitorización sintética
Ejecuta el mismo script con una programación. Un titular ausente, un hit ausente o una navegación fallida es una alerta, no una corazonada.
Rendimiento y Web Vitals
La página puede leer entradas de PerformanceObserver del mismo modo que el laboratorio de recolección las lee en un navegador normal.
Comprobaciones de renderizado SEO
Lee el DOM después de JavaScript. Un crawler que no ejecuta scripts nunca ve ese titular renderizado.
El script, por partes
Estos bloques son trozos del script que produjo la grabación de abajo. Cópialos en este orden. El listener tiene que estar registrado antes de que se abra la página.
Arranque
puppeteer-core habla el protocolo y usa un Chrome que ya tienes. El paquete puppeteer es la misma API con una descarga del navegador incluida. Esta grabación usó puppeteer-core 24 y el Chrome de la máquina.
import puppeteer from "puppeteer-core"
const browser = await puppeteer.launch({
executablePath: "/usr/bin/google-chrome",
headless: true,
args: ["--no-sandbox", "--disable-dev-shm-usage"],
})
const page = await browser.newPage()
await page.setViewport({ width: 1280, height: 800 })Interceptar hits de collect
Registra el listener antes de la navegación. Un hit que sale durante goto, si no, ya se ha ido. GA4 hace POST a /g/collect. Un POST puede llevar varios eventos, una query string por línea.
const hits = []
page.on("request", (request) => {
const url = request.url()
if (!url.includes("google-analytics.com") || !url.includes("/g/collect")) return
hits.push({
method: request.method(),
url,
body: request.postData() || "",
})
})
function eventNames(url, body) {
const parsed = new URL(url)
const chunks = [parsed.search.slice(1), ...body.split(/\n/).map((line) => line.trim()).filter(Boolean)]
const names = []
for (const chunk of chunks) {
const name = new URLSearchParams(chunk).get("en")
if (name) names.push(name)
}
return names
}Abrir la página
goto lleva Chrome a la URL y espera a que el documento haya cargado. waitForSelector retiene el script hasta que existe el titular del hero, lo que significa que JavaScript ha renderizado la página.
const target = "https://blackbox-site-eta.vercel.app/"
await page.goto(target, { waitUntil: "domcontentloaded", timeout: 45000 })
await page.waitForSelector("h1")Leer el dataLayer
page.evaluate se ejecuta en la página. Las filas de dataLayer son listas de argumentos, así que Array.from convierte cada una en un array de verdad antes de que pueda volver a Node.
const before = await page.evaluate(() =>
JSON.parse(JSON.stringify({
userAgent: navigator.userAgent,
webdriver: navigator.webdriver,
dataLayer: (window.dataLayer || []).map((entry) => Array.from(entry)),
}))
)Clic en Accept
El banner de consentimiento es un botón etiquetado Accept. Hacer clic es lo que hace una persona. Hasta ese clic, este sitio no hace push de eventos de medición y no envía un hit de collect por ellos.
const clickedAccept = await page.evaluate(() => {
const button = [...document.querySelectorAll("button")].find((node) => node.textContent.trim() === "Accept")
if (!button) return false
button.click()
return true
})
await page.waitForFunction(() =>
(window.dataLayer || []).some((entry) => {
const list = Array.from(entry)
return list[0] === "event" && list[1] === "page_view"
})
)Captura
La imagen son los píxeles que pintó Chrome, no un dibujo del HTML. Cierra el navegador cuando el script termine para que el proceso no siga en marcha.
await page.screenshot({ path: "puppeteer-home.png" })
await browser.close()Qué vio esa ejecución
Un script se ejecutó el 3 octubre 2026, 17:39 UTC contra https://blackbox-site-eta.vercel.app/. El viewport era 1280 por 800. Se hizo clic en Accept. Esta página no lanza un navegador: un Chrome headless en cada petición sería lento, fácil de repetir en bucle y poco adecuado para una función serverless corta.

User-Agent
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/148.0.0.0 Safari/537.36
Qué informó la página
- navigator.webdriver
- true
- Next.js userAgent()
- Chrome Headless en Linux. is_bot es false.
Cola antes de Accept
- consent default · analytics_storage: denied, ad_storage: denied, ad_user_data: denied, ad_personalization: denied, wait_for_update: 500
- js Date
- config G-JDE6BF33RY
- consent update · analytics_storage: denied, ad_storage: denied, ad_user_data: denied, ad_personalization: denied
Cola después de Accept
- consent default · analytics_storage: denied, ad_storage: denied, ad_user_data: denied, ad_personalization: denied, wait_for_update: 500
- js Date
- config G-JDE6BF33RY
- consent update · analytics_storage: denied, ad_storage: denied, ad_user_data: denied, ad_personalization: denied
- event consent_update · analytics_granted: true
- event segment_update · segments: desktop
- set user_properties · segments: desktop
- consent update · analytics_storage: granted, ad_storage: denied, ad_user_data: denied, ad_personalization: denied
- event page_view · page_location: https://blackbox-site-eta.vercel.app/, page_path: /, page_title: Black Box Personalization, page_referrer:
- event personalization_exposure · personalization_rule: hero:time-of-day,cta:baseline-cta,recommendations:date-order,layout:standard-weight
- event segment_update · segments: new-visitor,desktop
- set user_properties · segments: new-visitor,desktop
- event segment_update · segments: new-visitor,desktop,other-region
- set user_properties · segments: new-visitor,desktop,other-region
Antes de Accept la cola tiene el consentimiento por defecto, el arranque de la etiqueta y una actualización de consentimiento que sigue denegada. No hay page_view. Después de Accept la misma cola gana consent_update, segment_update, page_view y personalization_exposure. Se dejan fuera las filas de etiqueta sin nombre de comando.
Hits de collect
Tres POST llegaron a www.google-analytics.com/g/collect. Los dos primeros salieron mientras el consentimiento seguía denegado, así que su gcs es G100. El tercero es un lote: user_engagement, page_view, personalization_exposure y dos eventos segment_update, con gcs G101. page_view no repite la ruta como parámetro de evento. La ubicación del documento es el campo compartido dl, que es la URL de la portada. El tamaño de pantalla del hit es 800x600, el valor por defecto de headless, aunque el script fijó un viewport de 1280 por 800. Se omiten campos de transporte como gtm y gcd para que los campos del evento se lean bien.
Petición 1 · POST /g/collect
G100 significa que analytics storage seguía denegado cuando salió este hit.
- tid
- G-JDE6BF33RY
- gcs
- G100
- cid
- 1081073262.1791049135
- sid
- 1791049135
- dl
- https://blackbox-site-eta.vercel.app/
- dt
- Black Box Personalization
- sr
- 800x600
consent_update
ep.analytics_granted=true
Petición 2 · POST /g/collect
G100 significa que analytics storage seguía denegado cuando salió este hit.
- tid
- G-JDE6BF33RY
- gcs
- G100
- cid
- 1081073262.1791049135
- sid
- 1791049135
- dl
- https://blackbox-site-eta.vercel.app/
- dt
- Black Box Personalization
- sr
- 800x600
segment_update
ep.segments=desktop
Petición 3 · POST /g/collect
G101 significa que analytics storage estaba concedido y ad storage siguió denegado.
- tid
- G-JDE6BF33RY
- gcs
- G101
- cid
- 1081073262.1791049135
- sid
- 1791049135
- dl
- https://blackbox-site-eta.vercel.app/
- dt
- Black Box Personalization
- sr
- 800x600
user_engagement
ep.ga_temp_client_id=1081073262.1791049135 · up.segments=desktop
page_view
No hay parámetros de evento en esta fila. La URL de la página es dl, arriba.
personalization_exposure
ep.personalization_rule=hero:time-of-day,cta:baseline-cta,recommendations:date-order,layout:standard-weight
segment_update
ep.segments=new-visitor,desktop
segment_update
ep.segments=new-visitor,desktop,other-region · up.segments=new-visitor,desktop
Bots, y números que no son personas
Los sitios detectan los navegadores automáticos de unas pocas formas ordinarias. La cadena User-Agent puede decir HeadlessChrome, o puede nombrar un crawler conocido. navigator.webdriver es true bajo Puppeteer salvo que el script lo apague. El tamaño de pantalla, la ventana ausente y un clic que ocurre en el instante en que existe el botón son otras pistas. Ninguna es perfecta. Un script puede cambiar su User-Agent y mover un ratón.
El tráfico de bots sin filtrar cae en los mismos informes que las personas. Se mueven las vistas de página, los eventos y las landings. Un script que hace clic en Accept parece haber aceptado, así que Consent Mode deja pasar los hits. La tasa de rebote, el engagement y el tiempo real se desplazan, y una ejecución de QA de etiquetas no se distingue de un visitante salvo que algo marque la diferencia.
robots.txt permite / y pide a los crawlers que se salten /account, /admin, y /api. Eso es una indicación para los crawlers educados. No detiene Chrome, y no quita un hit de Google Analytics.
POST /api/collect devuelve 403 cuando el consentimiento no está concedido, salvo un consent_change que registra el paso de granted a denied. Esa fila se guarda con consent denied. Cuando se guarda un beacon con consentimiento, Next.js userAgent() pone is_bot a partir de una lista fija de nombres de crawler. HeadlessChrome no está en esa lista. Otra comprobación busca HeadlessChrome, PhantomJS, Puppeteer, Playwright y Selenium, y otra marca una clave de visitante que ya guardó 40 beacons en 60 segundos. Esas filas conservan bot_reason y se quedan en el registro. Los informes de Entender las saltan. El pathing, las recomendaciones y la etiqueta de GA no.
El laboratorio de bots muestra las tres reglas y los conteos. Para el User-Agent de la ejecución de arriba, el parser de Next.js dice Chrome Headless y is_bot es false, y la comprobación de headless es lo que lo marca.
RecorridoCómo lo hicimosMostrarOcultar
El ajuste de proveedor de ejemplo está marcado abajo. Los números de eVar y de event son ejemplos. Este laboratorio no llama a Adobe.
El laboratorio de Puppeteer muestra el script y la salida guardada de una ejecución de Chrome headless que abrió este sitio, hizo clic en Accept y leyó el dataLayer. Esta página no lanza un navegador y no llama a Adobe.
Mostrar un arranque
El primer ejemplo llama a puppeteer.launch con un Chrome que ya está en la máquina, luego abre una página y fija un viewport. La página no ejecuta ese código.
Escuchar antes de la navegación
El ejemplo de collect registra un listener de peticiones antes de goto. Se queda con las peticiones cuya URL contiene google-analytics.com y /g/collect, y eventNames lee el parámetro en.
Leer la cola en la página
page.evaluate copia userAgent, webdriver y el dataLayer. Cada fila del dataLayer se convierte en un array para poder volver a Node.
Mostrar una ejecución guardada
RunOutput lee la grabación incluida y dice que esta página no lanza Chrome. Los componentes del laboratorio no llaman a trackLabEvent.
Del código
El listener se registra antes de la navegación. Los nombres de evento son los valores en del hit de collect.
code: `const hits = []
page.on("request", (request) => {
const url = request.url()
if (!url.includes("google-analytics.com") || !url.includes("/g/collect")) return
hits.push({
method: request.method(),
url,
body: request.postData() || "",
})
})
function eventNames(url, body) {
const parsed = new URL(url)
const chunks = [parsed.search.slice(1), ...body.split(/\\n/).map((line) => line.trim()).filter(Boolean)]
const names = []
for (const chunk of chunks) {
const name = new URLSearchParams(chunk).get("en")
if (name) names.push(name)page.evaluate lee el dataLayer dentro de la página y devuelve un objeto plano.
code: `const before = await page.evaluate(() =>
JSON.parse(JSON.stringify({
userAgent: navigator.userAgent,
webdriver: navigator.webdriver,
dataLayer: (window.dataLayer || []).map((entry) => Array.from(entry)),
}))
)`,
},Google y Adobe
Este laboratorio no encola un evento propio. El bloque de Google muestra un ejemplo de cómo rastrearías la interacción. Adobe también es un ejemplo.
Este laboratorio no encola un evento de analítica propio. Después de Aceptar, el sitio sigue encolando virtual_page_view de la página, con page_path y page_title. Los clics dentro de una región data-track-ignore no se registran. El push de abajo es un ejemplo, no una llamada de esta página. Este sitio no llama a gtag('set') ni a Adobe.
Solo ejemplo. Esta página no hace push de este objeto.
// Example only. This lab does not queue this event.
dataLayer.push({
event: "puppeteer_run_example",
command: "goto",
})Implementación de ejemplo. Este sitio no llama a Adobe. eVar94, prop94 y event94 son números de variable de ejemplo. En Launch, un elemento de datos lee el valor y una regla lo envía cuando el valor cambia. En el report suite, habilita eVar94 con asignación Most Recent y haz que expire en el hit. Una processing rule no hace falta si el elemento de datos se mapea directo a esa eVar.
Payload de alloy de ejemplo. _example es un esquema de relleno, no un inquilino real.
alloy("sendEvent", {
xdm: {
eventType: "web.webinteraction.linkClicks",
_example: {
headlessCommand: "goto",
},
},
})Hit de ejemplo. eVar94 tiene alcance de hit en este ejemplo. prop94 muere en el mismo hit.
s.eVar94 = "goto"
s.prop94 = "goto"
s.events = "event94"
s.linkTrackVars = "eVar94,prop94,events"
s.linkTrackEvents = "event94"
s.tl(true, "o", "puppeteer_run_example")Traducción
Cada campo del laboratorio, el nombre en GA4 y la variable de Adobe de ejemplo. El alcance es la parte que suele perderse en la traducción.
Comando
GA4. No se envía. El script se muestra. Esta página no lo ejecuta.
Adobe. eVar94 de ejemplo, expira en el hit.
Alcance. Hit, si rastrearas un comando en una ejecución real. Esta página no lo hace.
Nombre del evento de collect
GA4. Esta página no lo envía. El ejemplo lee en de una URL de collect.
Adobe. prop94 de ejemplo, que muere en el hit.
Alcance. Evento, en un hit que observó un navegador headless. No es una propiedad de usuario.
Fila del dataLayer
GA4. No se envía. La grabación guardada se pinta en la página.
Adobe. Ejemplo: no copies una fila de la cola en eVar94.
Alcance. No es un hit de esta página.
Clic en Accept
GA4. Esta página no lo envía. El script de ejemplo hace clic en el botón Accept dentro de Chrome.
Adobe. event94 de ejemplo si una ejecución contara ese clic. eVar94 guardaría el comando, no esta página.
Alcance. Evento, dentro de la ejecución headless. Esta visita no lo dispara.
Recomendado a continuación
Por qué estas propuestasLeyendo las transiciones de recorrido…