Skip to content

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ó.
  • projectId es 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 para button / componentName vacíos. Campos no declarados en el body se ignoran (también 204; el endpoint no responde 400 por extras o projectId demasiado largo).
  • No se guarda la identidad del usuario que hizo el click.
  • Campo de página/ruta: preferido page. También se aceptan alias path, url y route.
  • timestamp es 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 por createdAt del 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ón analytics:* — el catálogo usa el área event-logger para 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 el createdAt del servidor (no el timestamp que envía el cliente); son opcionales. Sin rango se consideran todos los eventos aún retenidos.
  • limit opcional (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).
  • projectId es el valor a copiar en instrumentación; :id en 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 saveEvent con projectId.