Integration Patterns

Overview

await Encore.shared.placement(_:).show() returns a PresentationResult: the factual record of the presentation. It never throws, and it resolves exactly once. Three rules cover almost every integration:

Invoke show() from a main-actor context. The facade and builder are @MainActor.
Results are values: await inline for control flow. Branch on the result where the context lives.
outcomes is for passive observers. Analytics, debug overlays, and cross-screen state consume the stream instead of owning a call site.

Rule 1: Invoke show() from a main-actor context

Call show() from a SwiftUI button action, a .task, or a UIKit handler; you are already on the main actor there, and the compiler enforces the rest.

Button("Upgrade") {
    Task {                       // inherits @MainActor from the button action
        let result = await Encore.placement("upgrade_button").show()
        handle(result)
    }
}

Presentation mutates UI state; invoking it off-main would order the sheet arbitrarily against your progressing app UI. From nonisolated code, await hops you over: it compiles, and the result still resumes on main.

Rule 2: Results are values, await inline for control flow

Branch on the raw facts your flow cares about:

func cancelTapped() {
    Task {
        let result = await Encore.placement("cancel_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.
            navigateHome()
        } else {
            result.error.map(log)             // presentation failures are values
            proceedWithCancellation()         // dismissed, declined, nothing appeared, ...
        }
        // Code that runs in both branches lives here, written once
        analytics.track("cancel_flow_resolved")
    }
}

There is no SDK-computed “unlocked” verdict: what a claim means is a property of the flow that served it, so the record reports what happened and your integration decides. When the mechanism matters (analytics, debugging), switch on the factual record:

switch result {
case .presented(let outcome):      // advertiser + publisher funnels, dismissal
    analytics.log(outcome.advertiser, outcome.publisher, outcome.dismissal)
case .notPresented(let reason):    // no offers, control cohort, error, ...
    analytics.log(reason)
}

When the call site can’t await

show(resume:) delivers every outcome, including .notPresented, on the main actor:

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

When other parts of the app need the outcome, forward it into an app-owned @Observable state object distributed via .environment(_:):

@Observable final class OfferState {
    var lastResult: PresentationResult?
    func apply(_ result: PresentationResult) { lastResult = result }
}

// at the call site
Task {
    let result = await Encore.placement("paywall").show()
    offerState.apply(result)
}

Rule 3: outcomes is for passive observers

Anything that wants to watch results without owning a call site consumes the multicast outcomes stream. Every resolution lands there, plus late events:

.task {
    for await outcome in Encore.shared.outcomes {
        switch outcome {
        case .presentation(let placementId, let result):
            analytics.log("encore", placementId, "\(result)")
        case .strictUnlockVerified(let transactionId):
            // A strict-unlock claim verified after its flow ended, possibly
            // on a later launch. Entitlements are already refreshed; gate on
            // isActive / isActivePublisher.
            print("late verification for \(transactionId)")
        }
    }
}

Each access to outcomes returns an independent stream; any number of observers can listen concurrently.

Recipe: paywall-delegate call sites (Superwall and friends)

Delegate methods hand you a synchronous, nonisolated context. Bridge with a Task, forward the result into your state object:

extension PaywallService: SuperwallDelegate {
    func handleCustomPaywallAction(withName name: String) {
        guard name == "encore_offer" else { return }
        Task { @MainActor in
            let result = await Encore.placement("superwall_action").show()
            appState.apply(result)
        }
    }
}

Register your purchase controller once at configure time, so purchases the sheet triggers run through your subscription manager:

Encore.shared.configure(apiKey: key, purchaseController: AppPurchases())

Platform-specific notes

Task { } wrapping: show() is async; SwiftUI Button actions and UIKit @IBAction selectors are synchronous, so wrap the call in Task { ... }.
show() never throws: failures arrive as .notPresented(.error(EncoreError)), read via result.error. There is no catch block to forget.
Encore is the entry point: Encore is a public final class. Access it via Encore.shared; the static Encore.placement(_:) forwards to it.
Purchases: there are no purchase handlers to register per call site. The EncorePurchaseController passed to configure owns every purchase.

iOS

Android

Web

Bridges

Integration Patterns

Overview

Rule 1: Invoke show() from a main-actor context

Rule 2: Results are values, await inline for control flow

When the call site can’t await

Rule 3: outcomes is for passive observers

Recipe: paywall-delegate call sites (Superwall and friends)

Platform-specific notes

See also

​Overview

​Rule 1: Invoke show() from a main-actor context

​Rule 2: Results are values, await inline for control flow

​When the call site can’t await

​Sharing the result across the app

​Rule 3: outcomes is for passive observers

​Recipe: paywall-delegate call sites (Superwall and friends)

​Platform-specific notes

​See also

Overview

Rule 1: Invoke show() from a main-actor context

Rule 2: Results are values, await inline for control flow

When the call site can’t await

Sharing the result across the app

Rule 3: outcomes is for passive observers

Recipe: paywall-delegate call sites (Superwall and friends)

Platform-specific notes

See also