Integration Patterns

Overview

Every Encore SDK exposes the same primitive: Encore.placement(id).show() opens the offer sheet, the user accepts or dismisses, and you do something next. There are two idiomatic ways to wire up the “do something next” part:

Async-result — await show() returns a result; branch on it locally.
Handler-based — register onPurchaseRequest / onPassthrough once at app launch; the SDK calls back into them whenever a placement resolves.

Both patterns are first-class. Pick by whether the call site that triggers show() already has access to your purchase + decline logic.

The two patterns

Async-result (recommended when applicable)

The trigger is also the handler. Code that should run in both branches is written once, control flow is local, no global state.

async function onCancelTapped() {
    let result = await Encore.placement("cancel_flow").show()
    switch (result) {
        case .granted:    // user accepted the offer
            navigate(.home)
        case .notGranted: // user declined or no offers
            proceedWithCancellation()
    }
    // Code that runs in both branches
    analytics.track("cancel_flow_resolved")
}

Handler-based

// At app launch, after Encore.configure(...)
Encore.shared.onPurchaseRequest { request in
    await myBilling.purchase(request.productId)
}
Encore.shared.onPassthrough { placementId in
    proceedWithDefaultFlow(placementId)
}

// Anywhere, anytime
Encore.placement("cancel_flow").show()

On every platform, re-registering a handler replaces the previous one — no double-firing. You can call the setters multiple times safely.

Decision tree

Does the show() call site have direct access to your purchase logic
AND your decline/continuation logic?

├── YES -> Async-result (RECOMMENDED)
│         let result = await Encore.placement(id).show()
│         switch result { case .granted: ... case .notGranted: ... }
│
└── NO  -> Handler pattern
          - Register Encore.shared.onPurchaseRequest at app init
          - Register Encore.shared.onPassthrough at app init
          - Guarantee handlers are registered BEFORE any show() call

When async-result wins

The trigger lives next to the purchase code (e.g. a Cancel Subscription button in your settings screen that already imports your billing client)
Code that should run on both branches — analytics, navigation, cleanup — would otherwise duplicate across handler + caller
You want the post-show flow to read top-to-bottom without hopping between files

When handlers win

The trigger is a third-party paywall delegate (Superwall, RevenueCat) where you don’t control the call site
Purchase code lives in a ViewModel or DI scope not visible from a UI button action
Multiple show() sites share post-purchase logic and you’d rather centralize it

Mixing is fine

Handlers can fire for cross-cutting telemetry while async results drive control flow. The two patterns coexist on the same placement — the handler pattern is the default the SDK falls back to whenever the call site doesn’t act on the returned result.

Common scenarios

Scenario	Pattern
`Cancel` button in your subscription settings (you have purchase code)	Async-result
Encore presented from a Superwall delegate that can’t see your VM	Handler
Multiple `show()` sites sharing one billing path	Handler
Single `show()` call with branch-specific UI navigation	Async-result
Cross-cutting analytics on every offer regardless of caller	Handler (alongside async-result)

Cross-cutting concerns

Re-registration is replace, not append

All five SDKs replace the previous handler when you call the setter again. You don’t need to defensively unsubscribe. On React Native, the handler setters return an unsubscribe function for component-lifecycle convenience — useful but not required to prevent double-fires.

Async wrapping at non-async triggers

show() is async on every platform. When the trigger is a synchronous callback (SwiftUI Button action body, Compose onClick, an event listener) you wrap the call in the platform’s standard async launcher:

Platform	Wrapper
Swift / SwiftUI	`Task { ... }`
Android / Compose	`lifecycleScope.launch { ... }` or `coroutineScope.launch`
Flutter	`unawaited(...)` or `await` from an `async` callback
React Native	`await` from an `async` event handler
Web	`await` from an `async` function

Web has no global handlers

The Web SDK doesn’t expose onPurchaseRequest / onPassthrough — browsers handle the purchase via redirects/forms, so there’s no purchase-delegation contract to register. Use the async-result of Encore.placement(id).show() for control flow, and per-placement callbacks (Encore.placement(id).onGranted(...).onNotGranted(...)) for cross-cutting telemetry.

Order of operations for handlers

If you go with handlers, register them before any show() call. The simplest place is right after configure() at app launch. Late registration risks a placement firing into the void.

Per-platform guides

iOS

Swift code for both patterns, Task wrapping, replace semantics

Android

Kotlin code, lifecycleScope.launch, sealed-class PresentationResult

React Native

TypeScript code, PlacementResult.status, unsubscribe semantics

Flutter

Dart code, EncorePresentationResult switch, setOn* naming

Web

Async-result + per-placement callbacks (no global handlers)

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK