Set Up Candid User Research in a UIKit Application

UIKit apps follow the same configure-then-show pattern as SwiftUI, with one extra step: you must explicitly attach the Candid overlay to a UIViewController so the SDK knows where to anchor its research bubble and modal screens. Use Candid.attachUIKitOverlay(to:) right after you set your window’s root view controller, and call Candid.register(trigger:) whenever you want a study to start. (In SDK versions before 0.2.0 this method was named attachOverlay(to:).)

Configure the SDK

Call Candid.configure(_:) once at launch, before your app presents any UI. AppDelegate.application(_:didFinishLaunchingWithOptions:) and SceneDelegate.scene(_:willConnectTo:options:) are both appropriate places.

import CandidSDK
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Candid.configure(
            Candid.Configuration(
                apiKey: "YOUR_API_KEY",
                recordingDuration: 600,
                appearance: Candid.Appearance(
                    primaryColor: "#35C884",
                    font: .system(.rounded)
                )
            )
        )
        Candid.setUserId(AuthSession.current.userId)
        return true
    }
}

If your app uses the scene-based lifecycle, configure in SceneDelegate instead:

import CandidSDK
import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        Candid.configure(
            Candid.Configuration(apiKey: "YOUR_API_KEY")
        )
        Candid.setUserId(AuthSession.current.userId)
        // Attach the overlay after setting up the window, see next section.
    }
}

Attach the overlay

After you assign a root view controller to your UIWindow, call Candid.attachUIKitOverlay(to:) with that same root controller. The SDK adds a transparent overlay view above your app’s interface to host the research bubble and modal screens. The overlay only intercepts touches that land on visible Candid UI; everything else passes through to your app.

func scene(
    _ scene: UIScene,
    willConnectTo session: UISceneSession,
    options connectionOptions: UIScene.ConnectionOptions
) {
    guard let windowScene = scene as? UIWindowScene else { return }

    Candid.configure(
        Candid.Configuration(apiKey: "YOUR_API_KEY")
    )
    Candid.setUserId(AuthSession.current.userId)

    let rootViewController = MainTabBarController()
    let window = UIWindow(windowScene: windowScene)
    window.rootViewController = rootViewController
    window.makeKeyAndVisible()
    self.window = window

    // Attach after the window is visible.
    Candid.attachUIKitOverlay(to: rootViewController)
}

Pass your root view controller, the one assigned to window.rootViewController, not a child, tab, or presented controller. Attaching to a child controller clips the overlay to that controller’s view bounds and breaks the layout of the research bubble.

Register a trigger

Call Candid.register(trigger:) wherever it makes sense in your app flow. Candid fetches the currently running study from your dashboard and presents it over your content.

From a UIButton action

@objc private func feedbackButtonTapped() {
    Candid.register(trigger: "feedback")
}

In viewDidAppear

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    Candid.register(trigger: "home")
}

After a condition

func onboardingDidComplete() {
    // Existing logic…
    Candid.register(trigger: "onboarding_done")
}

Detach the overlay

Call Candid.detachUIKitOverlay() when you no longer need the research UI, for example, when the user logs out or when a particular scene is torn down.

func sceneDidDisconnect(_ scene: UIScene) {
    Candid.detachUIKitOverlay()
}

You can re-attach the overlay at any time by calling Candid.attachUIKitOverlay(to:) again with a new root controller.

If your app replaces its root view controller at runtime (for example, switching from an onboarding flow to the main app), call Candid.detachUIKitOverlay() before the swap and Candid.attachUIKitOverlay(to:) with the new root controller after it.

Get Started

Integration

Configuration

Set Up Candid User Research in a UIKit Application

Configure the SDK

Attach the overlay

Register a trigger

Detach the overlay

​Configure the SDK

​Attach the overlay

​Register a trigger

​Detach the overlay

Configure the SDK

Attach the overlay

Register a trigger

Detach the overlay