Skip to content

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.
  • projectId is 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 projectId is missing, unknown, revoked or longer than 64 characters → silent discard (204). Same for empty button / componentName. Undeclared body fields are ignored (also 204; the endpoint never answers 400 because of extras or an over-long projectId).
  • The identity of the user who clicked is not stored.
  • Page/route field: page is preferred. The aliases path, url and route are also accepted.
  • timestamp is 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's createdAt.

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:read operation. There is no analytics:* operation — the catalogue uses the event-logger area 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's createdAt (not the timestamp the client sends); both are optional. With no range, every event still retained is considered.
  • limit optional (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).
  • projectId is the value to copy into instrumentation; :id in 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.

  • Admin Analytics dashboard (frontend) and landing instrumentation: later tasks. SDK saveEvent with projectId.