Integrate Nuxie with iOS

Agent-readable instructions for installing, configuring, triggering, and verifying the Nuxie iOS SDK

Integrate Nuxie with iOS

Use this guide with the facts copied from the Nuxie dashboard. The facts supply the two publishable API keys, the trigger event, and the Experience name. The SDK requires iOS 15.0 or later.

This page is written as an implementation contract for coding agents and people. Preserve the app’s existing architecture and configuration conventions while completing each section.

1. Install the SDK

Add the Nuxie package with Swift Package Manager:

https://github.com/nuxieai/nuxie-ios

In Xcode, choose File > Add Package Dependencies, enter the URL, and add the Nuxie product to the app target. For a Package.swift project, add the package and product to the appropriate target instead.

Set the app’s minimum deployment target to iOS 15.0 or later. Confirm that this import compiles:

// nuxie-doc-snippet: import-nuxie
import Nuxie

2. Put each key in the matching build configuration

Do not hardcode either key in Swift. Reuse the app’s existing secret and configuration pattern if it has one. Otherwise, create xcconfig values for the two build types:

NUXIE_API_KEY = <API_KEY_DEBUG_BUILDS>

NUXIE_API_KEY = <API_KEY_RELEASE_BUILDS>

Assign each xcconfig file to its matching Xcode build configuration. If the project already has xcconfig files, add NUXIE_API_KEY to those files instead of replacing the base configuration.

Expose the selected value through the target’s Info settings with a NuxieAPIKey entry whose value is $(NUXIE_API_KEY). Do not commit real keys to a public repository.

3. Configure Nuxie at app launch

Call setup once, as early as possible. A SwiftUI app can configure Nuxie in its App initializer. A UIKit app can do the same in application(_:didFinishLaunchingWithOptions:).

// nuxie-doc-snippet: configure-nuxie-from-bundle
import Foundation
import Nuxie

guard
    let apiKey = Bundle.main.object(forInfoDictionaryKey: "NuxieAPIKey") as? String,
    !apiKey.isEmpty
else {
    preconditionFailure("Missing NuxieAPIKey build setting")
}

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

Handle a setup error in the style the app already uses for launch failures. Do not silently discard it while verifying the integration.

Purchase actions only

No additional configuration is required when Nuxie should launch, synchronize, and finish native StoreKit purchases. The default .full mode owns that complete path.

Configure NuxiePurchaseDelegate only when RevenueCat, Superwall, or a custom billing stack must launch checkout. Select observer mode explicitly when that app or provider owns StoreKit finishing:

// nuxie-doc-fragment: configure-app-purchase-delegate harness=app-delegate-body
let config = NuxieConfiguration(apiKey: apiKey)
config.purchaseHandlingMode = .observer
config.purchaseDelegate = AppPurchaseDelegate.shared
try NuxieSDK.shared.setup(with: config)

The delegate receives Nuxie’s retained StoreProduct and returns only the commercial outcome. It must launch the app’s real purchase and restore flows; it does not return receipts or transactions to Nuxie. See the purchase guide for compiling custom and provider examples.

4. Wire the published trigger

Find the user action or lifecycle point described by the Experience and fire the exact event from the copied facts:

// nuxie-doc-fragment: trigger-authored-event harness=sync-body
NuxieSDK.shared.trigger("<TRIGGER_EVENT>")

Keep the trigger at the domain event’s real source. For example, an upgrade offer triggered by a button tap belongs in that button’s action, not unconditionally at app launch. Do not rename, normalize, or prefix the event from the facts.

5. Verify on a device or simulator

Run a debug build and reach the code path that calls setup.
Open the app’s Connect your app surface in Nuxie. It should change from Waiting for your app to Connected.
Fire the configured trigger.
Confirm that the published Experience appears and the dashboard changes to Shown.

If Connected does not appear, verify the selected build configuration, the NuxieAPIKey Info value, network access, and setup error handling. If Connected appears but Shown does not, verify the exact trigger spelling and confirm the trigger is fired after setup.

Completion report

When finished, report:

The package target that received Nuxie
Where debug and release keys are selected
Where setup(with:) runs
Where the trigger is fired
Whether a purchase delegate was required
The observed Connected and Shown results