---
title: "Configuration"
description: "Initialize the Swift SDK and configure its environment, locale, logging, and purchases."
search:
  tags: ["sdk", "reference", "ios"]
  keywords: ["Swift", "StoreKit", "Xcode", "NuxieConfiguration", "setup", "environment", "apiKey"]
---

Initialize Nuxie once at launch to load your app's published Experiences and customer access. Configure locale, logging, and checkout before the session starts.

## Minimal setup

```swift
// nuxie-doc-snippet: minimal-configuration
import Nuxie

let config = NuxieConfiguration(apiKey: "your_api_key")
try NuxieSDK.shared.setup(with: config)
```

Call setup from your SwiftUI `App` initializer or UIKit app delegate. Copy the public key from **Connect your app**: use `pk_test_` for preview content in Debug and TestFlight builds and `pk_live_` for live content in App Store builds. Nuxie accepts sandbox purchases, including TestFlight's, only with the test key. Both use the default `.production` service environment. See [iOS setup](/docs/sdks/ios#add-your-public-key) for build configuration.

Set options before calling `setup(with:)`. Changes to the original configuration object do not affect a running SDK.

## Configuration options

### Core and network

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `apiKey` | `String` | Required | Publishable key for the selected Nuxie app and environment. |
| `environment` | `Environment` | `.production` | `.production` or `.development`. |

`environment` selects the Nuxie service: `.production` uses `https://i.nuxie.ai`, while `.development` uses `https://dev-i.nuxie.ai`. It is separate from your app's test/live key. Leave it at the default for ordinary integrations, including development builds. The SDK manages batching and retries.

### Logging

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `logLevel` | `LogLevel` | `.warning` | `.verbose`, `.debug`, `.info`, `.warning`, `.error`, or `.none`. |
| `enableConsoleLogging` | `Bool` | `true` | Emit SDK logs to the console. |
| `redactSensitiveData` | `Bool` | `true` | Mask sensitive identifiers and credentials in logs. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `beforeSend` | `(@Sendable (NuxieEvent) -> NuxieEvent?)?` | `nil` | Transform an event or return `nil` to drop it. |

Lifecycle events are captured automatically. Returning `nil` from `beforeSend` drops an event before storage, delivery, and Experience triggering. See [Privacy and logging](/docs/ios-sdk/privacy-and-logging).

### Locale

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `localeIdentifier` | `String?` | `nil` | Initial profile locale; `nil` follows the device locale. |

### Purchases

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `purchaseHandlingMode` | `PurchaseHandlingMode` | `.full` | `.full` makes Nuxie the native StoreKit sync/finish owner; `.observer` leaves finishing to the app or provider. |
| `purchaseDelegate` | `NuxiePurchaseDelegate?` | `nil` | Optional handler for RevenueCat, Superwall, or custom checkout. `nil` uses native StoreKit. |
| `testStoreEnabled` | `Bool` | `false` | Enable the Test Store. Accepted only with a `pk_test_` key in a Debug build. |

Use `.observer` when another SDK or your app finishes StoreKit transactions. Setting a delegate does not change this mode. See [Purchases](/docs/ios-sdk/purchases).

### Test Store

Test Store is a no-charge checkout for Debug builds, like RevenueCat's Test Store. It needs a `pk_test_` key and works on the default service; setup refuses it with a live key or in a Release build, which includes TestFlight and App Store builds. It bypasses StoreKit and your purchase delegate.

```swift
// nuxie-doc-fragment: test-store-debug-builds harness=config-body
#if DEBUG
config.testStoreEnabled = true
#endif
```

The checkout offers Purchased, Pending, Cancelled, and Failed. Purchased grants the Product's Features to the customer, so access unlocks at once and stays on the server like a real purchase. The grant records no transaction and never counts as revenue. It has no renewals or expiry: to test again, use a new customer. To prove StoreKit purchases, renewals, and restores, use [App Store sandbox testing](/docs/monetization/verify-ios-purchases) with Test Store disabled.

## Runtime changes

Use these methods to change purchase handling or locale after setup:

```swift
// nuxie-doc-snippet: runtime-purchase-control
import Nuxie

func selectProviderCheckout(
    _ delegate: any NuxiePurchaseDelegate
) throws {
    try NuxieSDK.shared.setPurchaseHandlingMode(.observer)
    try NuxieSDK.shared.setPurchaseDelegate(delegate)
}

_ = try await NuxieSDK.shared.setLocaleIdentifier("es_ES")
```

Pass `nil` to `setLocaleIdentifier(_:)` to follow the device locale again. The call fetches the new locale's profile before it returns. Events your app sends meanwhile wait for that profile, so a trigger sent during the change can still start an Experience. To change the public key or service environment, await `shutdown()` and set up with a new configuration.

## Complete setup example

This configuration uses native StoreKit, keeps log redaction enabled, and filters events named `debug_*`:

```swift
// nuxie-doc-snippet: complete-configuration
import Nuxie

let config = NuxieConfiguration(apiKey: "your_api_key")

config.environment = .production
config.logLevel = .warning
config.enableConsoleLogging = true
config.redactSensitiveData = true

config.localeIdentifier = nil

// Lifecycle moments ($app_installed, $app_updated, $app_opened,
// $app_backgrounded) are always captured; filter them with beforeSend.
config.beforeSend = { event in
    event.name.hasPrefix("debug_") ? nil : event
}

// Native StoreKit checkout, receipt sync, and finishing are the defaults.
config.purchaseHandlingMode = .full

try NuxieSDK.shared.setup(with: config)
```

<span id="next-steps" />

Continue with [customer identity](/docs/ios-sdk/identity-and-users) or [feature access](/docs/ios-sdk/features-and-entitlements).