> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycandid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Candid User Research in a SwiftUI Application

> Configure Candid, attach the overlay modifier to your root view, and trigger research studies in your SwiftUI app in minutes.

SwiftUI apps integrate Candid in three steps: configure the SDK with your API key and user ID, attach the `.candidOverlay()` modifier to your root view so the research UI has a place to render, then call `Candid.register(trigger:)` whenever you want a study to begin. All three steps are independent of your navigation stack, the overlay sits above everything else in the window.

## Configure the SDK

Call `Candid.configure(_:)` once before your app presents any UI. The recommended place is `App.init`, but a `.task` modifier on the root view also works if you prefer to defer until the first scene appears.

`Candid.Configuration` accepts the following parameters:

| Parameter           | Type                     | Description                                         |
| ------------------- | ------------------------ | --------------------------------------------------- |
| `apiKey`            | `String?`                | Your Candid API key                                 |
| `reward`            | `Candid.Reward?`         | Optional reward fulfilled after the session uploads |
| `recordingDuration` | `TimeInterval`           | Maximum recording length in seconds (default 600)   |
| `stepTimings`       | `[StepType: StepTiming]` | Skip and prompt timings per step type               |
| `appearance`        | `Candid.Appearance`      | Primary color, font, and widget position            |

The participant identifier is set separately with `Candid.setUserId(_:)`, at any time (e.g. after login).

```swift theme={null}
import CandidSDK
import SwiftUI

@main
struct MusicApp: App {
    init() {
        Candid.configure(
            Candid.Configuration(
                apiKey: "YOUR_API_KEY",
                recordingDuration: 600,
                appearance: Candid.Appearance(
                    primaryColor: "#35C884",
                    font: .system(.rounded)
                )
            )
        )
        Candid.setUserId(AuthSession.current.userId)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .candidOverlay()
        }
    }
}
```

<Note>
  Call `Candid.configure(_:)` before `Candid.register(trigger:)`. If you call `register(trigger:)` first, the SDK has no API key and cannot load or upload a research session.
</Note>

## Attach the overlay

Add `.candidOverlay()` to your **root view**: the view that fills the entire window. The modifier inserts an invisible layer that Candid uses to present the research bubble, permission prompts, and recording controls above your app's content.

```swift theme={null}
var body: some Scene {
    WindowGroup {
        ContentView()   // ← your root view
            .candidOverlay()
    }
}
```

<Warning>
  Apply `.candidOverlay()` exactly once at the root of your view hierarchy. Attaching it to a child view or inside a `NavigationStack` clips the overlay to that view's bounds and causes layout issues.
</Warning>

## Register a trigger

Call `Candid.register(trigger:)` to load the currently running study associated to a trigger from your Candid dashboard and present it to the user. Register triggers when a specific screen appears, or after any meaningful event in your app.

<Steps>
  <Step title="From a button">
    ```swift theme={null}
    Button("Give feedback") {
        Candid.register(trigger: "feedback")
    }
    ```
  </Step>

  <Step title="On screen appear">
    ```swift theme={null}
    .onAppear {
        Candid.register(trigger: "home")
    }
    ```
  </Step>

  <Step title="After an event">
    ```swift theme={null}
    .onChange(of: hasCompletedOnboarding) { _, completed in
        if completed {
    	  Candid.register(trigger: "onboarding_done")
        }
    }
    ```
  </Step>
</Steps>

## Complete minimal app

The following is a self-contained SwiftUI app showing every required piece together:

```swift theme={null}
import CandidSDK
import SwiftUI

@main
struct MusicApp: App {
    init() {
        Candid.configure(
            Candid.Configuration(apiKey: "YOUR_API_KEY")
        )
        Candid.setUserId("user-123")
    }

    var body: some Scene {
        WindowGroup {
            RootView()
                .candidOverlay()
        }
    }
}

struct RootView: View {
    var body: some View {
        NavigationStack {
            HomeView()
        }
    }
}

struct HomeView: View {
    var body: some View {
        VStack(spacing: 16) {
            Text("Welcome")
                .font(.largeTitle)

            Button("Share feedback") {
                Candid.register(trigger: "feedback")
            }
            .buttonStyle(.borderedProminent)
        }
        .navigationTitle("Home")
    }
}
```