Las anotaciones en gráficos te permiten marcar eventos importantes - despliegues, releases, campañas de marketing, incidentes, hitos personalizados - en cada gráfico temporal de Zenovay. Cuando el tráfico o los ingresos varían, ves al instante qué cambió en ese mismo momento sin salir del panel.
Por qué importan las anotaciones
La mayoría de las preguntas analíticas se reducen a "¿qué cambió?". Una caída inesperada el martes por la tarde es mucho más fácil de investigar cuando ves "deploy: release v2.5" marcado a las 14:32. Las anotaciones convierten el panel en una única línea temporal donde métricas de negocio y eventos operativos conviven.
Los cinco tipos de anotación
| Tipo | Color | Uso típico |
|---|---|---|
deploy | Azul | Despliegues de código, cambios de infraestructura, push de configuración |
release | Esmeralda | Anuncios públicos de release, cortes de versión |
campaign | Ámbar | Campañas de marketing, lanzamientos de anuncios, envío de emails |
incident | Rojo | Incidentes que impactan al cliente, caídas |
custom | Violeta | Cualquier otra cosa - reuniones, integraciones de partners, auditorías |
Cada tipo tiene un icono y un color distintivos para identificar de un vistazo qué cambió.
Tres formas de crear anotaciones
Opción 1 - En el panel
Abre el panel de tu sitio web y selecciona la pestaña Analytics, luego haz clic en el icono de nota en cualquier punto del gráfico de visitantes. Se abre el diálogo de detalles del día con tres pestañas: Notes, Annotations y Commits. En la pestaña Annotations, elige un tipo (deploy, release, campaign, incident o custom), escribe un mensaje y agrégalo. El marcador aparece inmediatamente en el gráfico.
Esta es la forma más rápida de marcar un evento puntual. Para los despliegues que realizas regularmente, el CLI de abajo es más apropiado.
Opción 2 - CLI de Zenovay (recomendada para CI)
La CLI es la vía canónica para marcar despliegues desde un pipeline de CI. Gestiona la autenticación mediante el inicio de sesión de tu cuenta y funciona en macOS, Linux y Windows.
zenovay annotation create --type=deploy --message="release v2.5"
Añádela como último paso de tu pipeline de despliegue para que cada
release se marque automáticamente. El comando se cierra con un código
distintivo en errores de límite de plan (4) o duplicado (5) para
que tu pipeline pueda manejar cada caso. Consulta la
guía de integración del CLI
para todos los flags y un ejemplo de GitHub Actions.
Opción 3 - API REST
También hay un endpoint /api/annotations que el panel utiliza. Se
autentica con tu sesión de panel (el mismo inicio de sesión que usas
en el navegador), así que solo es práctico para un servidor que ya
tiene una sesión válida. Las claves API externas zv_* no se aceptan
en este endpoint actualmente, así que para CI y otros entornos
automatizados, el CLI de arriba es la herramienta correcta: maneja
la autenticación por ti. Consulta la
referencia de la API de Anotaciones en gráficos
para la forma completa de solicitud y respuesta.
Límites del plan y comportamiento
- Gratis: 10 anotaciones por equipo y mes.
- Pro y superior: ilimitado.
Una anotación del mismo type y el mismo mensaje dentro de 5
minutos de una existente se rechaza para evitar que un pipeline mal
configurado inunde la línea temporal con duplicados. Dos anotaciones
del mismo tipo con mensajes diferentes (por ejemplo, "checkout roto"
y luego "checkout arreglado") se permiten ambas.
Dónde aparecen las anotaciones
- Bajo cada gráfico analítico para el cliente como una banda de chips coloreados. Pasa el cursor por encima para ver el mensaje completo y la hora exacta.
- En el panel de triaje de incidentes de conversión como "cambio sospechoso" cuando la anotación cae dentro de ±2 horas del inicio del incidente.
- En la posición del icono de notas heredada del gráfico de visitantes del dominio, si ya usabas la función previa. Ambas superficies se sincronizan automáticamente.
Leyendo la banda de chips
Cada chip bajo un gráfico está codificado por color según su tipo, con el icono a la izquierda. Los cinco colores se mantienen consistentes en todos los gráficos y páginas: una vez aprendidos, puedes escanear la banda de un vistazo. Un grupo azul = despliegues, ámbar = campañas, rojo = incidentes. El chip muestra tu mensaje y la hora de creación; pasa el cursor para ver la marca de tiempo completa.
Privacidad: los paneles públicos NUNCA muestran anotaciones
Si compartes un enlace público con alguien fuera de tu equipo, las anotaciones se ocultan. Los mensajes de despliegue y release están pensados para el equipo que opera el sitio, no para los visitantes. No hay forma de exponer públicamente los mensajes de anotación.
Patrones comunes
Marcar cada despliegue de producción automáticamente: añade el comando del CLI como paso post-despliegue. Cero trabajo manual tras el cableado inicial.
Marcar el lanzamiento de una campaña:
zenovay annotation create --type=campaign --message="Rebajas de primavera"
en el momento del go-live. Cuando revises el lift de tráfico más
tarde, el marcador ya estará en el gráfico.
Marcar un incidente conocido: publica una anotación incidente para que el gráfico explique visiblemente la caída. Combina de forma natural con el triaje de incidentes de conversión.
Solución de problemas
- "Annotation limit reached": límite mensual del plan Gratis alcanzado. Pasa a Pro para tener ilimitado.
- Error HTTP 409 (dedup): intentas publicar una anotación del mismo tipo y el mismo mensaje dentro de 5 minutos de una existente. Espera, cambia el mensaje, o acepta que el primer marcador ya representa el evento. (El CLI retorna el código de salida 5 para este caso.)
- La banda de chips no aparece: confirma que existe al menos una anotación para ese sitio. La banda permanece oculta cuando no hay nada que mostrar.
- El chip está en el idioma o tema incorrecto: el tema sigue el tema del panel; el idioma sigue la configuración regional del navegador. Ambos cambian automáticamente.