System Events
Himetrica automatically fires system events when meaningful things happen to a visitor. These events are prefixed with $ and can be used in funnels, user flows, and visitor timelines.
Overview
System events are generated server-side when Himetrica detects visitor behavior changes. They use a $ prefix to distinguish them from your custom events. You don't need to configure anything — they fire automatically.
Excluded from aggregate counts
Event List
| Event | When it fires | Repeatable |
|---|---|---|
$identified | Visitor gets a name or email for the first time | Once per visitor |
$engagement_changed | Engagement level changes (e.g. casual → active) | Yes |
$lifecycle_changed | Lifecycle stage changes (e.g. exploring → activated) | Yes |
$churned | Visitor transitions to "churned" lifecycle stage | Yes |
$first_conversion | Visitor fires a conversion event for the first time | Once per visitor |
$returned | Visitor returns after 7+ days of inactivity | Yes |
$identified
Fired when a previously anonymous visitor is identified for the first time — either through the client-side identify() call or the Server API POST /identify endpoint. This event only fires once per visitor.
Properties
| Key | Type | Description |
|---|---|---|
name | string | null | Visitor's name |
email | string | null | Visitor's email |
method | "client" | "server" | Whether identification came from client-side or server API |
$engagement_changed
Fired when a visitor's engagement level changes. Engagement levels are computed based on session frequency, page depth, recency, session duration, and event activity.
Possible levels: new, casual, active, power_user, dormant.
Properties
| Key | Type | Description |
|---|---|---|
from | string | Previous engagement level |
to | string | New engagement level |
score | number | Engagement score (0-100) |
$lifecycle_changed
Fired when a visitor's lifecycle stage changes. Lifecycle stages track where a visitor is in their journey with your product.
Possible stages: exploring, activated, retained, at_risk, churned.
Properties
| Key | Type | Description |
|---|---|---|
from | string | Previous lifecycle stage |
to | string | New lifecycle stage |
$churned
Fired when a visitor transitions to the "churned" lifecycle stage. This is a convenience event — it fires alongside $lifecycle_changed when the new stage is "churned". Useful as a standalone funnel step or conversion event.
By default, a visitor is considered churned after 30 days of inactivity. This threshold can be configured in your project's behavior settings.
Properties
| Key | Type | Description |
|---|---|---|
previousStage | string | The lifecycle stage before churning |
daysSinceLastSeen | number | Days since the visitor was last active |
$first_conversion
Fired when a visitor triggers one of your configured conversion events for the first time. Conversion events are defined in your project settings. This event only fires once per visitor, regardless of how many conversion events they trigger later.
Properties
| Key | Type | Description |
|---|---|---|
eventName | string | The name of the conversion event that was triggered |
$returned
Fired when a visitor comes back to your site after 7 or more days of inactivity. This can fire multiple times for the same visitor if they have multiple periods of inactivity.
Properties
| Key | Type | Description |
|---|---|---|
inactiveDays | number | Number of days the visitor was inactive |
previousLastSeenAt | string (ISO 8601) | When the visitor was last seen before returning |
Filtering & Aggregation
System events are automatically excluded from:
- Total event counts in the dashboard
- Top events ranking
- Event timeseries charts
- Daily rollup aggregations
- Engagement score calculations (events/session ratio)
System events are available in:
- Visitor timeline / event history
- Funnel steps (e.g. "Visited pricing" → "$identified" → "Purchase")
- User flow event filters
- Event detail views