placement() - Encore SDK

Purpose

Create and present Encore offers using a fluent API that fits naturally in SwiftUI and UIKit. Purchase handling and passthrough logic are managed by app-level handlers — see onPurchaseRequest() and onPassthrough().

Signature

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

placement(_:) returns a value conforming to PlacementBuilderProtocol. Build it from any thread, then call show():

public protocol PlacementBuilderProtocol {
    var id: String { get }

    /// Presents the offer sheet and returns the outcome. Throws on transport/SDK errors.
    func show() async throws -> PresentationResult

    /// Fire-and-forget presentation (wraps the async form in a Task).
    func show()
}

Encore.shared.placement(_:) and the static Encore.placement(_:) are equivalent — the static form just 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 throws`	None	Presents the offer sheet and returns a `PresentationResult`. Throws an `EncoreError` on transport / SDK failure. Presentation runs on the main actor automatically.
`show()`	None	Fire-and-forget variant — presents the sheet and discards the result/errors. Use the `async throws` form when you need the outcome.

Usage Patterns

Cancellation Flow (fire-and-forget)

Button("Cancel Subscription") {
    Encore.shared.placement("cancellation_flow").show()
}

Provide a placement ID to identify this specific placement in analytics and in your onPassthrough handler.

Async/Await Pattern

Button("Cancel Subscription") {
    Task {
        do {
            let result = try await Encore.shared.placement("cancellation_flow").show()
            switch result {
            case .granted(let entitlement):
                print("User accepted: \(entitlement)")
            case .notGranted(let reason):
                proceedWithCancellation(reason: reason)
            }
        } catch let error as EncoreError {
            // Transport / SDK failure — never block the user.
            print("Encore error: \(error.errorDescription ?? "")")
            proceedWithCancellation(reason: nil)
        }
    }
}

show() is @MainActor-driven — presentation always happens on the main thread. From a synchronous SwiftUI Button or UIKit @IBAction, wrap the await call in a Task { }.

​Purpose

​Signature

​Methods

​Usage Patterns

​Cancellation Flow (fire-and-forget)

​Async/Await Pattern

Purpose

Signature

Methods

Usage Patterns

Cancellation Flow (fire-and-forget)

Async/Await Pattern