Registers a handler invoked when Encore’s offer flow completes and a purchase is needed. The handler receives the App Store product ID and placement ID and should 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 (_ productId: String, _ placementId: String) async throws -> Void)
Parameters
| Name | Type | Description |
|---|
handler | (String, String) async throws -> Void | Async throwing callback receiving (productId, placementId). Trigger your purchase flow here. |
Returns
Returns the Encore instance for chaining.
When It Fires
| Scenario | Fires? |
|---|
| User accepts an offer | Yes |
| User dismisses without purchasing | No — see onPassthrough() |
| No offer available for this user | No — see onPassthrough() |
Usage
StoreKit
RevenueCat
Adapty
Qonversion
Custom
Encore.shared.onPurchaseRequest { productId, placementId in
guard let product = try await Product.products(for: [productId]).first else { return }
let result = try await product.purchase()
// StoreKit 2 handles the rest
}
Encore.shared.onPurchaseRequest { productId, placementId in
let products = try await Purchases.shared.products([productId])
guard let product = products.first else { return }
try await Purchases.shared.purchase(product: product)
}
Encore.shared.onPurchaseRequest { productId, placementId in
let products = try await Adapty.getPaywallProducts(paywall: paywall)
guard let product = products.first(where: { $0.vendorProductId == productId }) else { return }
try await Adapty.makePurchase(product: product)
}
Encore.shared.onPurchaseRequest { productId, placementId in
try await Qonversion.shared().purchaseProduct(productId: productId)
}
Encore.shared.onPurchaseRequest { productId, placementId in
// Your subscription manager here
// productId: App Store product ID to purchase
// placementId: Which placement triggered this (optional)
try await yourManager.purchase(productId)
}
Chained with onPassthrough
Encore.shared
.onPurchaseRequest { productId, placementId in
guard let product = try await Product.products(for: [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).