Candid, Static Methods and Properties Reference

Candid is the top-level @MainActor enum that acts as the single namespace for all SDK interactions. You never instantiate it directly; instead you call its static methods and set its static properties from your app’s main actor context. The sections below cover every public API member in declaration order.

`configure(_:)`

@MainActor
static func configure(_ configuration: Candid.Configuration)

Call this method once, as early as possible in your app’s lifecycle (typically in App.init() or application(_:didFinishLaunchingWithOptions:)), before invoking any other SDK method. Calling it more than once replaces the active configuration.

Candid.Configuration

required

The configuration value that controls your API key, reward, recording duration, step timings, and visual appearance. See Candid.Configuration for the full field reference.

// SwiftUI, App entry point
@main
struct MyApp: App {
    init() {
        Candid.configure(
            Candid.Configuration(apiKey: "cpk_your_project_key")
        )
    }

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

`setUserId(_:)`

@MainActor
static func setUserId(_ userId: String?)

Sets the participant identifier attached to study resolution and uploads, or clears it with nil. Call it at any time, before or after configure(_:), for example once the user logs in. When no user id is set, requests are sent anonymously and once-per-user study presentation is tracked locally per install.

String?

required

A stable identifier for the current participant in your own system, for example a database row ID or hashed email. Pass nil to clear it (e.g. on sign-out).

// After login
Candid.setUserId("user-abc123")

// On sign-out
Candid.setUserId(nil)

`register(trigger:)`

@MainActor
static func register(trigger: String)

Fetches the active study from the Candid dashboard associated to a trigger and presents the recording overlay to the participant.

String

required

Your trigger name. You choose this value and it should match the trigger from a study in your dashboard.

`log(_:)`

@MainActor
static func log(_ event: String)

Forwards a named user event to the SDK so it can be matched against action task completion criteria. Call this alongside (or instead of) your own analytics tracking whenever something meaningful happens in your app.

String

required

The event name. This must match the event (or one of the matchingEvents) on the Candid.Task you want to complete. Matching is case-sensitive.Examples: "add_to_cart", "checkout_tapped", "photo_uploaded"

// Simple event
Candid.log("checkout_tapped")

`attachUIKitOverlay(to:)` and `detachUIKitOverlay()`

@MainActor
static func attachUIKitOverlay(to viewController: UIViewController)

@MainActor
static func detachUIKitOverlay()

UIKit methods to manually manage the Candid overlay’s lifecycle. Use these when you cannot use the SwiftUI .candidOverlay() modifier, for example in a UIKit-only app or when your root view controller is set up imperatively. attachUIKitOverlay(to:) installs the overlay as a child of the provided view controller; detachUIKitOverlay() removes it. The overlay only intercepts touches that land on visible Candid UI; everything else passes through to your app. You only need to call attachUIKitOverlay(to:) once; the SDK retains the reference until you call detachUIKitOverlay() or reset().

UIViewController

required

The root UIViewController to which the Candid overlay will be attached. Pass the window’s root view controller for full-screen coverage.

// UIKit AppDelegate
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    Candid.configure(Candid.Configuration(apiKey: "cpk_your_project_key"))

    if let root = window?.rootViewController {
        Candid.attachUIKitOverlay(to: root)
    }
    return true
}

// On sign-out or teardown
Candid.detachUIKitOverlay()

`candidOverlay()`

@MainActor
func candidOverlay() -> some View

A SwiftUI View extension method that attaches the Candid recording overlay to your view hierarchy. Apply it at the root of your app’s scene so the overlay can appear on top of any screen.

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .candidOverlay()  // Apply at the app root
        }
    }
}

​configure(_:)

​setUserId(_:)

​register(trigger:)

​log(_:)

​attachUIKitOverlay(to:) and detachUIKitOverlay()

​candidOverlay()

`configure(_:)`

`setUserId(_:)`

`register(trigger:)`

`log(_:)`

`attachUIKitOverlay(to:)` and `detachUIKitOverlay()`

`candidOverlay()`