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

# Get Started with the Candid iOS SDK in Minutes

> Add Candid to an iOS project, configure your API key, attach the overlay, and run your first in-app research session in under five minutes.

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

<Steps>
  <Step title="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**:

    ```text theme={null}
    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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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:

    ```xml theme={null}
    <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.
  </Step>

  <Step title="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:

    ```swift theme={null}
    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](/configuration/overview) for details.

    To identify the current participant, call `Candid.setUserId(_:)` at any time, for example once the user logs in:

    ```swift theme={null}
    Candid.setUserId("user-abc123")
    ```

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

  <Step title="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:

    ```swift theme={null}
    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:

    ```swift theme={null}
    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.
  </Step>

  <Step title="Register a trigger">
    Call `Candid.register(trigger:)` wherever you want to trigger a study:

    ```swift theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>