Lifecycle & Profile Sync

Journey profile synchronization and app lifecycle hooks

The SDK conditionally synchronizes the Journey profile at explicit lifecycle boundaries and coordinates event delivery, parked Journey work, and feature access as the app moves between foreground and background.

Profile refresh

The profile carries current facts, eligible Journey arms, authenticated release envelopes, delivery locations, and feature access.

Synchronization points

The SDK loads and reauthenticates the cached profile before using it, then performs a conditional network synchronization at two points:

• On setup – after cached state is available.
• On foreground – once for each foreground transition.

Identity changes switch to that identity’s cached profile and local facts. They do not trigger an extra network request. There is no public manual refresh API and no periodic profile timer.

setLocaleIdentifier(_:) updates local settings and invalidates an in-flight fetch under the old locale. Locale-specific content is fetched at the next launch or foreground synchronization.

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.
• Facts – server-owned properties, memberships, and experiment assignments replace the synchronized snapshot.
• Journeys – eligible arms and signed releases replace active catalog authority after exact authentication.
• Features – the SwiftUI FeatureInfo observable is refreshed with the latest access data.
• Active Journeys – continuing work keeps its exact pinned signed release even when the active catalog advances.

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 Journeys and their exact release authority remain persisted.
3. In-memory Journey timers are suspended.

Returning to the foreground

When the app becomes active:

1. Event batching resumes and pending events flush.
2. The profile is conditionally synchronized.
3. Feature access is synced to the SwiftUI observable.
4. Parked Journey work is recovered against fresh facts, and due timers resume.

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 experience triggers.

Next steps

• Tracking Events – events capture the current identity automatically
• Segments – profile updates refresh server-calculated membership facts
• Configuration – configure setup, logging, and purchase ownership