Event logger (analytics de clicks de UI)
Este módulo registra eventos de click/interacción de la interfaz y expone rankings agregados por empresa . Está pensado para que el frontend (directiva [appTrackEvent]), la landing y el SDK browser (eventLogger.saveEvent) envíen telemetría sin frenar la UX, y para que Owner/Admin consulten qué botones/componentes y páginas se usan más.
Guardar un evento
http
POST /event-logger/save-event
Content-Type: application/json
{
"projectId": "ap_a1b2c3d4e5f6789012345678abcdef01",
"button": "Close_Document",
"componentName": "DocumentViewerComponent",
"description": "User closed the document viewer",
"timestamp": "2026-09-08T12:00:00.000Z",
"page": "/documents/viewer"
}- Responde siempre 204 (sin cuerpo), tanto si se persistió como si se descartó.
projectIdes obligatorio para persistir. El tenant del evento es el dueño de ese project ID, no la empresa de sesión. Visitantes anónimos (sin JWT) también pueden enviar eventos si el ID es válido y activo.- Si falta el
projectId, es desconocido, está revocado o supera 64 caracteres → descarte silencioso (204). Igual parabutton/componentNamevacíos. Campos no declarados en el body se ignoran (también 204; el endpoint no responde 400 por extras oprojectIddemasiado largo). - No se guarda la identidad del usuario que hizo el click.
- Campo de página/ruta: preferido
page. También se aceptan aliaspath,urlyroute. timestampes opcional (hora reportada por el cliente, solo para auditoría de la fila). Si falta, es inválido o está en el futuro, el servidor lo sustituye por la hora actual. Los rankings no usan este campo: filtran porcreatedAtdel servidor.
Consultar estadísticas (Owner / Admin)
http
GET /event-logger/stats?startDate=2026-08-01T00:00:00.000Z&endDate=2026-09-08T23:59:59.999Z&limit=10
Authorization: Bearer <token-owner-o-admin>json
{
"topButtons": [
{
"button": "Close_Document",
"componentName": "DocumentViewerComponent",
"count": 42
}
],
"topPages": [{ "page": "/documents/viewer", "count": 17 }]
}- Solo OWNER o ADMIN de la empresa activa (o super admin de plataforma actuando en un tenant). MEMBER → 403. Sin token → 401.
- Con API key normal: requiere operación
event-logger:read. No hay operaciónanalytics:*— el catálogo usa el áreaevent-loggerpara todo/event-logger/*. - Agrega eventos de todos los project IDs de esa empresa (activos y revocados con histórico) —. Nunca de otras empresas —.
startDate/endDate(ISO-8601) filtran por elcreatedAtdel servidor (no eltimestampque envía el cliente); son opcionales. Sin rango se consideran todos los eventos aún retenidos.limitopcional (default 10, máximo 50).- Empresa sin eventos o rango sin datos → rankings vacíos (
[]), no error.
Project IDs (measurement IDs)
Owner/Admin gestionan identificadores opacos por empresa para instrumentar productos vía SDK/landing.
http
POST /event-logger/project-ids
Authorization: Bearer <token-owner-o-admin>
Content-Type: application/json
{ "name": "Landing pública" }json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"projectId": "ap_a1b2c3d4e5f6789012345678abcdef01",
"name": "Landing pública",
"status": "active",
"revokedAt": null,
"createdAt": "2026-09-08T20:00:00.000Z"
}http
GET /event-logger/project-ids
Authorization: Bearer <token-owner-o-admin>http
POST /event-logger/project-ids/:id/revoke
Authorization: Bearer <token-owner-o-admin>- Solo OWNER / ADMIN de la empresa activa (mismo gate que stats).
projectIdes el valor a copiar en instrumentación;:iden revoke es el UUID.- Listado solo de la empresa activa; nunca de otras.
- Revocar pone
status: revoked(soft). Nuevos eventos con ese ID se descartan en silencio; el histórico sigue entrando en el agregado de stats.
Retención
Los eventos crudos se conservan 90 días desde su creación y luego se purgan automáticamente (job in-process diario al arrancar el módulo). No hay rollup agregado en esta iteración: al purgar se pierde el histórico crudo.
Relacionado
- Panel admin Analytics (frontend) e instrumentación landing: tareas posteriores. SDK
saveEventconprojectId.