---
title: "Lifecycle & Profile Sync"
description: "Understand profile updates and SDK behavior across app lifecycle changes."
search:
  tags: ["sdk", "reference", "ios"]
  keywords: ["Swift", "StoreKit", "Xcode"]
---

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()`](/docs/ios-sdk/identity-and-users#resetting-identity-logout) 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()` or `reset()` 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](/docs/ios-sdk/privacy-and-logging#the-beforesend-hook) 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.

<span id="next-steps" />

See [Tracking events](/docs/ios-sdk/tracking-events) for custom app events and [Segments](/docs/ios-sdk/segments) for targeting updates.