Demo de session replay

Aplicación de demo interactiva que muestra cómo instrumentar una aplicación web para session replay en ClickStack

En resumen

Esta guía explica cómo instrumentar una aplicación web para session replay con el SDK para navegador de ClickStack. A diferencia de otros conjuntos de datos de ejemplo que cargan datos pregenerados, esta demostración ofrece una aplicación interactiva en la que generas datos de sesión mediante tus propias interacciones.

Tiempo requerido: 10-15 minutos

​

Descripción general

La aplicación de demostración de session replay es un explorador de documentación creado con JavaScript puro. Demuestra lo mínima que puede ser la instrumentación de session replay: una etiqueta <script> y una llamada de inicialización capturan automáticamente todas las interacciones del usuario.

El repositorio incluye dos ramas:

• main — totalmente instrumentada y lista para usar de inmediato
• pre-instrumented — una versión limpia sin instrumentación, con comentarios en el código que indican dónde añadirla

Esta guía usa primero la rama main para ver session replay en acción y luego recorre el código de instrumentación para que puedas aplicar el mismo patrón en tu propia aplicación.

Para obtener más contexto sobre qué es Session Replay y cómo encaja en ClickStack, consulta la página de la funcionalidad Session Replay.

​

Requisitos previos

• Docker y Docker Compose instalados
• Puertos 3000, 4317, 4318 y 8080 disponibles

​

Ejecutar la demo

1. ​

   Clonar el repositorio

   git clone https://github.com/ClickHouse/clickstack-session-replay-demo
   cd clickstack-session-replay-demo
   
2. ​

   Iniciar ClickStack

   docker-compose up -d clickstack
   
3. ​

   Obtener tu API key

   1. Abre HyperDX en http://localhost:8080
   2. Crea una cuenta o inicia sesión si es necesario
   3. Ve a Team Settings → API Keys
   4. Copia tu API key de ingesta

   5. Defínela como una variable de entorno:

   export CLICKSTACK_API_KEY='your-api-key-here'
   
4. ​

   Iniciar la aplicación de demostración

   docker-compose --profile demo up demo-app
   

   Asegúrate de ejecutar este comando en la misma terminal en la que exportaste la variable CLICKSTACK_API_KEY.

   Abre http://localhost:3000 en tu navegador e interactúa con la aplicación: busca temas, filtra por categoría, consulta ejemplos de código y guarda elementos en favoritos.

   Todas las interacciones se capturan automáticamente con el SDK para navegador de ClickStack.

5. ​

   Ver tu session replay

   Vuelve a HyperDX en http://localhost:8080 y ve a Client Sessions en la barra lateral izquierda.

   Deberías ver tu sesión en la lista con su duración y número de eventos. Haz clic en el botón ▶️ para reproducirla.

   Cambia entre los modos Highlighted y All Events para ajustar el nivel de detalle en la línea de tiempo.

​

La instrumentación

La aplicación de demostración muestra la poca cantidad de código que se necesita para habilitar session replay. Solo hacen falta dos incorporaciones a la aplicación:

1. Incluye el SDK (app/public/index.html):

<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>

2. Inicializa ClickStack (app/public/js/app.js):

window.HyperDX.init({
  url: 'http://localhost:4318',
  apiKey: window.CLICKSTACK_API_KEY,
  service: 'clickhouse-session-replay-demo',
  consoleCapture: true,
  advancedNetworkCapture: true,
});

Todo lo demás es código estándar de la aplicación. El SDK captura automáticamente todas las interacciones del usuario, los logs de la consola, las peticiones de red y los errores; no se necesita instrumentación adicional.

​

Pruébalo tú mismo

Para instrumentar la aplicación desde cero, cambia a la rama pre-instrumented:

git checkout pre-instrumented

Esta rama contiene la misma aplicación, pero sin ninguna instrumentación de ClickStack. Los comentarios del código en app/public/index.html y app/public/js/app.js indican exactamente dónde agregar los dos fragmentos de código anteriores. Una vez añadidos, reinicia la app de demostración y tus interacciones empezarán a aparecer en ClickStack.

​

Solución de problemas

​

Las sesiones no aparecen en HyperDX

1. Revisa si hay errores en la consola del navegador
2. Verifica que ClickStack esté en ejecución: docker-compose ps
3. Confirma que la API key esté configurada: echo $CLICKSTACK_API_KEY
4. Ajusta el intervalo de tiempo en la vista Client Sessions (prueba con Last 15 minutes)
5. Fuerza la recarga del navegador: Cmd+Shift+R (Mac) o Ctrl+Shift+R (Windows/Linux)

​

Errores 401 Unauthorized

La API key no está configurada correctamente. Asegúrate de que:

1. La hayas exportado en tu terminal: export CLICKSTACK_API_KEY='your-key'
2. Hayas iniciado la aplicación de demo en la misma terminal donde la exportaste
3. Hayas obtenido la clave desde la UI de HyperDX (no una cadena generada aleatoriamente)

​

Limpieza

Detén los servicios:

docker-compose down

Elimine todos los datos:

docker-compose down -v

​

Más información

• Session Replay — descripción general de la funcionalidad, opciones de SDK y controles de privacidad
• Referencia del SDK para navegador — opciones completas del SDK y configuración avanzada
• Primeros pasos con ClickStack — despliegue ClickStack e ingeste sus primeros datos
• Todos los conjuntos de datos de ejemplo — otros conjuntos de datos de ejemplo y guías