Tracking Events

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

Tracking Events

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

The trigger method

Use trigger() to send an event. It works as a fire-and-forget call, but also returns a TriggerHandle you can observe for campaign decisions and entitlement updates.

swift

// Fire-and-forget
NuxieSDK.shared.trigger("item_added_to_cart", properties: [
    "item_id": "sku_999",
    "price": 29.99
])

Method signature

swift

@discardableResult
public func trigger(
    _ event: String,
    properties: [String: Any]? = nil,
    userProperties: [String: Any]? = nil,
    userPropertiesSetOnce: [String: Any]? = nil,
    handler: ((TriggerUpdate) -> Void)? = nil
) -> TriggerHandle

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.
`userProperties`	Properties to set on the user profile (mapped to `$set`).
`userPropertiesSetOnce`	Properties to set only if not already present (mapped to `$set_once`).
`handler`	An optional callback that receives progressive `TriggerUpdate` values as the event is processed.

Observing trigger outcomes

The returned TriggerHandle conforms to AsyncSequence and delivers TriggerUpdate values:

swift

let handle = NuxieSDK.shared.trigger("paywall_trigger")
 
for await update in handle {
    switch update {
    case .decision(let decision):
        print("Decision: \(decision)")
    case .entitlement(let entitlement):
        print("Entitlement: \(entitlement)")
    case .journey(let journey):
        print("Journey: \(journey)")
    case .error(let error):
        print("Error: \(error)")
    }
}

You can also use the callback parameter for the same updates:

swift

NuxieSDK.shared.trigger("paywall_trigger") { update in
    // Called on the main thread
    switch update {
    case .decision(.flowShown):
        print("Flow is now visible")
    default:
        break
    }
}

Event properties

Attach structured data to any event:

swift

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 in segments, campaign conditions, and analytics.

System events

The SDK automatically tracks system events prefixed with $. These events are used internally for campaign triggers, 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_start`	Campaign triggers	A campaign journey started for the user.
`$journey_completed`	Journey finishes	A campaign journey completed (goal met, expired, or cancelled).
`$flow_shown`	Flow presented	A flow was displayed to the user.
`$purchase_completed`	Purchase succeeds	A StoreKit purchase completed.
`$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 and session ID are 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 to a local database for segment evaluation and history.
Route -- the event is forwarded to the campaign 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

Events are delivered to the server in batches for efficiency:

The queue flushes automatically when it reaches the flushAt threshold (default: 20 events).
A periodic timer flushes remaining events every flushInterval seconds (default: 30).
When the app enters the foreground, the queue flushes immediately.
When the app enters the background, automatic flushing pauses.

To flush manually:

swift

await NuxieSDK.shared.flushEvents()

Storage limits

Events are stored locally in a database for segment evaluation and campaign matching:

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 Flows -- learn how events trigger campaign flows
Segments -- see how event history feeds segment evaluation
Privacy & Logging -- configure sanitizers and the beforeSend hook