Presenting Offers

Overview

Encore lets you present a premium brand offer (a real perk a brand funds to acquire customers, such as a free trial, discount, or credit) at critical moments like cancellation flows or feature paywalls. You call show() wherever you need an offer and branch on the result it returns; if your app sells a product through Encore offers, purchases run through the EncorePurchaseController you registered at configure time.

Using a third-party subscription manager? If Superwall or RevenueCat owns your paywall, the trigger point changes: see Superwall or RevenueCat.

Present Offers

The facade is @MainActor, so call show() from a main-actor context: a SwiftUI button action, a .task, or a UIKit handler. show() never throws and always resolves; a SwiftUI Button action is synchronous, so wrap the await in a Task:

Button("Cancel Subscription") {
    Task {
        let result = await Encore.shared.placement("cancellation_flow").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
            proceedWithCancellation()      // dismissed, declined, nothing appeared, ...
        }
    }
}

Always run your original flow in the non-success branch. Every presentation resolves exactly once, so this branch is guaranteed to run whenever the user should continue: dismissals, no offers, control cohorts, and errors all land here.

Callback form

When the call site can’t await, show(resume:) delivers every outcome (including .notPresented) on the main actor:

Button("Cancel Subscription") {
    Encore.shared.placement("cancellation_flow").show { result in
        if result.claim == nil && result.publisher != .purchased {
            proceedWithCancellation()
        }
    }
}

show() never throws. Failures arrive as .notPresented(.error(EncoreError)) on the PresentationResult, so there is no catch block to forget.

Handle Purchases

When a user accepts an offer that requires a purchase, the SDK calls the EncorePurchaseController you registered at configure time. It performs the purchase through your billing code (StoreKit 2, RevenueCat, Adapty, or your own) and reports what happened:

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.notFound }
        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_live_your_key", purchaseController: AppPurchases())

The example above uses StoreKit 2. See EncorePurchaseController for RevenueCat, Adapty, and custom subscription manager implementations.

If your app uses Encore offers without a subscription product, no controller is needed and no purchase is ever attempted. If a product is configured but no controller is registered, the SDK never attempts a purchase: the claim completes with publisher: .notAttempted and the sdk_iap_no_purchase_controller analytics event flags the misconfiguration.

Observe Outcomes Passively

Anything that wants to watch results without owning a call site (analytics forwarding, a debug overlay, cross-screen state) consumes 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
        }
    }
}

What a Grant Looks Like

The result of show() records the raw facts of the flow; read the granted entitlement itself from isActive / isActivePublisher, the authoritative state. See Two-phase entitlements in EntitlementScope for how provisional and verified grants differ and which scope to gate on.

Next Steps

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

iOS

Android

Web

Bridges

Presenting Offers

Overview

Present Offers

Callback form

Handle Purchases

Observe Outcomes Passively

What a Grant Looks Like

Next Steps

​Overview

​Present Offers

​Callback form

​Handle Purchases

​Observe Outcomes Passively

​What a Grant Looks Like

​Next Steps

Overview

Present Offers

Callback form

Handle Purchases

Observe Outcomes Passively

What a Grant Looks Like

Next Steps