placement()

Purpose

Create and present Encore offers using a fluent builder API. Fetches available offers for the current user and presents them in a native offer sheet. show() returns the complete PresentationResult record and never throws.

Signature

// Create a placement
fun placement(id: String? = null): PlacementBuilder

class PlacementBuilder {
    // Builder configuration
    fun useCase(useCase: UseCase): PlacementBuilder
    fun headline(text: String): PlacementBuilder
    fun subheadline(text: String): PlacementBuilder

    // Present (suspend); safe to call from any thread or scope
    suspend fun show(activity: Activity): PresentationResult
    suspend fun show(): PresentationResult

    // Present (callback); delivered exactly once, on the main thread
    fun show(activity: Activity, onResult: (PresentationResult) -> Unit)
    fun show(onResult: (PresentationResult) -> Unit)
}

Methods

Method	Parameters	Description
`placement()`	`id: String?`	Creates a placement with optional identifier. If omitted, auto-generates a unique ID
`useCase()`	`useCase: UseCase`	Which product surface this presentation is. Defaults to `UseCase.REDUCE_CHURN`; see Use cases
`headline()`	`text: String`	Overrides the headline for this presentation. The whole string, not a fragment: you own the copy end to end, so localize and pluralize however your app already does. A blank string is ignored
`subheadline()`	`text: String`	Sibling of `headline()` for the line beneath it
`show(activity)`	`activity: Activity`	Suspending; fetches offers, presents the sheet, and resolves once the record seals. Returns `PresentationResult`
`show()`	none	Suspending; auto-resolves the current foreground Activity. Nothing in the foreground resolves to `NotPresented(NoForegroundActivity)`
`show(activity) { }` / `show { }`	`onResult: (PresentationResult) -> Unit`	Callback forms; `onResult` is delivered exactly once, on the main thread, regardless of foreground state

show() never throws: every failure is a value on the result, including calling before configure() (NotPresented(NotConfigured)). The suspending forms are safe to call from any thread or scope; the body runs on a background dispatcher and UI work is hopped to Main internally.

Copy overrides resolve in strict priority order, first one set wins: this override, then the copy Encore resolved for your app, then the shipped template default. A blank string is ignored, so the chain falls through rather than rendering an empty line. See Where the copy comes from.

Use cases

A use case selects which template the backend resolves and which funnel the presentation is counted in. It is a different axis from the placement ID: one use case holds many placements.

Case	Description
`UseCase.REDUCE_CHURN`	Second-chance monetization of a paywall decline. The default
`UseCase.REWARD_USERS`	Rewarding a user after something they already did (a completed purchase, a milestone, a streak, a level), never as a way to sell. Claim-only: no in-app purchase runs anywhere in the path, and it never falls back to the paywall layout. If the use case is not enabled for your app, the result is `NotPresented(UseCaseUnavailable)`, a correct no-op

Each case carries a fixed wire value ("churn-intervention" and "post-action-reward") that the backend stores and that analytics splits the funnel on. The constant names are the API surface; the wire values are the contract.

Usage

Suspend (recommended)

lifecycleScope.launch {
    val result = Encore.placement("cancel_flow").show()
    val converted = result.claim != null || result.publisher == PublisherOutcome.Purchased
    if (converted) grantAccess() else proceedWithCancellation()
}

Callback form

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

Result delivery is not foreground-gated: the callback fires even if your Activity backgrounded mid-flow. Don’t touch views without checking your own lifecycle.

Reward surface

lifecycleScope.launch {
    Encore.placement("streak_complete")
        .useCase(UseCase.REWARD_USERS)
        .headline("That's three days in a row staying informed 🔥")
        .subheadline("Here's a little thank you from us")
        .show()
}

With named placements for analytics

// Placement ID appears in your Dashboard analytics and on Encore.outcomes
Encore.placement("onboarding_upsell").show { }
Encore.placement("cancel_flow").show { }
Encore.placement("settings_upgrade").show { }

Provide a descriptive placement ID to identify this specific placement in your analytics. If omitted, a random ID is generated.

Appearance

The sheet renders in light, dark, or automatic appearance, following the appearance mode configured for your app in the Encore dashboard. Automatic is the default: the sheet follows your host app’s theme, falling back to the device setting when that theme can’t be read. The sheet runs in its own Activity, so this is what keeps it visually part of the app it presents over rather than following the device past a host that pins its own style.

Claim CTA toggle

Encore.shared.isClaimEnabled controls whether the claim CTA on offer cards is tappable. It is runtime-mutable by design: flip it to false to gray out and disable the claim button, and back to true to re-enable it.

Encore.shared.isClaimEnabled = false

PresentationResult: the returned record and its fact readers
Encore.outcomes: every resolution also lands on the passive stream
Integration Patterns: choosing between the suspend and callback forms

iOS

Android

Web

Bridges

Purpose

Signature

Methods

Use cases

Usage

Suspend (recommended)

Callback form

Reward surface

With named placements for analytics

Appearance

Claim CTA toggle

​Purpose

​Signature

​Methods

​Use cases

​Usage

​Suspend (recommended)

​Callback form

​Reward surface

​With named placements for analytics

​Appearance

​Claim CTA toggle

​Related

Purpose

Signature

Methods

Use cases

Usage

Suspend (recommended)

Callback form

Reward surface

With named placements for analytics

Appearance

Claim CTA toggle

Related