Presenting Offers - Encore SDK

Overview

Encore allows you to present targeted offers to users in exchange for rewards (free trials, discounts, credits) at critical moments like cancellation flows or feature paywalls. The SDK uses a delegation pattern — you register purchase and passthrough handlers, then call .show() wherever you need an offer.

Present Offers

Presenting an Encore offer is a single line. The facade is @MainActor, and show() presents on the main thread automatically:

Button("Cancel Subscription") {
    Encore.shared.placement("cancellation_flow").show()   // fire-and-forget
}

When presenting offers in critical flows (like cancellation), your onPassthrough handler ensures users are never blocked from completing their intended action.

Observing the outcome

The fire-and-forget show() above hands control to your registered handlers. If you’d rather branch on the outcome at the call site, use the async form — it returns a PresentationResult. Because a SwiftUI Button action is synchronous, wrap the await in a Task:

Button("Cancel Subscription") {
    Task {
        do {
            let result = try await Encore.shared.placement("cancellation_flow").show()
            switch result {
            case .granted(let entitlement):
                // Success: the user earned an entitlement. Reflect it in your UI.
                unlockPremium(for: entitlement)
            case .notGranted(let reason):
                // Dismiss, no offers, experiment control, or unsupported OS.
                proceedWithCancellation(reason: reason)
            }
        } catch {
            // Transport / SDK error — never block the user.
            proceedWithCancellation(reason: nil)
        }
    }
}

show() only throws for genuine transport/SDK failures. A user dismissal is .notGranted(...), not a thrown error.

Handle Offer Results

Choosing your integration shape: This page shows the handler pattern. If your call site has direct access to purchase logic, the async-result pattern is often cleaner. See Integration Patterns for the decision tree and iOS Integration Patterns for Swift examples.

Register handlers that tell the SDK how to complete purchases and what to do when a user dismisses. Register these once at app launch, after configure().

Register `onPurchaseRequest`

Called when a user accepts an offer. Use this to trigger a purchase via StoreKit, RevenueCat, Adapty, or your own billing implementation. Return true on success — Encore then auto-dismisses the offer sheet. Return false (or throw) to keep the sheet up so the user can retry.

Encore.shared.onPurchaseRequest { purchaseRequest in
    guard let product = try await Product.products(for: [purchaseRequest.productId]).first else {
        return false
    }
    let result = try await product.purchase()
    guard case .success(let verification) = result,
          case .verified(let transaction) = verification else {
        return false  // cancelled, pending, or unverified — keep the sheet up
    }
    await transaction.finish()
    return true  // verified purchase — dismiss the sheet
}

The example above uses StoreKit 2. See onPurchaseRequest() for RevenueCat, Adapty, Qonversion, and custom subscription manager examples.

Register `onPassthrough`

Called when the user dismisses the offer or no offers are available. Use this to resume the user’s original action (e.g., proceed with cancellation).

Encore.shared.onPassthrough { placementId in
    // Resume your original user flow
}

`onPurchaseComplete` (Optional)

Only needed when you don’t set an onPurchaseRequest handler, or when integrating with subscription managers that don’t auto-detect purchases (e.g., Adapty, Qonversion). RevenueCat and Superwall auto-detect purchases and don’t need this callback. The handler receives the verified StoreKit transaction and the productId (in that order):

Encore.shared.onPurchaseComplete { transaction, productId in
    // Sync the StoreKit transaction with your subscription manager
}

Summary

Callback	When it fires	Required?
`onPurchaseRequest`	User accepts the offer	Yes
`onPassthrough`	User dismisses or no offers available	Yes
`onPurchaseComplete`	Purchase finishes (for managers that don’t auto-detect)	Optional

Both onPurchaseRequest and onPassthrough must be registered before presenting any placements.

Third-Party Paywall Integrations

For Superwall and RevenueCat integrations, see the dedicated guides:

Using Superwall

Trigger Encore from Superwall paywalls and dismissals

Using RevenueCat

Trigger Encore from RevenueCat paywalls and dismissals

What a Grant Looks Like

When a user accepts an offer, Encore grants the entitlement in two phases: a provisional grant for instant UX (visible immediately), then a verified grant once the backend confirms the transaction. Provisional grants can later be revoked if verification fails. Gate reversible UI (unlocking a screen, hiding an upsell) on the broad .all scope; gate irreversible or expensive grants on .verified. See EntitlementScope — Two-phase entitlements for the full model.

Next Steps

Add Subscription Product - Create an App Store subscription product and connect it to Encore
Configure Analytics - Track offer performance and measure impact

​Overview

​Present Offers

​Observing the outcome

​Handle Offer Results

​Register onPurchaseRequest

​Register onPassthrough

​onPurchaseComplete (Optional)

​Summary

​Third-Party Paywall Integrations

Using Superwall

Using RevenueCat

​What a Grant Looks Like

​Next Steps

Overview

Present Offers

Observing the outcome

Handle Offer Results

Register `onPurchaseRequest`

Register `onPassthrough`

`onPurchaseComplete` (Optional)

Summary

Third-Party Paywall Integrations

What a Grant Looks Like

Next Steps