Skip to main content

​
Overview

Encore allows you to present targeted offers to users in exchange for rewards (free trials, discounts, credits) at critical moments like cancellation flows or feature paywalls. The SDK uses a delegation pattern — you register purchase and passthrough handlers, then call .show() wherever you need an offer.

​
Handle Offer Results

Before presenting offers, register handlers that tell the SDK how to process purchases and what to do when a user dismisses. Register these once in Application.onCreate(), after configure().

​
Register onPurchaseRequest

Called when a user accepts an offer. Use this to trigger a purchase via Google Play Billing, RevenueCat, Adapty, or your own billing implementation. 
Encore.shared.onPurchaseRequest { productId, placementId ->
    // Route to RevenueCat, Adapty, or your billing implementation
    billingManager.purchase(productId)
}

​
Register onPassthrough

Called when the user dismisses the offer or no offers are available. Use this to resume the user’s original action (e.g., proceed with cancellation). 
Encore.shared.onPassthrough { placementId ->
    // Resume your original user flow
    proceedWithCancellation()
}

​
onPurchaseComplete (Optional)

Only needed when you don’t set an onPurchaseRequest handler, or when integrating with subscription managers that don’t auto-detect purchases (e.g., Adapty, Qonversion). RevenueCat and Superwall auto-detect purchases and don’t need this callback. 
Encore.shared.onPurchaseComplete { productId, placementId ->
    // Sync purchase state with your subscription manager
}

​
Summary

CallbackWhen it firesRequired?
onPurchaseRequestUser accepts the offerYes
onPassthroughUser dismisses or no offers availableYes
onPurchaseCompletePurchase finishes (for managers that don’t auto-detect)Optional
Both onPurchaseRequest and onPassthrough must be registered before presenting any placements.

​
Presenting an Offer

lifecycleScope.launch {
    Encore.placement("cancellation_flow").show(activity)
}

​
Fire-and-Forget

For cases where you don’t need to await the result: 
Encore.placement("cancellation_flow").show(this, lifecycleScope)
That’s it — when the user accepts an offer, your onPurchaseRequest handler fires. When they dismiss or no offers are available, onPassthrough fires.

​
Placement IDs

Use meaningful placement IDs to track where offers are triggered in your app: 
// Cancellation flow
Encore.placement("cancellation_flow").show(activity)

// Feature paywall
Encore.placement("premium_feature_gate").show(activity)

// Onboarding
Encore.placement("onboarding_offer").show(activity)
Placement IDs appear in your Encore Dashboard analytics, letting you measure conversion rates per placement.

​
Next Steps