Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt

Use this file to discover all available pages before exploring further.

Registers a handler invoked when Encore’s offer flow completes and a purchase is needed. The handler receives a PurchaseRequest containing the product ID, placement ID, and optional promotional offer ID. Use it to trigger the purchase via your subscription manager (e.g. StoreKit, RevenueCat).
Set onPurchaseRequest before calling placement().show(). If not set, Encore will fall back to a native StoreKit purchase automatically. For best results with 3P subscription managers, set this handler to purchase through your provider directly.

​
Signature

public func onPurchaseRequest(_ handler: @escaping (PurchaseRequest) async throws -> Void) -> Encore

​
Parameters

NameTypeDescription
handler(PurchaseRequest) async throws -> VoidAsync throwing callback receiving a PurchaseRequest. Trigger your purchase flow here.

​
PurchaseRequest Properties

PropertyTypeDescription
productIdStringThe App Store product identifier to purchase
placementIdString?Which placement triggered this purchase, if any
promoOfferIdString?Promotional offer identifier to apply, or nil for standard purchases

​
Returns

Returns the Encore instance for chaining.

​
When It Fires

ScenarioFires?
User accepts an offerYes
User dismisses without purchasingNo — see onPassthrough()
No offer available for this userNo — see onPassthrough()

​
Usage

Encore.shared.onPurchaseRequest { purchaseRequest in
    guard let product = try await Product.products(for: [purchaseRequest.productId]).first else { return }
    let result = try await product.purchase()
    // StoreKit 2 handles the rest
}

​
Chained with onPassthrough

Encore.shared
    .onPurchaseRequest { purchaseRequest in
        guard let product = try await Product.products(for: [purchaseRequest.productId]).first else { return }
        let result = try await product.purchase()
    }
    .onPassthrough { placementId in
        // User didn't purchase — continue original flow
        proceedWithCancellation()
    }
The handler is an async throws function, so you can call other async APIs (like StoreKit or network requests) directly inside it.
When no onPurchaseRequest handler is set, Encore handles purchases via native StoreKit 2 automatically. Use onPurchaseComplete to sync these transactions with providers that don’t auto-detect StoreKit transactions (e.g., Adapty, Qonversion).