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

# Candid, Static Methods and Properties Reference

> Complete reference for every public static method and property on the Candid enum, the single entry point into the Candid iOS SDK.

`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(_:)`

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

<ParamField path="configuration" type="Candid.Configuration" required>
  The configuration value that controls your API key, reward, recording duration, step timings, and visual appearance. See [Candid.Configuration](/reference/configuration) for the full field reference.
</ParamField>

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

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

<ParamField path="userId" type="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).
</ParamField>

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

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

***

## `register(trigger:)`

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

<ParamField path="trigger" type="String" required>
  Your trigger name. You choose this value and it should match the trigger from a study in your dashboard.
</ParamField>

## `log(_:)`

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

<ParamField path="event" type="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"`
</ParamField>

```swift theme={null}
// Simple event
Candid.log("checkout_tapped")
```

***

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

```swift theme={null}
@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()`.

<ParamField path="viewController" type="UIViewController" required>
  The root `UIViewController` to which the Candid overlay will be attached. Pass the window's root view controller for full-screen coverage.
</ParamField>

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

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

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