Event logger (UI click analytics)
This module records interface click and interaction events and exposes aggregated rankings per company. It is designed so the frontend (the [appTrackEvent] directive), the landing page and the browser SDK (eventLogger.saveEvent) can send telemetry without slowing the UX, and so Owner/Admin can see which buttons, components and pages are used the most.
Saving an event
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"
}- Always answers 204 (no body), whether the event was persisted or discarded.
projectIdis mandatory for persistence. The event's tenant is the owner of that project ID, not the session's company. Anonymous visitors (no JWT) can also send events when the ID is valid and active.- If
projectIdis missing, unknown, revoked or longer than 64 characters → silent discard (204). Same for emptybutton/componentName. Undeclared body fields are ignored (also 204; the endpoint never answers 400 because of extras or an over-longprojectId). - The identity of the user who clicked is not stored.
- Page/route field:
pageis preferred. The aliasespath,urlandrouteare also accepted. timestampis optional (the time reported by the client, only for row auditing). If it is missing, invalid or in the future, the server replaces it with the current time. Rankings do not use this field: they filter by the server'screatedAt.
Reading statistics (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 <owner-or-admin-token>json
{
"topButtons": [
{
"button": "Close_Document",
"componentName": "DocumentViewerComponent",
"count": 42
}
],
"topPages": [{ "page": "/documents/viewer", "count": 17 }]
}- OWNER or ADMIN of the active company only (or a platform super admin acting in a tenant). MEMBER → 403. No token → 401.
- With a normal API key: requires the
event-logger:readoperation. There is noanalytics:*operation — the catalogue uses theevent-loggerarea for all of/event-logger/*. - It aggregates events from all of that company's project IDs (active, and revoked ones with history). Never from other companies.
startDate/endDate(ISO-8601) filter by the server'screatedAt(not thetimestampthe client sends); both are optional. With no range, every event still retained is considered.limitoptional (default 10, maximum 50).- A company with no events, or a range with no data → empty rankings (
[]), not an error.
Project IDs (measurement IDs)
Owner/Admin manage opaque per-company identifiers to instrument products through the SDK or landing page.
http
POST /event-logger/project-ids
Authorization: Bearer <owner-or-admin-token>
Content-Type: application/json
{ "name": "Public landing" }json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"projectId": "ap_a1b2c3d4e5f6789012345678abcdef01",
"name": "Public landing",
"status": "active",
"revokedAt": null,
"createdAt": "2026-09-08T20:00:00.000Z"
}http
GET /event-logger/project-ids
Authorization: Bearer <owner-or-admin-token>http
POST /event-logger/project-ids/:id/revoke
Authorization: Bearer <owner-or-admin-token>- OWNER / ADMIN of the active company only (same gate as stats).
projectIdis the value to copy into instrumentation;:idin revoke is the UUID.- Listing covers the active company only; never other companies.
- Revoking sets
status: revoked(soft). New events with that ID are silently discarded; the history still feeds the stats aggregate.
Retention
Raw events are kept for 90 days from creation and then purged automatically (a daily in-process job when the module starts). There is no aggregated rollup in this iteration: purging loses the raw history.
Related
- Admin Analytics dashboard (frontend) and landing instrumentation: later tasks. SDK
saveEventwithprojectId.