> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# configure()

> Initialize the Encore SDK with your public API key

Configures the shared Encore instance for use throughout your app. This must be called once, typically in your `AppDelegate` or SwiftUI `App` initializer, before using any other SDK methods.

<Warning>
  Call `configure()` before using any other SDK methods. Failure to do so produces `EncoreError.integration(.notConfigured)` errors.
</Warning>

## Signature

```swift theme={null}
public func configure(
  apiKey: String,
  options: Encore.Options = .init()
)
```

`Options` bundles the SDK's runtime settings:

```swift theme={null}
extension Encore {
    public struct Options: Sendable {
        public var logLevel: LogLevel   // default .none
        public var unlock: UnlockMode   // default .optimistic

        public init(logLevel: LogLevel = .none, unlock: UnlockMode = .optimistic)
    }
}
```

<Note>
  The older `configure(apiKey:logLevel:unlock:)` overload is **deprecated** — it forwards to `configure(apiKey:options:)`. Prefer passing an `Options` value.
</Note>

## Parameters

| Name      | Type                         | Default   | Description                                                                     |
| --------- | ---------------------------- | --------- | ------------------------------------------------------------------------------- |
| `apiKey`  | `String`                     | -         | Your Live Key (`pk_live_…`) or Test Key (`pk_test_…`) from the Encore Dashboard |
| `options` | [`Encore.Options`](#options) | `.init()` | Runtime options — log verbosity and unlock mode                                 |

### Options

| Field      | Type                             | Default       | Description                                       |
| ---------- | -------------------------------- | ------------- | ------------------------------------------------- |
| `logLevel` | [`Encore.LogLevel`](#log-levels) | `.none`       | Logging verbosity                                 |
| `unlock`   | [`UnlockMode`](#unlock-mode)     | `.optimistic` | When entitlements are granted after an offer flow |

### Unlock mode

`UnlockMode` controls *when* the SDK grants an entitlement after the user returns from an offer:

```swift theme={null}
public enum UnlockMode: Sendable {
    case optimistic   // default: grant immediately on return from Safari
    case strict       // wait for advertiser postback verification before granting
}
```

| Mode                    | Behavior                                                                                                                                    | Use when                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `.optimistic` (default) | Grants the moment the user returns to the app. This is the **provisional** grant — instant UX, later confirmed (or revoked) by the backend. | You want the snappiest unlock and gate reversible UX on the `.all` scope (see [EntitlementScope](./entitlement-scope)). |
| `.strict`               | Withholds the grant until the advertiser's postback verifies the conversion.                                                                | You only ever want verified grants and can tolerate a short delay before the reward appears.                            |

```swift theme={null}
Encore.shared.configure(
    apiKey: "pk_live_<your_key>",
    options: .init(logLevel: .info, unlock: .strict)
)
```

### Log levels

```swift theme={null}
public enum LogLevel: Int, Comparable {
  case none = 0    // No logging (recommended for production)
  case error = 1   // Only errors
  case warn = 2    // Warnings and errors
  case info = 3    // Milestones, warnings, and errors
  case debug = 4   // Everything (verbose, development only)
}
```

<Info>
  Higher levels include all lower levels. For example, `.info` will also show warnings and errors.
</Info>

### API keys

Encore supports two types of API keys:

| Key Type     | Format        | Description                                                                                                        |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Live Key** | `pk_live_...` | Production key with standard geo-filtering based on offers' configured regions                                     |
| **Test Key** | `pk_test_...` | Testing key that bypasses geo-filtering, allowing you to test the complete entitlement lifecycle from any location |

<Info>
  Use the test key (`pk_test_...`) during development to test offers from any location without geo-filtering restrictions. This makes it easy to test the entire entitlement lifecycle end-to-end for a single user.
</Info>

<Warning>
  Always use your live key (`pk_live_...`) in production builds. The test key is for development and testing only.
</Warning>

## Usage

### Basic Configuration

```swift theme={null}
import Encore

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  Encore.shared.configure(apiKey: "pk_live_your_key")
  return true
}
```

### SwiftUI

```swift theme={null}
@main
struct YourApp: App {
  init() {
    Encore.shared.configure(apiKey: "pk_live_your_key")
  }
  
  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}
```

### With Debug Logging (Development)

```swift theme={null}
#if DEBUG
Encore.shared.configure(
  apiKey: "pk_test_your_key",
  options: .init(logLevel: .debug)  // Enable debug logs for development
)
#else
Encore.shared.configure(apiKey: "pk_live_your_key")  // Silent for production
#endif
```

### Using Test Key for Development

Use the test key to test offers from any location without geo-filtering:

```swift theme={null}
#if DEBUG
Encore.shared.configure(
  apiKey: "pk_test_your_key",  // Bypasses geo-filtering
  options: .init(logLevel: .debug)
)
#else
Encore.shared.configure(apiKey: "pk_live_your_key")
#endif
```

<Tip>
  The test key (`pk_test_...`) is perfect for comprehensive end-to-end testing of the entitlement lifecycle, allowing you to test location-restricted offers from anywhere during development.
</Tip>

<Tip>
  Use `logLevel: .debug` during development to see detailed SDK logs, then remove it (or use `.none`) for production builds.
</Tip>