Presenting Offers

Overview

Encore presents a premium brand offer (a real perk a brand funds to acquire customers, such as a free trial, discount, or credit) at a moment you choose. Start with Reward Users: a reward sheet at a moment the user just earned, such as a completed purchase, a streak, or a milestone, at no cost to you. The other use case, Reduce Churn, presents offers in a cancel flow or after a paywall decline.

Present an offer

show() is a suspend function that resolves once the presentation is over, with one complete result record, and it never throws. It is safe to call from any thread or scope:

Reward Users
Reduce Churn

lifecycleScope.launch {
    val result = Encore.placement("streak_day_7")
        .useCase(UseCase.REWARD_USERS)
        .headline("Nice work, Sam!")   // optional; falls back to the copy resolved for your app
        .show()
    result.claim?.let { claim ->
        // The user claimed an offer. Keep claim.transactionId; it carries the attribution.
        claim.transactionId?.let(::persistClaim)
    }
    // Every other result: carry on with your own celebration screen.
}

Select UseCase.REWARD_USERS on every reward placement. A reward placement never runs a purchase and never falls back to the paywall layout, so it needs no subscription product and no purchase controller. The walkthrough, including per-call copy, is the Reward Placements guide.

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()
    }
}

A placement that omits useCase() is a Reduce Churn placement. 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.

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. Contracts: placement() · PresentationResult.

result.claim means the user tapped through to an offer, not that they finished it. To pay your own prize for trying an offer, see Reward for Trying (SDK 2.3.0+).

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("streak_day_7").useCase(UseCase.REWARD_USERS).show { result ->
    result.claim?.let { claim ->
        // The user claimed an offer.
    }
}

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

This section applies to Reduce Churn placements only. A reward placement never runs a purchase, so an app that presents only reward placements can skip it. 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:

// When the user keeps a streak
lifecycleScope.launch {
    Encore.placement("streak_day_7").useCase(UseCase.REWARD_USERS).show()
}

// After a completed purchase
lifecycleScope.launch {
    Encore.placement("purchase_complete").useCase(UseCase.REWARD_USERS).show()
}

// In your cancellation flow (Reduce Churn)
lifecycleScope.launch { Encore.placement("cancellation_flow").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.

Bring users back to finish their gift

Put a Claim Reminder on your home tab. It stays hidden until the user claims a gift, then reminds them to finish. Once they do, it thanks them or steps aside. Encore manages that. You can also put a Gifts Button on your reward screen, so users can open their gifts there whenever offers are waiting. Both need version 2.4.0 or later of the SDK. See the trigger components quickstart.

Next Steps

Reward Placements - Reward a user at a moment they just earned, with copy you set per call
Configure Analytics - Track offer performance and measure impact
Add Subscription Product - Reduce Churn only: create a Google Play subscription product and connect it to Encore

iOS

Android

Web

Bridges

Presenting Offers

Overview

Present an offer

Callback form

Handle purchases

Observe outcomes passively

Placement IDs

Bring users back to finish their gift

Next Steps

​Overview

​Present an offer

​Callback form

​Handle purchases

​Observe outcomes passively

​Placement IDs

​Bring users back to finish their gift

​Next Steps

Overview

Present an offer

Callback form

Handle purchases

Observe outcomes passively

Placement IDs

Bring users back to finish their gift

Next Steps