Updating to 2.x

​

Overview

• show() returns a result and never throws. Errors arrive as values on the result instead of as thrown exceptions.
• Purchases run through a registered EncorePurchaseController. The SDK never runs purchase code you didn’t write.
• Global handler closures and delegates are retired. Results are values at the call site; passive observation moves to the Encore.shared.outcomes stream.
• The public API is @MainActor. Results and callbacks always land on the main actor.

​

Step 1: Update the package

.package(url: "https://github.com/EncoreKit/ios-sdk", from: "2.0.0")

​

Step 2: Register a purchase controller

final class AppPurchases: EncorePurchaseController {
    func purchase(_ request: PurchaseRequest) async throws -> EncorePurchaseResult {
        let products = try await Purchases.shared.products([request.productId])
        guard let product = products.first else { throw PurchaseError.productNotFound }
        let result = try await Purchases.shared.purchase(product: product)
        return result.userCancelled ? .cancelled : .purchased
    }
}

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

final class AppPurchases: EncorePurchaseController {
    func purchase(_ request: PurchaseRequest) async throws -> EncorePurchaseResult {
        let products = try await Product.products(for: [request.productId])
        guard let product = products.first else { throw PurchaseError.productNotFound }
        switch try await product.purchase() {
        case .success(let verification):
            if case .verified(let transaction) = verification { await transaction.finish() }
            return .purchased
        case .userCancelled: return .cancelled
        case .pending: return .pending
        @unknown default: return .cancelled
        }
    }
}

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

​

Step 3: Update show() call sites

// 1.x
do {
    let result = try await Encore.placement("paywall").show()
    if case .granted = result { unlock() } else { runOriginalFlow() }
} catch {
    runOriginalFlow()   // often forgotten, causing a silent hang
}

// 2.0
let result = await Encore.placement("paywall").show()
if result.claim != nil || result.publisher == .purchased { unlock() } else { runOriginalFlow() }

// 1.x: every error and result discarded
Encore.placement("paywall").show()

// 2.0: every outcome delivered
Encore.placement("paywall").show { result in
    if result.claim == nil && result.publisher != .purchased { runOriginalFlow() }
}

​

Step 4: Update result handling

let result = await Encore.placement("paywall").show()
if result.claim != nil || result.publisher == .purchased {
    // The user claimed an offer or completed your purchase.
    // Read the concrete entitlement from isActive / isActivePublisher.
} else {
    result.error.map(log)   // presentation failures are values
    runOriginalFlow()       // dismissed, declined, no offers, control cohort, ...
}

switch result {
case .presented(let outcome):
    analytics.log(outcome.advertiser, outcome.publisher, outcome.dismissal)
case .notPresented(let reason):
    analytics.log(reason)
}

​

Step 5: Replace global callbacks with the outcomes stream

Task {
    for await outcome in Encore.shared.outcomes {
        switch outcome {
        case .presentation(let placementId, let result):
            analytics.log("encore_outcome", placementId, result)
        case .strictUnlockVerified:
            // Entitlements already refreshed. Re-check isActive / isActivePublisher.
            break
        }
    }
}

​

Removed APIs at a glance

​

Behavior changes to be aware of

• Errors no longer throw from show(). Old catch fallback blocks are dead code; run fallback off .notPresented instead.
• Claim-then-purchase records both funnels. 1.x collapsed the flow to a single winner. 2.0 carries advertiser: .claimed(...) and publisher: .purchased side by side, and the result is delivered once, after the purchase resolves (later than 1.x fired its callbacks).
• Strict mode records the claim, and verification upgrades it. The record says advertiser: .claimed(...) immediately (and result.claim surfaces it); in-session verification upgrades it to .verified(...), and late completion arrives as .strictUnlockVerified on Encore.shared.outcomes, surviving process death. Gate concrete access on isActive / isActivePublisher.
• Callbacks and resumes always land on the main actor. 1.x invoked them from arbitrary contexts.

​

New in 2.0, with no migration required

• A claim-only reward surface. A placement can select .useCase(.rewardUsers) to present after the user has already done something worth celebrating, such as a completed purchase, a milestone, or a streak. It never runs a purchase and never falls back to the paywall sheet. Placements that omit useCase(_:) keep the default .reduceChurn surface.
• Per-presentation copy overrides. headline(_:) and subheadline(_:) replace the sheet’s shipped copy for one presentation. You pass the whole string, so localization and pluralization stay yours.
• A runtime claim gate. Encore.shared.isClaimEnabled dims the claim CTA and stops it responding to taps, leaving the rest of the presentation intact.
• No more wedged presentations. A dead flow can no longer brick presentation with .alreadyPresenting: every flow resolves on a real event.
• Durable strict-mode claims. A strict-mode claim that ends unverified persists across launches until verification completes.

let result = await Encore.shared.placement("streak_complete")
    .useCase(.rewardUsers)
    .headline("That's three days in a row staying informed 🔥")
    .subheadline("Here's a little thank you from us")
    .show()

​

Verify the migration

1. The project compiles with no references to removed 1.x APIs.
2. If a subscription product is configured for your app, an EncorePurchaseController is registered at configure time.
3. Every fallback path (your original paywall or flow) runs off the no-claim, no-purchase branch (result.claim == nil && result.publisher != .purchased), not a catch block.
4. Test the full flow on a device: present a placement, claim an offer, complete a purchase, and dismiss without acting. Each path should resolve exactly once with the result you expect.