Get Started with the Candid iOS SDK in Minutes

This guide takes you from a blank Xcode project to a working Candid session.

Add the Swift Package to Xcode

Open your project in Xcode, then choose File → Add Package Dependencies. Paste the repository URL into the search field and press Return:

https://github.com/trycandid/candid-ios-sdk.git

Select the Candid product and add it to your app target. Xcode resolves the package and makes the CandidSDK module available to import.

Candid requires iOS 17 or later and Xcode 16 with Swift 6. Make sure your target’s minimum deployment version is set to iOS 17 before resolving the package.

Add NSMicrophoneUsageDescription to Info.plist

So that your app can access the microphone, open your target’s Info.plist and add the following key if not present:

<key>NSMicrophoneUsageDescription</key>
<string>Candid records microphone audio while you share feedback.</string>

This string will be shown to the user in the system permission prompt.

Configure the SDK with your API key

Call Candid.configure(_:) once at launch, typically in your App initialiser or application(_:didFinishLaunchingWithOptions:). Pass a Candid.Configuration value with your project API key:

import CandidSDK

Candid.configure(
    .init(apiKey: "your_api_key")
)

Replace your_api_key with the key shown in your Candid project settings. You can optionally pass reward, recordingDuration, stepTimings, and appearance to the same initialiser to customise the session, see Configuration for details.To identify the current participant, call Candid.setUserId(_:) at any time, for example once the user logs in:

Candid.setUserId("user-abc123")

You can call Candid.configure(_:) more than once, for example to update the API key or appearance. Each call replaces the previous configuration.

Attach the overlay to your root view

Candid presents its session UI in a transparent full-screen overlay. Attach it once at the root of your SwiftUI view hierarchy using the .candidOverlay() modifier:

import CandidSDK
import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .candidOverlay()
        }
    }
}

For UIKit apps, attach the overlay to your root view controller instead:

import CandidSDK

Candid.attachUIKitOverlay(to: rootViewController)

Place .candidOverlay() (or attachUIKitOverlay) at the outermost level so the overlay covers the entire screen during a session without being clipped by child view geometry.

Call Candid.register(trigger:) wherever you want to trigger a study:

import CandidSDK

Candid.register(trigger: "home")

Candid.register(trigger:)presents the study overlay automatically if it applies. Candid walks the participant through permissions, tasks, recording, and upload without any further code on your side.

Confirm the integration is done correctly

In your dashboard, click on New Study, type a random question in Task 1, keep Rollout to 100%, and type your trigger name. Then, click on Create Study, then Run Study. Build your app, launch it and navigate until your trigger is registered. Your study should now show: complete it and you will see the result session on your dashboard.