Tracking Events

Send events from your app to power segments, experiences, and analytics

Events are the foundation of Nuxie’s targeting and analytics. Track user actions to trigger experiences, build segments, and measure performance.

The trigger method

Use trigger() to capture an event for delivery and ordered Journey evaluation. The call returns immediately; Journey matching and presentation are owned by the SDK.

NuxieSDK.shared.trigger("item_added_to_cart", properties: [
    "item_id": "sku_999",
    "price": 29.99
])

Method signature

public func trigger(
    _ event: String,
    properties: [String: Any]? = nil
)

Parameter	Description
`event`	The event name. Use a descriptive string like `"checkout_started"`. System events use a `$` prefix.
`properties`	Key-value pairs attached to this specific event.

Use identify() when the same call needs to update profile properties. Trigger results are intentionally not returned to application code: the SDK recovers from assignment problems, selects an authored experiment fallback when needed, and presents the resulting Journey without turning configuration details into an app-facing decision API.

Event properties

Attach structured data to any event:

NuxieSDK.shared.trigger("purchase_started", properties: [
    "product_id": "com.app.premium",
    "price": 9.99,
    "currency": "USD",
    "source": "settings_screen"
])

Properties are stored locally and delivered to the server in batches. They are available to analytics and server-side targeting; authenticated Journey releases may also read the compiler-pruned facts delivered in the profile.

System events

The SDK automatically tracks system events prefixed with $. These events are used internally for Journey execution, server-side segment evaluation, and analytics.

Event	When tracked	Description
`$app_installed`	First launch	The app launched for the first time on this device.
`$app_updated`	Launch after version change	The app launched with a different version than the previous session.
`$app_opened`	Every launch	The app opened, including first launch, updates, and foreground returns.
`$app_backgrounded`	App enters background	The app moved to the background.
`$identify`	`identify()` called	A user identity was linked. Includes `distinct_id` and `$anon_distinct_id`.
`$journey_leg_started`	Journey execution starts	A locally assigned Journey section began; a new binding also creates its Journey.
`$journey_leg_completed`	Journey execution finishes	A locally assigned Journey section reported its outcome and declared outputs.
`$journey_milestone`	Milestone action runs	The run recorded a named milestone.
`$experience_shown`	Experience presented	An experience was displayed to the user.
`$experience_dismissed`	Experience dismissed	The user dismissed an experience.
`$experience_errored`	Experience failed	Presentation failed.
`$experience_artifact_load_succeeded`	Artifact loaded	The experience version artifact loaded.
`$experience_artifact_load_failed`	Artifact load failed	The experience version artifact failed to load.
`$purchase_completed`	Purchase succeeds	A StoreKit purchase completed, including Experience context when applicable.
`$purchase_synced`	Transaction synced	A transaction was verified and synced to the server.
`$restore_completed`	Restore succeeds	A purchase restore completed.
`$feature_used`	`useFeature()` called	Feature usage was reported.

Tip: Name your custom events without the $ prefix. The $ prefix is reserved for SDK system events.

How events are processed

When you call trigger(), the event flows through these stages:

Snapshot – the current distinct ID is captured at call time.
Enrich – device context (OS version, app version, device model) is attached.
Sanitize – data types are normalized and any configured sanitizer is applied.
Store – the event is persisted locally for reliable delivery and bounded history.
Route – the event is forwarded to the experience engine for trigger matching.
Deliver – the event is added to the network queue for batch delivery to the server.

If a beforeSend hook is configured, it runs between step 3 and step 4. Returning nil from beforeSend drops the event entirely.

Batching and delivery

The SDK owns reliable event delivery. It batches pending analytics, retries temporary failures, resumes delivery on foreground, and preserves captured events across process restarts. Queue tuning and manual flush controls are not part of the public SDK API.

Storage limits

Events are stored locally for reliable delivery and bounded Journey history:

Maximum stored events: 10,000
Retention period: 30 days

Events beyond these limits are automatically cleaned up. Network delivery is handled separately through the in-memory batch queue.

Next steps

Presenting Experiences – learn how events trigger experiences
Segments – see how the server turns events into membership facts
Privacy & Logging – configure sanitizers and the beforeSend hook