Set Up Candid User Research in a SwiftUI Application

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

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()
        }
    }
}

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.

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.

var body: some Scene {
    WindowGroup {
        ContentView()   // ← your root view
            .candidOverlay()
    }
}

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.

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.

From a button

Button("Give feedback") {
    Candid.register(trigger: "feedback")
}

On screen appear

.onAppear {
    Candid.register(trigger: "home")
}

After an event

.onChange(of: hasCompletedOnboarding) { _, completed in
    if completed {
	  Candid.register(trigger: "onboarding_done")
    }
}

Complete minimal app

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

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")
    }
}

Get Started

Integration

Configuration

Set Up Candid User Research in a SwiftUI Application

Configure the SDK

Attach the overlay

Register a trigger

Complete minimal app

​Configure the SDK

​Attach the overlay

​Register a trigger

​Complete minimal app

Configure the SDK

Attach the overlay

Register a trigger

Complete minimal app