Aula privada | GA4 WebAR Básico

GA4 básico

Mapa del proyecto: primero WebAR, después analítica

En este nivel no vamos a copiar un bloque enorme sin contexto. Vamos a construir la experiencia como lo haría un desarrollador real: primero una página HTML, luego una escena de realidad aumentada con MindAR, después una propiedad de Google Analytics 4 y finalmente eventos que conectan lo que ocurre en la cámara con los reportes de GA4.

La idea central es simple: una experiencia WebAR no solo debe verse bonita. También debe responder preguntas: ¿cuántas personas abrieron la experiencia?, ¿cuántas lograron detectar el marcador?, ¿cuántas hicieron clic?, ¿en qué punto se perdió la interacción? GA4 nos ayuda a medir esas respuestas.

Qué vas a crear

Una página index.html.
Una experiencia MindAR con un target de imagen.
Un archivo analytics.js para enviar eventos a GA4.
Un archivo app.js para escuchar eventos de WebAR.
Un template final descargable para practicar.

Orden correcto

Crear estructura HTML.
Compilar imagen target.
Probar MindAR sin GA4.
Crear propiedad GA4.
Instalar el script de GA4.
Medir eventos WebAR.

Archivos finales

Al terminar tendrás esta estructura:

index.html: estructura visual, scripts y escena AR.
styles.css: estilos básicos de la interfaz sobre cámara.
analytics.js: función reutilizable para enviar eventos a GA4.
app.js: lógica de MindAR, eventos y clics.
targets/analitica.mind: marcador compilado.

Entiendo el mapa del proyecto

Paso 1

Crear el archivo HTML desde cero

Antes de hablar de MindAR o GA4 necesitamos una página web. WebAR significa realidad aumentada en la web, por eso todo empieza con HTML. HTML no programa la lógica; HTML define la estructura: qué elementos existen, dónde se cargan los scripts y qué contenido verá el navegador.

Crea una carpeta llamada webar-ga4-basico. Dentro crea un archivo llamado index.html. Si estás usando Visual Studio Code, puedes hacerlo desde el panel lateral: clic derecho sobre la carpeta, opción New File, y escribes index.html.

Primer HTML del proyectoindex.html

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>WebAR medible con GA4</title>
  </head>
  <body>
    <h1>Mi primera experiencia WebAR medible</h1>
  </body>
</html>

Explicación línea por línea

Línea 1: indica al navegador que este documento usa HTML moderno.
Línea 2: abre el documento HTML y declara que el idioma principal es español.
Línea 3: abre el head, la zona donde ponemos información técnica de la página.
Línea 4: permite usar tildes, eñes y caracteres especiales correctamente.
Línea 5: hace que la página se adapte al ancho del celular.
Línea 6: define el título que aparece en la pestaña del navegador.
Línea 8: abre el body, la zona visible de la página.
Línea 9: muestra un título temporal para confirmar que el archivo funciona.

Prueba rápida

Abre este archivo con Live Server. Si ves el texto en el navegador, la base HTML ya funciona. Todavía no hay realidad aumentada ni analítica. Eso está bien: estamos avanzando por capas.

Ya creé mi index.html inicial

Paso 2

Conceptos básicos antes de usar MindAR

MindAR es una librería de JavaScript que permite reconocer imágenes desde la cámara del navegador. Cuando MindAR reconoce una imagen objetivo, calcula su posición y orientación para que podamos colocar contenido encima: texto, modelos 3D, videos, botones visuales o cualquier elemento de A-Frame.

En este curso usaremos image tracking. Eso significa que la experiencia se activa cuando la cámara ve una imagen plana, por ejemplo una postal, un empaque, un póster o una hoja impresa. Esa imagen primero debe convertirse en un archivo .mind. El archivo .mind no es la imagen original; es un archivo optimizado que contiene las características visuales que MindAR necesita para reconocerla.

Términos importantes

Target: imagen que la cámara debe reconocer.
.mind: archivo compilado que usa MindAR.
A-Frame: framework para escribir escenas 3D con etiquetas HTML.
targetFound: evento cuando el marcador se detecta.
targetLost: evento cuando el marcador se pierde.

Buena imagen target

Usa imágenes con detalles, contraste, bordes, texto o patrones. Evita fondos planos, imágenes borrosas, logos demasiado simples o superficies repetitivas. Si el target es débil, la analítica también será confusa porque muchos usuarios no lograrán activar la experiencia.

Compilador integrado

Elegir imagen, compilar target y generar .mind

Selecciona una imagen de prueba, compílala y descarga el archivo. Luego crea una carpeta llamada targets en tu proyecto y guarda el archivo como analitica.mind.

Seleccionar imagen target

Selecciona una imagen para iniciar.

La vista previa de la imagen aparecerá aquí.

Ya entiendo target, .mind y eventos de MindAR

Paso 3

Agregar A-Frame y MindAR al HTML

Ahora vamos a preparar el HTML para que pueda usar realidad aumentada. Para eso cargamos dos librerías externas dentro del head. A-Frame nos permite escribir una escena 3D usando etiquetas como <a-scene>, <a-camera> y <a-text>. MindAR se conecta con A-Frame y agrega el reconocimiento de imágenes.

Estos scripts se colocan dentro del head, después del title. Los ponemos ahí para que el navegador los tenga disponibles cuando llegue al cuerpo de la página y encuentre la escena AR.

HTML acumulado con librerías ARindex.html

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>WebAR medible con GA4</title>
    <script src="https://aframe.io/releases/1.5.0/aframe.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/mind-ar@1.2.5/dist/mindar-image-aframe.prod.js"></script>
  </head>
  <body>
    <h1>Mi primera experiencia WebAR medible</h1>
  </body>
</html>

Explicación línea por línea

Línea 7: carga A-Frame. Sin esta librería, el navegador no entendería etiquetas como <a-scene>.
Línea 8: carga MindAR para image tracking. Esta versión integra MindAR con A-Frame.
Importante: ambos scripts vienen de internet. Si trabajas sin conexión, no cargarán. En servidor real deben cargarse por HTTPS.

Ya agregué A-Frame y MindAR

Paso 4

Crear la primera escena WebAR sin GA4

Antes de medir, necesitamos que la experiencia funcione. Este paso crea una escena MindAR básica. Si el target se detecta, veremos un plano blanco y un texto sobre la imagen. Todavía no estamos enviando eventos a Google Analytics. Primero confirmamos que la cámara, el target y la escena funcionan.

MindAR básico acumuladoindex.html

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>WebAR medible con GA4</title>
    <script src="https://aframe.io/releases/1.5.0/aframe.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/mind-ar@1.2.5/dist/mindar-image-aframe.prod.js"></script>
  </head>
  <body>
    <div class="hud">
      <strong>WebAR básico</strong>
      <p id="status">Apunta la cámara al marcador.</p>
    </div>

    <a-scene mindar-image="imageTargetSrc: targets/analitica.mind;" embedded color-space="sRGB" vr-mode-ui="enabled: false" device-orientation-permission-ui="enabled: false">
      <a-camera position="0 0 0" look-controls="enabled: false"></a-camera>
      <a-entity id="target" mindar-image-target="targetIndex: 0">
        <a-plane color="#ffffff" width="1.35" height="0.9" position="0 0 0.04"></a-plane>
        <a-text value="Mi primera experiencia WebAR" align="center" color="#0f172a" position="0 0.1 0.08" width="2.8"></a-text>
      </a-entity>
    </a-scene>
  </body>
</html>

Explicación línea por línea

Líneas 10 a 13: crean una interfaz fija sobre la cámara. El párrafo con id="status" luego se actualizará desde JavaScript.
Línea 15: crea la escena AR. El atributo mindar-image indica dónde está el archivo .mind.
Línea 16: crea la cámara de A-Frame. look-controls se desactiva porque MindAR controla la posición.
Línea 17: crea el marcador lógico. targetIndex: 0 significa que usamos el primer target del archivo .mind.
Línea 18: agrega un plano blanco encima del marcador.
Línea 19: agrega texto aumentado sobre el plano.

Antes de continuar

Prueba esta escena con Live Server o en un servidor HTTPS. Si la cámara no abre, revisa permisos del navegador. Si no detecta el target, revisa que el archivo se llame exactamente targets/analitica.mind.

Si la cámara se ve a media pantalla

Eso normalmente ocurre porque el documento no tiene altura completa o porque el canvas de A-Frame queda ocupando solo una parte del navegador. En el template final ya corregimos esto con CSS: la cámara queda como video fijo a pantalla completa, el canvas transparente queda encima y no usamos fondos negros que puedan tapar la cámara.

CSS para cámara a pantalla completastyles.css

html,
body {
  width: 100%;
  height: 100%;
  min-height: 100dvh;
  margin: 0;
  overflow: hidden;
  background: transparent;
}

body {
  position: fixed;
  inset: 0;
}

a-scene,
canvas,
.a-canvas {
  position: fixed !important;
  inset: 0 !important;
  width: 100vw !important;
  height: 100dvh !important;
  background: transparent !important;
}

video {
  position: fixed !important;
  inset: 0 !important;
  width: 100vw !important;
  height: 100dvh !important;
  object-fit: cover !important;
}

Ya probé MindAR sin GA4

Paso 5

Qué es Google Analytics 4 y qué vamos a medir

Google Analytics 4, o GA4, es la versión actual de Google Analytics. Sirve para medir lo que hacen los usuarios dentro de un sitio web o aplicación. A diferencia de enfoques antiguos basados principalmente en páginas vistas, GA4 trabaja con eventos. Un evento es una acción que queremos registrar: abrir la experiencia, detectar un target, perder un target, hacer clic o enviar un formulario.

En WebAR esto es muy útil porque una página vista no nos dice si la experiencia aumentada realmente funcionó. Una persona puede abrir la página y abandonarla sin detectar el marcador. Por eso necesitamos eventos específicos de AR.

Conceptos de GA4

Propiedad: contenedor principal de datos de un sitio o negocio.
Flujo web: conexión entre tu sitio web y GA4.
Measurement ID: identificador con formato G-XXXXXXXXXX.
Evento: acción medible, por ejemplo target_found.
Parámetro: dato adicional del evento, por ejemplo target_index: 0.

Eventos básicos del curso

webar_page_open: la experiencia se abrió.
target_found: MindAR detectó el marcador.
target_lost: MindAR perdió el marcador.
cta_click: el usuario hizo clic en el botón.

Dónde encontrar GA4

GA4 se encuentra dentro de Google Analytics. Para entrar, abre analytics.google.com con una cuenta de Google. Si es la primera vez que entras, Google te pedirá crear una cuenta de Analytics. Esa cuenta no es tu correo; es un contenedor administrativo donde luego crearás propiedades.

Entra a analytics.google.com.
Inicia sesión con una cuenta de Google.
Busca el botón o sección Administrar. Normalmente aparece con un icono de engranaje.
Revisa que estés en la cuenta correcta. Si manejas varios clientes, puedes cambiar de cuenta con el selector superior.
Dentro de Administrar, busca la opción Crear y luego Propiedad.

Cómo crear la propiedad GA4

En Administrar, haz clic en Crear y selecciona Propiedad.
Escribe un nombre claro, por ejemplo WebAR GA4 Basico o el nombre del cliente.
Selecciona zona horaria y moneda. Esto ayuda a que los reportes tengan fechas y valores correctos.
Continúa el asistente. Google puede preguntarte objetivos del negocio; para este curso puedes elegir opciones relacionadas con leads, interacción o comportamiento de usuario.
Cuando la propiedad esté creada, continúa con la configuración de recopilación de datos.

Una propiedad es el espacio donde GA4 guardará los eventos de tu experiencia. Si haces una experiencia WebAR para un cliente diferente, lo más ordenado es crear una propiedad o al menos un flujo separado para ese proyecto.

Crear el flujo web

El flujo web es la conexión entre tu página WebAR y GA4. Como MindAR corre dentro del navegador, necesitas un flujo de tipo Web, no Android ni iOS.

Dentro de la propiedad, entra a Flujos de datos.
Haz clic en Añadir flujo o elige la plataforma Web.
Escribe la URL donde estará publicada la experiencia, por ejemplo https://tudominio.com/webar-ga4.
Escribe un nombre de flujo, por ejemplo Experiencia WebAR MindAR.
Deja activada la medición mejorada si quieres que GA4 mida páginas vistas y algunas interacciones automáticas. Para este curso, además, enviaremos eventos propios desde JavaScript.
Crea el flujo.

Qué dato necesitas copiar

El dato que necesitas para el código es el ID de medición. Tiene formato G-XXXXXXXXXX. Google lo muestra dentro de los detalles del flujo web. Ese ID es el puente entre tu página y tu propiedad GA4: si lo copias mal, los eventos no llegarán al lugar correcto.

Referencia oficial: Google: encontrar el ID de medición.

Video guía: crear GA4 para WebAR En este video verás dónde entrar en Google Analytics, cómo ubicar la propiedad, el flujo web y el ID de medición que luego pegaremos en el proyecto.

Ya entiendo qué es GA4 y qué mediremos

Paso 6

Instalar el script de GA4 dentro del HTML

El script de GA4 se coloca dentro del head del documento, normalmente después del title y antes de las librerías principales de la experiencia. No se coloca dentro de a-scene, ni dentro de body al azar. Su trabajo es preparar la función gtag, que será la encargada de enviar datos a Google Analytics.

Para conseguir este script desde GA4, entra a Administrar, abre Flujos de datos, selecciona tu flujo web y busca la sección del Google tag. Allí puedes entrar a las instrucciones de instalación y elegir instalación manual. Google mostrará un bloque de código parecido al que usamos abajo.

Ruta dentro de GA4 para encontrar el tag

Abre analytics.google.com.
Entra a Administrar.
Verifica que estás en la propiedad correcta.
En la zona de propiedad, entra a Flujos de datos.
Selecciona la pestaña Web y haz clic en tu flujo web.
Busca el ID de medición. Debe empezar por G-.
Busca Ver instrucciones de etiqueta o View tag instructions.
Elige Instalar manualmente y copia el bloque del Google tag.

En el código de abajo estamos agregando GA4 al HTML que ya habíamos construido. Observa que seguimos conservando A-Frame y MindAR. La página ahora tiene tres capas: estructura HTML, realidad aumentada y analítica.

HTML acumulado con GA4index.html

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>WebAR medible con GA4</title>
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag("js", new Date());
      gtag("config", "G-XXXXXXXXXX");
    </script>
    <script src="https://aframe.io/releases/1.5.0/aframe.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/mind-ar@1.2.5/dist/mindar-image-aframe.prod.js"></script>
  </head>
</html>

Explicación línea por línea

Línea 7: descarga la librería gtag.js desde Google. Cambia G-XXXXXXXXXX por tu Measurement ID real.
Línea 8: abre un bloque de JavaScript interno dentro del HTML.
Línea 9: crea dataLayer, una lista donde se guardan los comandos que se enviarán a Google.
Línea 10: crea la función gtag. Cada vez que la llamamos, agrega información a dataLayer.
Línea 11: registra el momento en que GA4 queda inicializado.
Línea 12: conecta esta página con tu propiedad GA4.

Cómo verificar si funciona

Guarda el archivo index.html.
Ábrelo con Live Server o desde HTTPS.
En GA4, entra a Informes en tiempo real o Realtime.
Abre tu experiencia WebAR en otra pestaña o en el celular.
Si el tag está bien instalado, deberías ver actividad después de unos segundos.
Cuando agreguemos eventos personalizados, también podrás ver eventos como target_found y cta_click.

Si no ves datos, revisa que el ID en el script sea exactamente el mismo ID que aparece en el flujo web.

Qué NO debes hacer

No envíes nombres, correos ni teléfonos a GA4. Para medir formularios usaremos banderas como has_email: true, pero no el email real. Esto mantiene la analítica más limpia y más segura.

Referencia oficial: Google: encontrar el Google tag y el ID.

Ya instalé GA4 en el head

Paso 7

Crear analytics.js para no repetir código

Podríamos llamar a gtag("event", ...) directamente en todo el proyecto, pero eso haría el código desordenado. Es mejor crear un archivo llamado analytics.js con una función propia: trackEvent. Así todos los eventos pasan por el mismo lugar.

Crea un archivo nuevo en la raíz del proyecto llamado analytics.js. Luego pega este código. Al final deberás cargarlo en index.html antes de app.js, porque app.js usará la función trackEvent.

Función base de analíticaanalytics.js

const MEASUREMENT_ID = "G-XXXXXXXXXX";

function trackEvent(eventName, params = {}) {
  if (typeof gtag !== "function") return;
  gtag("event", eventName, {
    course: "ga4_webar",
    experience: "mindar_image_tracking",
    ...params
  });
}

window.trackEvent = trackEvent;

Explicación línea por línea

Línea 1: guarda el Measurement ID como referencia visible para el proyecto.
Línea 3: crea una función llamada trackEvent. Recibe el nombre del evento y parámetros opcionales.
Línea 4: revisa si gtag existe. Si GA4 no cargó, evita un error que pueda romper la experiencia.
Línea 5: envía un evento a GA4.
Línea 6: agrega el nombre del curso como parámetro común.
Línea 7: indica que la experiencia usa image tracking de MindAR.
Línea 8: mezcla los parámetros específicos de cada evento, como target_index o cta_url.
Línea 12: hace que trackEvent esté disponible para otros archivos JavaScript.

Ya creé analytics.js

Paso 8

Crear app.js y conectar MindAR con GA4

Ahora sí unimos las dos partes: la experiencia AR y la analítica. MindAR emite eventos cuando encuentra o pierde el marcador. Nosotros escuchamos esos eventos con JavaScript y enviamos datos a GA4 usando trackEvent.

Crea un archivo llamado app.js. Este archivo debe cargarse después de analytics.js, porque necesita usar la función trackEvent.

Eventos básicos WebARapp.js

const target = document.querySelector("#target");
const statusText = document.querySelector("#status");
const cta = document.querySelector("#cta");

trackEvent("webar_page_open");

target.addEventListener("targetFound", () => {
  statusText.textContent = "Marcador detectado.";
  trackEvent("target_found", {
    target_index: 0,
    target_name: "analitica"
  });
});

target.addEventListener("targetLost", () => {
  statusText.textContent = "Marcador perdido. Vuelve a apuntar.";
  trackEvent("target_lost", {
    target_index: 0,
    target_name: "analitica"
  });
});

cta.addEventListener("click", () => {
  trackEvent("cta_click", {
    cta_label: cta.textContent.trim(),
    cta_url: cta.href
  });
});

Explicación línea por línea

Línea 1: busca el elemento con id="target". Ese elemento es el marcador AR.
Línea 2: busca el texto de estado para cambiarlo cuando ocurra algo.
Línea 3: busca el botón que vamos a medir como CTA.
Línea 5: envía el evento webar_page_open cuando se abre la experiencia.
Línea 7: escucha el evento targetFound de MindAR.
Línea 8: cambia el texto visible para confirmar detección.
Línea 9: envía target_found a GA4.
Líneas 10 y 11: agregan información del marcador detectado.
Línea 15: escucha cuando MindAR pierde el target.
Línea 17: envía target_lost a GA4.
Línea 23: escucha el clic del botón.
Línea 24: envía cta_click a GA4.
Líneas 25 y 26: registran texto y URL del botón.

Cargar los dos JS al final del HTMLindex.html

<script src="analytics.js"></script>
<script src="app.js"></script>

Estos scripts van justo antes de cerrar </body>. Primero se carga analytics.js, luego app.js. El orden importa.

Ya conecté MindAR con GA4

Paso 9

Template final y prueba en GA4

Ya tienes una experiencia WebAR básica y medible. Para confirmar que todo funciona, abre GA4 y entra en Realtime. Luego abre tu experiencia, escanea el marcador y haz clic en el CTA. Deberías ver eventos como webar_page_open, target_found, target_lost y cta_click.

Checklist final

El archivo index.html abre con Live Server o HTTPS.
El archivo targets/analitica.mind existe y tiene ese nombre exacto.
El Measurement ID reemplazó a G-XXXXXXXXXX.
analytics.js carga antes que app.js.
La cámara abre y MindAR detecta el target.
GA4 Realtime muestra eventos.

Template GA4 básico

Incluye experiencia MindAR, GA4, eventos base y comentarios dentro del código para estudiar cada parte.

Descargar template básico

Terminé el nivel básico de GA4

Ingresa tu código de estudiante

Mapa del proyecto: primero WebAR, después analítica

Qué vas a crear

Orden correcto

Archivos finales

Crear el archivo HTML desde cero

Explicación línea por línea

Prueba rápida

Conceptos básicos antes de usar MindAR

Términos importantes

Buena imagen target

Elegir imagen, compilar target y generar .mind

Agregar A-Frame y MindAR al HTML

Explicación línea por línea

Crear la primera escena WebAR sin GA4

Explicación línea por línea

Antes de continuar

Si la cámara se ve a media pantalla

Qué es Google Analytics 4 y qué vamos a medir

Conceptos de GA4

Eventos básicos del curso

Dónde encontrar GA4

Cómo crear la propiedad GA4

Crear el flujo web

Qué dato necesitas copiar

Instalar el script de GA4 dentro del HTML

Ruta dentro de GA4 para encontrar el tag

Explicación línea por línea

Cómo verificar si funciona

Qué NO debes hacer

Crear analytics.js para no repetir código

Explicación línea por línea

Crear app.js y conectar MindAR con GA4

Explicación línea por línea

Template final y prueba en GA4

Checklist final

Template GA4 básico