Sessions & Lifecycle

Session management, profile refresh, and app lifecycle hooks

Sessions & Lifecycle

The SDK manages sessions automatically and refreshes the user profile to keep campaigns, segments, and features current. You can also control sessions manually and hook into the app lifecycle.

Sessions

A session groups events and activity into a single usage period. The SDK creates, rotates, and attaches session IDs to events automatically.

Automatic rotation

Sessions rotate based on two rules:

When the app returns to the foreground after the inactivity timeout has passed, the SDK starts a new session. If a session has been active for more than 24 hours, it rotates on the next event.

Sessions are not persisted across app restarts. Each cold start creates a new session on the first event.

Manual session control

// Start a new session immediately
NuxieSDK.shared.startNewSession()
 
// End the current session
NuxieSDK.shared.endSession()
 
// Reset the session (clear and start new)
NuxieSDK.shared.resetSession()
 
// Get the current session ID (nil if no session exists)
let sessionId = NuxieSDK.shared.getCurrentSessionId()
 
// Set a custom session ID
NuxieSDK.shared.setSessionId("custom-session-id")

Sessions and identity

• Calling identify() starts a new session.
• Calling reset() resets the session.

This ensures each identity has a clean session boundary.

Profile refresh

The profile is the SDK's primary configuration payload. It contains campaigns, segment definitions, flow references, feature access, experiment assignments, and user properties.

Caching strategy

The SDK uses a tiered cache with these freshness windows:

On a cold start, the SDK loads the profile from disk cache first. If the disk cache is stale, a background refresh runs automatically.

Refreshing the profile

The profile refreshes automatically at these points:

• On setup -- the SDK fetches an initial profile in the background.
• On foreground -- if the cached profile is older than 15 minutes, a background refresh starts.
• On identify -- the SDK loads the new user's cached profile (if available) and triggers a background refresh.

To force a refresh manually:

let profile = try await NuxieSDK.shared.refreshProfile()

Tip: Call refreshProfile() after changing configuration.localeIdentifier to fetch locale-specific content.

What a profile update triggers

When the SDK receives a fresh profile, it fans the update out to all subsystems:

• User properties -- server-provided properties are merged into the local property store.
• Segments -- segment definitions are updated and an evaluation cycle runs immediately.
• Flows -- new or updated flows are prefetched; removed flows are cleared from cache.
• Features -- the SwiftUI FeatureInfo observable is refreshed with the latest access data.
• Campaigns -- active campaign journeys are checked for cross-device resume.

App lifecycle

The SDK listens for iOS app lifecycle notifications and coordinates its subsystems:

Entering the background

When the app enters the background:

1. Event batching pauses.
2. Active campaign journeys are persisted to disk.
3. Scheduled campaign timers are cancelled.

Returning to the foreground

When the app becomes active:

1. The session is checked for rotation (inactivity or max length).
2. Event batching resumes and pending events flush.
3. The profile is refreshed if stale (older than 15 minutes).
4. Feature access is synced to the SwiftUI observable.
5. Campaign timers are re-armed.
6. A short grace period prevents flows from appearing immediately.

Default lifecycle plugin

The AppLifecyclePlugin is installed by default and tracks:

• $app_installed -- first launch ever
• $app_updated -- launch after a version change
• $app_opened -- every app open
• $app_backgrounded -- every background transition

These events power built-in analytics and can be used as campaign triggers.

Next steps

• Tracking Events -- events carry the session ID automatically
• Segments -- profile updates refresh segment definitions
• Configuration -- configure event batching and other options