configure()

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.

Call configure() before using any other SDK methods. Failure to do so makes show() resolve with .notPresented(.notConfigured) and other APIs report EncoreError.integration(.notConfigured).

Signature

@MainActor
public func configure(
  apiKey: String,
  purchaseController: EncorePurchaseController? = nil,
  options: Encore.Options = .init()
)

Options bundles the SDK’s runtime settings:

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)
    }
}

Parameters

Name	Type	Default	Description
`apiKey`	`String`	-	Your Live Key (`pk_live_…`) or Test Key (`pk_test_…`) from the Encore Dashboard
`purchaseController`	`EncorePurchaseController?`	`nil`	The controller Encore offers purchase through. Required if your app sells a product through Encore offers; with no controller, the SDK never attempts a purchase.
`options`	`Encore.Options`	`.init()`	Runtime options: log verbosity and unlock mode

The SDK has no built-in billing. If a subscription product is configured for your app but no controller is registered, the claim completes with publisher: .notAttempted, a warning is logged naming the product, and the sdk_iap_no_purchase_controller analytics event is emitted. See EncorePurchaseController.

Registering a controller is build-time wiring, not user state: it survives reset(), so logging a user out does not require re-registering.

Options

Field	Type	Default	Description
`logLevel`	`Encore.LogLevel`	`.none`	Logging verbosity
`unlock`	`UnlockMode`	`.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:

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).
`.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.

Encore.shared.configure(
    apiKey: "pk_live_<your_key>",
    options: .init(logLevel: .info, unlock: .strict)
)

Log levels

extension Encore {
  public enum LogLevel: Int, Comparable, Sendable {
    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)
  }
}

Higher levels include all lower levels. For example, .info will also show warnings and errors.

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

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.

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

Usage

Basic Configuration

import Encore

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

With a purchase controller

If your app sells a product through Encore offers, register your EncorePurchaseController at configure time so purchases run through your billing code:

Encore.shared.configure(
  apiKey: "pk_live_your_key",
  purchaseController: AppPurchases()
)

SwiftUI

@main
struct YourApp: App {
  init() {
    Encore.shared.configure(
      apiKey: "pk_live_your_key",
      purchaseController: AppPurchases()
    )
  }

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

Development builds

Pair the test key with logLevel: .debug so development builds bypass geo-filtering and log verbosely, while production builds keep the live key and stay silent:

#if DEBUG
Encore.shared.configure(
  apiKey: "pk_test_your_key",          // Bypasses geo-filtering
  purchaseController: AppPurchases(),
  options: .init(logLevel: .debug)     // Verbose SDK logs
)
#else
Encore.shared.configure(
  apiKey: "pk_live_your_key",
  purchaseController: AppPurchases()
)
#endif

iOS

Android

Web

Bridges

Signature

Parameters

Options

Unlock mode

Log levels

API keys

Usage

Basic Configuration

With a purchase controller

SwiftUI

Development builds

​Signature

​Parameters

​Options

​Unlock mode

​Log levels

​API keys

​Usage

​Basic Configuration

​With a purchase controller

​SwiftUI

​Development builds

Signature

Parameters

Options

Unlock mode

Log levels

API keys

Usage

Basic Configuration

With a purchase controller

SwiftUI

Development builds