Lifecycle & Profile Sync
Understand profile updates and SDK behavior across app lifecycle changes.
The SDK keeps published content and customer access up to date as people use your app. It refreshes the profile at launch, on foreground return, and when the customer changes, while preserving queued events and in-progress Journeys between sessions.
Setup and shutdown
NuxieSDK.shared is the process-wide SDK instance. Call setup(with:) once during app launch. isSetup reports whether a session is running, and version returns the SDK version for diagnostics.
Await shutdown() when ending that session or before setting up with a different app key or service environment. It stops lifecycle observation and background work, waits for active operations, and closes SDK resources. Ordinary screen navigation and background transitions do not require shutdown.
Shutdown is not sign-out. Use reset() to clear the signed-in customer.
Profile refresh
The profile contains customer properties, feature access, and the published Journeys the SDK can run.
Synchronization points
- Setup: load cached state, then check for updates.
- Foreground: check for updates once per foreground transition.
- Customer change: restore that customer’s cached state and request an updated profile after
identify()orreset()changes the ID.
The SDK reuses the existing profile when the server reports that nothing changed. Calling identify() again with the same ID does not force a refresh.
setLocaleIdentifier(_:) fetches the new locale’s profile at once, and events sent meanwhile wait for it. There is no periodic timer or manual profile refresh method.
What a profile update triggers
The SDK updates customer properties, segment membership, experiment assignments, eligible Journeys, and feature access. SwiftUI feature observers receive the changed state.
Journeys already in progress keep their published version when a new version arrives.
App lifecycle
Entering the background
Event batching and in-memory Journey timers pause. Captured events and active Journey state remain stored.
Returning to the foreground
Queued events resume delivery, the profile synchronizes, and waiting Journey work and timers resume using the updated state.
Default lifecycle plugin
The SDK automatically records:
| Event | When |
|---|---|
$app_installed |
First launch. |
$app_updated |
Launch after an app version change. |
$app_opened |
App launch or foreground return. |
$app_backgrounded |
Background transition. |
Use these events as Experience triggers. beforeSend can filter them before delivery and triggering.
Handle errors
setup(with:) throws NuxieError.invalidConfiguration for invalid configuration. Async feature queries, usage commands, and runtime setters can throw NuxieError.notConfigured when setup has not completed, as well as errors from the requested operation.
Catch errors from async methods in the calling task. Keep loading, denied access, and a failed request as separate UI states. Purchase and restore methods use their typed outcome values for cancellation, pending approval, and failure.
trigger(), identify(), reset(), and useFeature() do not return asynchronous completion results. Diagnose failures through SDK logging and observe access or activity when the app needs the resulting state. For a usage decision, prefer useFeatureAndWait() or consumeFeature().
A usage request can throw CancellationError if the customer changes before the command is accepted. A later timeout does not establish that an accepted server operation was reversed. Use the original operation ID when retrying explicit consumption.
See Tracking events for custom app events and Segments for targeting updates.