iOS SDK reference

Display Experiences, identify customers, and manage access in your Swift app.

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 through File > Add Package Dependencies in Xcode, then add the Nuxie product to your app target. Requires iOS 15 or later.

See Installation for Package.swift configuration.

Initialize the SDK

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

// 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 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:

// 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 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:

// 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 for dismissal and App Actions, or 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:

// 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 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

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

NuxieActivityInfo includes the event ID, customer ID, timestamps, typed activity, name, and scalar properties. Attach the delegate before the activity occurs. See activity callbacks 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.

Related guides

• Publishing — release an Experience to your app.
• Segments — use customer audiences for targeting.
• Privacy and logging — filter event data and configure logs.

The complete Swift API is available in the SDK repository.