Skip to main content

Product events

The product-events channel records small, structured facts about what users do in the product so the team can observe adoption, funnels, and operational health. This section is the canonical place to learn what the channel collects, how to add a new event, how personally-identifiable information is handled, and where to observe events in production.

Consumer model​

The channel is the surface that the official client SDK uses, not a stable public-API surface for arbitrary external consumers. The ingest endpoint (POST /api/diagnostics/frontend-events) is published in the API reference because it is part of the diagnostics namespace, but it is provisioned for SDK-driven traffic only:

  • Authentication is mandatory; anonymous traffic is rejected.
  • Event names are governed by an allow-list in source control. Names absent from the allow-list are rejected per event, not silently dropped.
  • Rate limits, batch caps, and payload size caps are enforced for abuse resistance, not as part of an external contract.
  • The shape, semantics, and lifetime of events may change without notice to keep pace with product evolution.

If you are an external developer integrating with the platform, treat this section as observable behaviour, not as a stable API contract.

What this section covers​

  • Canonical event registry — every event currently accepted by the backend, with properties, owners, PII annotations, and the date each was added.
  • Adding a new product event — the end-to-end workflow plus a copy-pasteable PR checklist mirroring the same-PR rule that gates the backend allow-list and PII paths files.
  • PII policy — which fields are treated as PII, the deterministic-hash-with-deployment-salt model, the deletion behaviour on user-account removal, and the retention behaviour.
  • Diagnostics self-read invariants — uniform 404 on detail endpoints, no admin widening for frontend-events, and properties payload rendered verbatim on the client. The durable contracts of the self-read diagnostics surface.
  • Dashboards of reference — where accepted events show up in production (default forward destination, backend events table, and the reserved placeholder for a future SaaS analytics destination).

Why this section exists​

The channel was built in three phases under Spine task x-005-product-telemetry-primitive: a backend ingest endpoint, a client primitive (recordProductEvent({ event, properties })), and this docs review that publishes the workflow and policy. The registry, the authoring guide, the PII policy, and the dashboards page are co-published so cross-references resolve and so the next contributor adding an event finds every gate in one place.