Presenting Offers

Overview

Encore lets you present a premium brand offer (a real perk a brand funds to acquire customers, such as a free trial, discount, or credit) at critical moments like cancellation flows or feature paywalls. You call .show() wherever you need an offer; it returns one complete result record, and it never throws.

Present an offer

show() is a suspend function that resolves once the presentation is over. It is safe to call from any thread or scope:

lifecycleScope.launch {
    val result = Encore.placement("cancellation_flow").show()
    val converted = result.claim != null || result.publisher == PublisherOutcome.Purchased
    if (converted) {
        // The user claimed an offer or completed your purchase
        finish()
    } else {
        proceedWithCancellation()
    }
}

The result carries raw facts: result.claim is the claimed offer (or null), result.publisher is your purchase funnel’s outcome, and result.error surfaces presentation failures as values. There is no SDK-computed “unlocked” verdict; your integration branches on the facts your flow cares about. See PresentationResult for the full record.

Never block the user’s original action. When the result shows no claim and no purchase (dismissed, no offers, control cohort, error), run your original flow.

Callback form

If the call site isn’t a coroutine, use the callback overload. The callback is delivered exactly once, on the main thread:

Encore.placement("cancellation_flow").show { result ->
    if (result.claim == null && result.publisher != PublisherOutcome.Purchased) {
        proceedWithCancellation()
    }
}

Both forms auto-resolve the current foreground Activity; show(activity) and show(activity) { result -> } overloads are available when you need to bind to a specific Activity.

Handle purchases

If your app has a subscription product configured, register an EncorePurchaseController at configure() time. When a user accepts an offer that leads to a purchase, Encore invokes your controller with the product to buy and awaits your verdict:

Encore.shared.configure(
    context = this,
    apiKey = "pk_...",
    purchaseController = AppPurchases(billing),  // RevenueCat, Play Billing, or your own stack
)

The SDK never runs purchase code you didn’t write: with no controller registered, the claim flow still completes, the result records PublisherOutcome.NotAttempted, and nothing is ever charged. If your app uses Encore offers without a subscription product, no controller is needed.

Observe outcomes passively

For cross-cutting concerns (analytics, logging, entitlement sync) that shouldn’t live at every call site, collect the Encore.outcomes stream. Subscribe at app startup; there is no replay:

appScope.launch {
    Encore.outcomes.collect { outcome ->
        when (outcome) {
            is PlacementOutcome.Presentation ->
                analytics.log("encore_outcome", outcome.placementId, outcome.result)
            is PlacementOutcome.StrictUnlockVerified ->
                grantEntitlement(outcome.transactionId)
        }
    }
}

Placement IDs

Use meaningful placement IDs to track where offers are triggered in your app:

// In your cancellation flow
lifecycleScope.launch { Encore.placement("cancellation_flow").show() }

// At a premium feature gate
lifecycleScope.launch { Encore.placement("premium_feature_gate").show() }

// During onboarding
lifecycleScope.launch { Encore.placement("onboarding_offer").show() }

Placement IDs appear in your Encore Dashboard analytics, letting you measure conversion rates per placement.

Await the result at the call site by default; see Android Integration Patterns for the callback and outcomes-stream shapes.

Next Steps

Add Subscription Product - Create a Google Play subscription product and connect it to Encore
Configure Analytics - Track offer performance and measure impact

iOS

Android

Web

Bridges

Presenting Offers

Overview

Present an offer

Callback form

Handle purchases

Observe outcomes passively

Placement IDs

Next Steps

​Overview

​Present an offer

​Callback form

​Handle purchases

​Observe outcomes passively

​Placement IDs

​Next Steps

Overview

Present an offer

Callback form

Handle purchases

Observe outcomes passively

Placement IDs

Next Steps