---
title: "iOS SDK reference"
description: "Display Experiences, identify customers, and manage access in your Swift app."
sidebar:
  label: "iOS"
search:
  tags: ["sdk", "reference", "ios"]
  keywords: ["Swift", "StoreKit", "Xcode", "configure", "identify", "consumeFeature", "App Action"]
---

The Nuxie iOS SDK connects your app to the Experiences you create and publish in Nuxie. It supports SwiftUI and UIKit, with built-in StoreKit checkout and Feature access checks.

## Installation

Add the [Nuxie package](https://github.com/nuxieai/nuxie-ios) through **File > Add Package Dependencies** in Xcode, then add the `Nuxie` product to your app target. Requires iOS 15 or later.

See [Installation](/docs/ios-sdk/installation) for `Package.swift` configuration.

<span id="interfaces-and-contracts"></span>

## Initialize the SDK

Copy your app's publishable key from **Connect your app** and call `setup(with:)` once at launch:

```swift
// nuxie-doc-snippet: reference-ios-setup
import Nuxie

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

Use your `pk_test_` key for preview content in development builds and your `pk_live_` key for live content in release builds. Both use the default `.production` service environment. [Configuration](/docs/ios-sdk/configuration) covers locale, logging, and purchase options.

### Configuration options

`NuxieConfiguration` accepts `environment`, `localeIdentifier`, `logLevel`, `enableConsoleLogging`, `redactSensitiveData`, `beforeSend`, `purchaseHandlingMode`, `purchaseDelegate`, and `testStoreEnabled`. Set them before setup. The defaults use production services, the device locale, warning logs with redaction, and native StoreKit checkout.

`isSetup` reports a running session; `version` identifies the installed SDK. Await `shutdown()` before setting up with a different app key or environment. Shutdown releases the SDK session; `reset()` signs out the customer.

At runtime, use `setLocaleIdentifier(_:)`, `setPurchaseDelegate(_:)`, and `setPurchaseHandlingMode(_:)` for those specific changes. These methods can throw if the SDK is not configured.

## Identify a customer

Call `identify()` when a customer signs in. Use the same ID your app uses for that account:

```swift
// nuxie-doc-fragment: reference-ios-identify harness=sync-body
NuxieSDK.shared.identify(
    "user-456",
    userProperties: ["plan": "free"]
)
```

The SDK creates an anonymous ID before sign-in. Changing to a different customer loads their cached state and requests an updated profile. Call `reset()` on sign-out to start a new anonymous session. See [Identity and users](/docs/ios-sdk/identity-and-users) for properties and account changes.

`getDistinctId()` returns the signed-in ID or current anonymous ID. `getAnonymousId()` always returns the anonymous ID, and `isIdentified` distinguishes the two states. `identify()` also accepts `userPropertiesSetOnce` for values to set only when absent. `reset(keepAnonymousId: true)` explicitly retains the anonymous ID.

## Display an Experience

Publish an Experience with an event trigger, then send that event from your app:

```swift
// nuxie-doc-fragment: reference-ios-trigger harness=sync-body
NuxieSDK.shared.trigger("upgrade_requested")
```

Nuxie displays the Experience when the customer matches its audience and re-entry rules. You can update those rules and the Experience's content without changing this call.

See [Presenting Experiences](/docs/ios-sdk/presenting-experiences) for dismissal and App Actions, or [Tracking events](/docs/ios-sdk/tracking-events) to attach event properties.

`trigger(_:properties:)` accepts an optional dictionary of event properties and returns immediately. Use `beforeSend` to filter event data before storage, delivery, and triggering.

Call `await dismiss()` on the main actor to close a visible Experience. Use App Actions to connect an Experience to your app, such as opening the library after onboarding. The action reaches `nuxie(_:didRequestAppAction:)` on your delegate with its name and payload.

## Check Feature access

Use a Feature key to check whether a customer can use a paid capability:

```swift
// nuxie-doc-fragment: reference-ios-access harness=async-body
let access = try await NuxieSDK.shared.hasFeature("premium-content")
if access.allowed {
    showPremiumContent()
} else {
    showUpgradePrompt()
}
```

The same Feature can be granted by several Products, so your app doesn't need to check each subscription separately. For quotas and credits, `useFeatureAndWait()` records usage and returns whether it was accepted. See [Features and entitlements](/docs/ios-sdk/features-and-entitlements) for balances, SwiftUI updates, and usage examples.

### Query and observe access

`hasFeature(_:requiredBalance:entityId:policy:)` is async and throwing. `requiredBalance` defaults to `1`, `entityId` is optional, and `policy` is `.cacheFirst` or `.remote`. Neither policy consumes an allowance.

`FeatureAccess` returns `allowed`, `unlimited`, optional `balance`, and `type`. `NuxieSDK.shared.features` is a main-actor `ObservableObject`: observe `state`, `all`, or `snapshot`, or use `isAllowed(_:)`, `hasBalance(_:)`, `balance(_:)`, and `feature(_:)` for current UI state. `.unknown` means access is still loading, `.reconciling` means purchase access is being synchronized, and a `.ready` snapshot can be empty.

### Record and consume usage

| Method | Result |
| --- | --- |
| `useFeature(_:amount:entityId:metadata:)` | Starts usage reporting without returning a result. |
| `useFeatureAndWait(_:amount:entityId:setUsage:metadata:)` | Async `FeatureUsageResult`; inspect `success`. |
| `consumeFeature(_:quantity:operationId:entityId:)` | Async `FeatureConsumptionResult` for an operation ID saved by your app. |

`setUsage: true` reports a cumulative total and charges only the increase. Explicit consumption lets you reuse the same operation ID after a timeout. Check the receipt's `accepted` value before performing the action, including a last use that leaves zero balance. Apply the accepted app action only once.

Use the credit feature's key directly when spending shared credits. The [feature access guide](/docs/ios-sdk/features-and-entitlements) lists parameters, result fields, and retry behavior.

## Purchases

Nuxie handles StoreKit checkout, purchase synchronization, and transaction finishing by default. To use an existing billing provider, configure a `NuxiePurchaseDelegate` and choose which system owns transaction finishing.

The [purchase guide](/docs/ios-sdk/purchases) includes native StoreKit, RevenueCat, and Superwall examples.

`NuxiePurchaseDelegate` implements `purchase(product:) async -> PurchaseResult` and `restorePurchases() async -> RestoreResult`. Purchase outcomes are `.purchased`, `.cancelled`, `.pending`, and `.failed(Error)`. Restore outcomes are `.restored`, `.noPurchases`, and `.failed(Error)`.

Call `await NuxieSDK.shared.restorePurchases()` from your own restore button. Use the delegate's selected `StoreProduct` and `storeKitPurchaseOptions` for custom checkout. The [purchase guide](/docs/ios-sdk/purchases#product-fields) describes every product field and billing integration option.

## Delegate callbacks

Assign an app-retained `NuxieDelegate` to `NuxieSDK.shared.delegate`. The SDK holds it weakly. All callbacks run on the main actor; implement only the methods you need.

| Method | Purpose |
| --- | --- |
| `featureAccessDidChange(_:from:to:)` | Receive the old and new access for a changed feature. |
| `nuxie(_:didRequestAppAction:)` | Handle the name, payload, and Experience context of an authored App Action. |
| `nuxieDidEmit(_:)` | Observe activity for analytics and presentation state. |

`NuxieActivityInfo` includes the event ID, customer ID, timestamps, typed activity, name, and scalar properties. Attach the delegate before the activity occurs. See [activity callbacks](/docs/ios-sdk/presenting-experiences#observe-activity) for fields and customer handling.

## Errors

Catch errors from setup and async methods. `NuxieError` includes `.notConfigured` and `.invalidConfiguration(String)`; other operation failures are returned as Swift errors. A failed feature request is different from a successful `allowed: false` result.

Fire-and-forget methods log failures. Purchase cancellation and pending approval are typed outcomes. A timeout during consumption does not prove the charge was cancelled: retry using the original operation ID.

<span id="shared-platform-behavior"></span>

## Related guides

- [Publishing](/docs/guides/publishing) — release an Experience to your app.
- [Segments](/docs/ios-sdk/segments) — use customer audiences for targeting.
- [Privacy and logging](/docs/ios-sdk/privacy-and-logging) — filter event data and configure logs.

The complete Swift API is available in the [SDK repository](https://github.com/nuxieai/nuxie-ios/blob/main/api/public-api.txt).