placement()

Purpose

Create and present Encore offers using a fluent API that fits naturally in SwiftUI and UIKit. Purchases run through the EncorePurchaseController you register at configure() time.

Signature

@MainActor
public static func placement(_ id: String? = nil) -> any PlacementBuilderProtocol

placement(_:) returns a builder. Configure it with the optional builder methods, then call show():

@MainActor
public protocol PlacementBuilderProtocol {
    var id: String { get }

    /// Presents the offer sheet and returns the outcome. Never throws.
    func show() async -> PresentationResult

    /// Callback form: delivers every outcome (including .notPresented) on the main actor.
    func show(resume: @escaping @Sendable (PresentationResult) -> Void)

    /// Reports when the builder starts and stops loading.
    func onLoadingStateChange(_ callback: @escaping @Sendable (Bool) -> Void) -> Self

    /// Selects the surface to present. Defaults to .reduceChurn.
    func useCase(_ useCase: UseCase) -> Self

    /// Overrides the sheet's headline copy.
    func headline(_ text: String) -> Self

    /// Overrides the sheet's subheadline copy.
    func subheadline(_ text: String) -> Self
}

Encore.shared.placement(_:) and the static Encore.placement(_:) are equivalent; the static form forwards to the shared instance.

Methods

Method	Parameters	Description
`placement(_:)`	`id: String?`	Creates a placement builder with an optional identifier. If omitted, a unique ID is auto-generated.
`show() async`	None	Presents the offer sheet and returns a `PresentationResult`. Never throws; failures arrive as `.notPresented(.error(EncoreError))`.
`show(resume:)`	`(PresentationResult) -> Void`	Callback form. Delivers every outcome, including `.notPresented`, on the main actor.
`onLoadingStateChange(_:)`	`(Bool) -> Void`	Reports when the builder starts and stops loading, so you can show your own spinner.
`useCase(_:)`	`UseCase`	Selects the surface to present. Defaults to `.reduceChurn`.
`headline(_:)`	`String`	Overrides the sheet’s headline copy for this presentation.
`subheadline(_:)`	`String`	Overrides the sheet’s subheadline copy for this presentation.

.presented means the interaction ran: the offer sheet, or on IAP-first variants the purchase sheet that stands in for it. headline(_:) and subheadline(_:) pass the full string through as-is; the SDK never composes copy out of a count. Priority is this override, then the copy Encore resolved for your app, then the shipped template default, and an empty string is ignored so it can’t blank the shipped copy. See Where the copy comes from.

Use cases

public enum UseCase: String, Sendable, CaseIterable, Equatable {
    case reduceChurn = "churn-intervention"   // default
    case rewardUsers = "post-action-reward"
}

The raw values are the wire format the backend stores and that analytics splits the funnel on. The case names are the API surface; the raw values are the contract. .reduceChurn is the default surface for cancel flows and paywall declines. .rewardUsers presents the reward surface after the user has already done something worth celebrating (a completed purchase, a milestone, a streak); it is not a way to sell. It is claim-only: no in-app purchase runs anywhere in the path, and it never falls back to the paywall sheet. See Reward Users. If no enabled variant resolves for the requested use case, show() resolves with .notPresented(.useCaseUnavailable) and no UI appears.

Usage Patterns

Async/await (recommended)

The facade and builder are @MainActor, so call show() from a main-actor context: a SwiftUI button action, a .task, or a UIKit handler. 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, ...
        }
    }
}

Callback form

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

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

There is no fire-and-forget show() in 2.x. Every presentation resolves exactly once, and the resolution is always delivered, so fallback logic can never be silently skipped.

Selecting a use case

let result = await Encore.shared.placement("workout_complete")
    .useCase(.rewardUsers)
    .headline("Nice work!")
    .show()

show() is @MainActor: presentation always happens on the main thread. From nonisolated code, await hops to the main actor automatically and the result still resumes there.

Appearance

The sheet renders in light, dark, or automatic appearance, following the appearance mode configured for your app in the Encore dashboard. Automatic is the default: the presentation window is left unspecified, so the sheet inherits your app’s interface style and switches with it, with no work on your side.

PresentationResult describes everything show() can resolve to.
outcomes is the passive stream every resolution also lands on.
isClaimEnabled gates the claim CTA on the cards this presents.

iOS

Android

Web

Bridges

Purpose

Signature

Methods

Use cases

Usage Patterns

Async/await (recommended)

Callback form

Selecting a use case

Appearance

​Purpose

​Signature

​Methods

​Use cases

​Usage Patterns

​Async/await (recommended)

​Callback form

​Selecting a use case

​Appearance

​Related

Purpose

Signature

Methods

Use cases

Usage Patterns

Async/await (recommended)

Callback form

Selecting a use case

Appearance

Related