Skip to content
Nuxie
Esc
↑↓navigate↵open⌘Jpreview
On this page

System Events

Reference for all $ prefixed system events

Nuxie uses $-prefixed system events for internal tracking. These events are sent automatically by the SDK or generated by the platform. You can use them in segment conditions, experience triggers, and analytics queries.

Convention

  • System events start with $ (e.g., $app_opened).
  • Custom events use any name without a $ prefix (e.g., signup_completed).
  • System events are excluded from the event catalog by default. Only $identify and $feature_used are auto-cataloged.

App lifecycle events

Sent automatically by the SDK when your app transitions between states.

Event When it fires Properties
$app_installed First launch after install None
$app_updated First launch after an app version change None
$app_opened Every time the app enters the foreground (including first launch) None
$app_backgrounded App transitions to the background None

The SDK tracks install and update status using locally persisted flags. $app_opened fires on every foreground transition, including the launch that triggers $app_installed or $app_updated.

Identity events

Sent when you call identity methods on the SDK or API.

Event When it fires Key properties
$identify User identity is established or merged distinct_id, $anon_distinct_id (optional), $set, $set_once
$create_alias Two known identities are linked distinct_id, alias

$identify

Use $identify to associate an anonymous user with a known identity. If $anon_distinct_id is provided and maps to a different user, Nuxie merges the two profiles automatically.

NuxieSDK.shared.identify("user-456", properties: [
    "$set": ["email": "user@example.com"]
])

$create_alias

Links two known external identifiers to the same user. Provide the alias as a property:

{
  "event": "$create_alias",
  "distinct_id": "user-456",
  "properties": {
    "alias": "legacy-id-789"
  }
}

Journey events

The SDK sends five canonical facts as an experience run progresses. These facts are processed synchronously so the server can reject stale transitions and return authoritative conversion facts.

Event When it fires Key properties
$journey_enrolled A device or server enrolls a run journey_id, experience_id, experience_version, trigger_ref, plane, settings_snapshot
$journey_transition The run advances to another node journey_id, epoch, from_node (optional), to_node, region, plane
$journey_milestone A named milestone is reached journey_id, milestone_id
$journey_converted The device reports or the server confirms conversion journey_id, at, source_fact_ref
$journey_exited The run reaches a terminal state journey_id, reason, at

Enrollment and transitions

$journey_enrolled freezes the experience version and goal settings for the run. Each $journey_transition carries a monotonic epoch; a stale epoch is recorded for diagnostics but cannot move the authoritative current node.

Milestones and conversion

$journey_milestone records explicit progress without ending the run. The server evaluates the pinned goal against all eligible facts and is the conversion authority. A device may report $journey_converted immediately, but the server independently folds the goal and returns the authoritative conversion fact through event or profile responses.

Exit

$journey_exited records a terminal reason such as completed, converted_exit, time_limit, cancelled, or error. Conversion and exit are separate facts; a converted run does not have to exit immediately.

Experience presentation events

Sent during experience presentation, purchase, and artifact loading.

Event When it fires Key properties
$experience_shown An experience is presented experience_id, experience_version, journey_id
$experience_dismissed The user dismisses an experience experience_id, experience_version, journey_id
$experience_purchased A purchase completes from an experience experience_id, experience_version, journey_id
$experience_timed_out Presentation exceeds its time limit experience_id, experience_version, journey_id
$experience_errored Presentation fails experience_id, experience_version, journey_id
$experience_artifact_load_succeeded The version artifact loads experience_id, experience_version, journey_id
$experience_artifact_load_failed The version artifact fails to load experience_id, experience_version, journey_id
$screen_shown A screen within an experience is displayed screen_id
$screen_dismissed A screen is dismissed screen_id, method (optional)

Experience start is configured by the global interaction trigger start (not by a system event name).

$screen_shown and $screen_dismissed

These events fire for each screen transition within an experience. Use them in experience interactions to trigger actions when specific screens appear or are dismissed.

Purchase events

Sent during StoreKit purchase and restore flows.

Event When it fires Key properties
$purchase_completed A purchase transaction succeeds Product-specific properties
$purchase_failed A purchase transaction fails Error details
$purchase_cancelled The user cancels a purchase Product-specific properties
$purchase_synced A verified transaction is synced to the server Transaction details
$restore_completed A restore operation succeeds Restored transaction details
$restore_failed A restore operation fails Error details
$restore_no_purchases A restore finds no previous purchases None

$purchase_completed

Fired after a successful StoreKit purchase. The SDK sends this event before syncing the transaction with the server.

$purchase_synced

Fired after the SDK successfully syncs a verified StoreKit transaction with the Nuxie backend via POST /purchase. This confirms the backend has processed the transaction and updated entitlements.

Feature events

Event When it fires Key properties
$feature_used A metered feature is consumed feature_extId, amount (optional), entityId (optional)
$entitlement_granted An entitlement is granted to a user featureId, balance, unlimited

$feature_used

Decrements the user’s balance for a metered feature. The amount defaults to 1 if not specified. If the user does not have sufficient balance, the server returns a 402 error.

NuxieSDK.shared.useFeature("ai_credits", amount: 5)

$entitlement_granted

Fired when an entitlement is granted through a purchase, subscription renewal, or manual assignment. Updates the user’s feature access at the edge.

Experiment events

Event When it fires Key properties
$experiment_exposure A user is exposed to an experiment variant experiment_key, variant_key, experiment_id, experience_id, experience_version

$experiment_exposure

Fired when a user sees an experience associated with an experiment. This event is the basis for experiment metrics (per-variant impressions and conversions). Invalid exposure events are silently dropped by the server.

Session properties

The SDK attaches a $session_id property to every event. Sessions are managed automatically – a new session starts when the app returns to the foreground after an inactivity period.

You do not need to manage sessions manually. The $session_id property is available for segment conditions and analytics queries.

Using system events in segments

System events work in segment conditions just like custom events. For example, you can create a segment for “users who opened the app in the last 7 days” using:

  • Event condition: $app_opened
  • Time window: last 7 days
  • Count: at least 1

See Segment Builder for details on building conditions with events.

Next steps

Last updated on July 28, 2026

Was this page helpful?