System Events

Reference for all $ prefixed system events

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, campaign 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`
`$merge_dangerously`	Force-merge two existing users	`distinct_id`, `alias` or `$anon_distinct_id`

$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.

swift

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

$create_alias

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

json

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

$merge_dangerously

Force-merges two existing users. Both users must already exist. The source user's properties are merged into the target with "set once" semantics (existing target values are preserved).

Journey events

Sent automatically as users progress through campaign journeys.

Event	When it fires	Key properties
`$journey_start`	A journey session begins	`session_id`, `campaign_id`, `entry_node_id`, `context` (optional)
`$journey_node_executed`	A journey node is processed	`session_id`, `node_id`, `node_data` (optional)
`$journey_completed`	A journey session finishes	`session_id`, `campaign_id`

$journey_start

Fired when a campaign trigger matches and a new journey session begins. If a journey session already exists for the campaign, the existing session is returned instead of creating a new one.

$journey_node_executed

Fired each time a node in the journey graph is executed. The node_data property contains node-specific metadata, including the node type and any associated data.

$journey_completed

Fired when a journey reaches a terminal node or an exit condition is met.

Flow events

Sent during flow presentation and interaction.

Event	When it fires	Key properties
`$flow_entered`	A flow begins rendering	`entry_screen_id`
`$flow_shown`	A flow is presented to the user	`flow_id`, `campaign_id` (optional)
`$screen_shown`	A screen within a flow is displayed	`screen_id`
`$screen_dismissed`	A screen is dismissed	`screen_id`, `method` (optional)

$screen_shown and $screen_dismissed

These events fire for each screen transition within a flow. Use them in campaign 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.

swift

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`

$experiment_exposure

Fired when a user sees a flow 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

REST API -- Endpoint reference for sending events
Webhooks -- App Store webhook events
Tracking Events -- Send custom events from the iOS SDK