Contents
Introducción
Este tutorial explica, con todo lujo de detalles, cómo enviar eventos a Google Analytics (GA4) desde un bloque de Gutenberg (JavaScript). Cubre desde la integración básica de gtag, el registro correcto del bloque en WordPress, hasta ejemplos de código para el editor y el front-end, y recomendaciones sobre consentimiento y depuración.
Requisitos previos
- WordPress 5.0 con editor Gutenberg activo.
- Cuenta de Google Analytics 4 y Measurement ID (por ejemplo: G-XXXXXXXXXX).
- Conocimientos básicos de JavaScript (ESNext), React en bloques y PHP para registrar scripts.
- En sitios con políticas de privacidad estrictas, un gestor de consentimiento (cookie consent) para respetar GDPR/CCPA.
Conceptos clave de GA4
- gtag(event, …): forma típica de enviar eventos si cargas gtag.js con tu Measurement ID.
- dataLayer: si usas Google Tag Manager, en lugar de gtag puedes empujar al dataLayer: window.dataLayer.push(…).
- Nombre del evento y parámetros: GA4 usa un nombre de evento y parámetros adicionales (por ejemplo: event_name: cta_click, params: {button_name: subscribe, value: 1}).
- DebugView: imprescindible para verificar eventos en tiempo real en GA4.
1) Incluir Google Analytics (gtag) en WordPress
La forma más simple: encolar el script de gtag en functions.php para que esté disponible en el front-end. También puede cargarse mediante un plugin específico o mediante GTM.
// functions.php (ejemplo simple)
function mi_tema_enqueue_gtag() {
measurement_id = G-XXXXXXXXXX // sustituir por tu Measurement ID
// Encolar gtag.js
wp_enqueue_script(
gtag-js,
https://www.googletagmanager.com/gtag/js?id={measurement_id},
array(),
null,
false
)
// Insertar initializar gtag con inline script
inline =
window.dataLayer = window.dataLayer []
function gtag(){dataLayer.push(arguments)}
gtag(js, new Date())
gtag(config, {measurement_id})
wp_add_inline_script(gtag-js, inline)
}
add_action(wp_enqueue_scripts, mi_tema_enqueue_gtag)
2) Registrar el bloque y sus scripts (PHP)
Registra los assets del bloque (editor y front-end) y pasa al JS variables necesarias como el Measurement ID o banderas de consentimiento.
// functions.php (registro de bloque)
function mi_plugin_register_block() {
dir = dirname( __FILE__ )
// Registro del script del bloque (editor)
wp_register_script(
mi-bloque-editor,
plugins_url(build/editor.js, __FILE__),
array(wp-blocks,wp-element,wp-editor,wp-i18n),
filemtime( dir . /build/editor.js )
)
// Registro del script para frontend del bloque (si es necesario)
wp_register_script(
mi-bloque-frontend,
plugins_url(build/frontend.js, __FILE__),
array(),
filemtime( dir . /build/frontend.js ),
true
)
// Pasar datos a JS (p. ej. Measurement ID y flag de consentimiento)
wp_localize_script( mi-bloque-editor, MiBloqueSettings, array(
measurementId => G-XXXXXXXXXX,
consentGiven => true, // o lógica para detectar consentimiento real
))
register_block_type( mi-plugin/mi-bloque, array(
editor_script => mi-bloque-editor,
script => mi-bloque-frontend
) )
}
add_action( init, mi_plugin_register_block )
3) Enviar eventos desde el bloque (editor) — ejemplo JS
Este ejemplo muestra un bloque simple con un botón. Al hacer clic se enviará un evento a GA. Ten en cuenta que en el editor (back-end) normalmente no envías eventos a GA público en este ejemplo el envío está pensado para el front-end o si realmente quieres trackear interacciones del editor se debería usar un Measurement ID distinto y considerar privacidad.
// editor.js (ejemplo ESNext para registerBlockType)
import { registerBlockType } from @wordpress/blocks
import { Button } from @wordpress/components
import { useState } from @wordpress/element
registerBlockType(mi-plugin/mi-bloque, {
title: Bloque con evento GA,
icon: megaphone,
category: common,
edit: () => {
const [count, setCount] = useState(0)
const sendGAEvent = (action = click) => {
const measurementId = (typeof MiBloqueSettings !== undefined) ? MiBloqueSettings.measurementId : null
// Comprueba consentimiento si está disponible
const consent = (typeof MiBloqueSettings !== undefined) ? MiBloqueSettings.consentGiven : true
if (!consent) {
console.log(Consentimiento no otorgado — evento no enviado)
return
}
// Si gtag está disponible
if (typeof window.gtag === function) {
window.gtag(event, bloque_interaccion, {
event_category: bloque,
event_label: mi-boton,
value: count 1,
measurement_id: measurementId
})
console.log(Evento enviado con gtag)
return
}
// Si se usa dataLayer (GTM)
if (Array.isArray(window.dataLayer)) {
window.dataLayer.push({
event: bloque_interaccion,
category: bloque,
label: mi-boton,
value: count 1
})
console.log(Evento enviado al dataLayer)
return
}
console.log(No hay gtag ni dataLayer disponible)
}
return (
Ejemplo de bloque que envía eventos a Google Analytics.
)
},
save: () => {
return (
BLOQUE: contenido estático en el front-end — el JS del front-end gestiona el evento real.
)
}
})
4) Enviar eventos desde el front-end del bloque (JS)
Para detectar interacciones reales del usuario en el sitio público, incluye un script que se ejecute en el front-end. Aquí un ejemplo sencillo que escucha clics y envía eventos.
// frontend.js
document.addEventListener(DOMContentLoaded, function() {
const botones = document.querySelectorAll(.mi-bloque-frontend .mi-boton)
botones.forEach(btn => {
btn.addEventListener(click, function() {
const label = this.getAttribute(data-label) mi-boton
const value = parseInt(this.getAttribute(data-value) 1, 10)
// Comprueba gtag
if (typeof window.gtag === function) {
window.gtag(event, mi_boton_click, {
button_label: label,
value: value
})
return
}
// fallback a dataLayer
window.dataLayer = window.dataLayer []
window.dataLayer.push({
event: mi_boton_click,
button_label: label,
value: value
})
})
})
})
5) Manejo de consentimiento (GDPR) — ejemplo simple
Antes de enviar cualquier evento, asegúrate de que el usuario ha dado su consentimiento si la legislación lo exige. Aquí un patrón sencillo: no enviar eventos hasta que el gestor de consentimientos haya marcado permiso.
// Ejemplo: escuchar evento custom generado por tu gestor de cookies
window.addEventListener(cookieConsentGiven, function(e) {
// e.detail puede contener permisos concretos
window._ga_consent = true
})
// Uso en tu código
if (window._ga_consent) {
window.gtag(event, consented_event, { })
} else {
// aplazar evento o no enviarlo
}
6) Parámetros recomendados y buenas prácticas
GA4 es flexible, pero sigue buenas prácticas para que los datos sean útiles:
| Parámetro | Descripción | Ejemplo |
|---|---|---|
| event_name | Nombre del evento, breve y en minúsculas con guiones bajos. | mi_boton_click |
| button_label | Etiqueta para identificar el elemento. | suscribirme, comprar |
| value | Valor numérico relacionado con el evento (1, precio, etc.). | 1, 29.99 |
| page_location / page_title | Información contextual de la página donde ocurre el evento. | document.location.href, document.title |
7) Depuración y verificación
- Activa DebugView en GA4: en la interfaz de Google Analytics, ve a Admin gt DebugView y filtra tus eventos.
- Usa la extensión de Google Analytics Debugger para el navegador (console logs de gtag).
- Observa la pestaña Network para verificar requests a collect/measurement.
- Incluye console.log en tus scripts para confirmar ejecución antes de enviar al Analytics.
8) Casos comunes y errores frecuentes
- No aparece gtag ni dataLayer: asegúrate de que el script de gtag o GTM se haya cargado antes de ejecutar tu código.
- Eventos enviados pero no aparecen en GA: comprueba DebugView, las métricas pueden tardar si no es DebugView nombre de evento inválido o filtros pueden impedir visión.
- Problemas de consentimiento: muchos gestores bloquean gtag hasta que el usuario acepta integra tu lógica para no enviar información hasta que se acepte.
- Enviar eventos desde el editor: evita contaminar datos de producción considera un Measurement ID separado para eventos del editor o envía únicamente desde el front-end.
9) Ejemplos avanzados
Si quieres enviar eventos server-side (Measurement Protocol) o enriquecer eventos con datos de usuario desde WordPress (por ejemplo, ID de usuario autenticado) deberías:
- Utilizar la Measurement Protocol de GA4 mediante requests HTTP desde PHP, respetando privacidad y hashing de identificadores cuando aplique.
- Enviar eventos en el rendering del servidor si necesitas garantizar envío incluso con JS desactivado (caso extremo).
Ejemplo básico de envío server-side (concepto)
// Nota: este es un ejemplo conceptual y requiere tu API secret y Measurement ID
measurement_id = G-XXXXXXXXXX
api_secret = YOUR_API_SECRET
endpoint = https://www.google-analytics.com/mp/collect?measurement_id={measurement_id}api_secret={api_secret}
payload = array(
client_id => CLIENT_ID_OR_GENERATED_UUID,
events => array(
array(
name => registro_completado,
params => array(
method => newsletter,
value => 1
)
)
)
)
json = wp_json_encode( payload )
response = wp_remote_post( endpoint, array(
headers => array(Content-Type => application/json),
body => json
) )
Resumen y puntos clave
- Preferencia: usa gtag para GA4 o dataLayer si usas GTM. Ambos son compatibles con bloques de Gutenberg.
- Registra y encola correctamente scripts del editor y front-end desde PHP usando wp_register_script / register_block_type.
- Gestiona consentimiento antes de enviar datos de usuarios.
- Usa DebugView y la consola para verificar envíos y depurar errores.
- Evita enviar eventos de producción desde el editor salvo que sepas qué haces usa un Measurement ID separado si necesitas métricas del editor.
Recursos útiles
Documentación oficial de GA4: https://developers.google.com/analytics/devguides/collection/ga4/events
Documentación Measurement Protocol (server-side): https://developers.google.com/analytics/devguides/collection/protocol/ga4
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |