Updating to 2.x

Overview

SDK 2.0 is a breaking release that makes the integration surface simpler and harder to misuse:

show() returns one result record and never throws. Errors arrive as values on the result instead of as exceptions.
Purchases run through a registered EncorePurchaseController. The SDK never runs purchase code you didn’t write; the built-in Play Billing fallback is removed.
Global handler closures are retired. Results are values at the call site; passive observation moves to the Encore.outcomes stream.
The callback form is always delivered on the main thread; the suspending form resumes in your caller’s context. show() itself is safe to call from any thread or scope.

2.0 removes the 1.x legacy surface outright rather than deprecating it, so every call site that needs attention fails to compile. Work through the steps below until the project builds, then run the verification checklist. The removed API table maps every 1.x symbol to its replacement.

Step 1: Update the dependency

dependencies {
    implementation("com.encorekit:encore:2.0.0")
}

Sync and build. The compile errors that appear are your migration worklist; each one corresponds to a step below.

Step 2: Register a purchase controller

This is the largest change. In 1.x, purchases ran through the onPurchaseRequest closure, and if no handler was registered the SDK bought the product itself through Play Billing and reported it via onPurchaseComplete. 2.0 removes the closure, the completion callback, and the built-in Play Billing fallback: that fallback bypassed whatever receipt validation, restore handling, and entitlement bookkeeping your app already has, and it made a missing registration look like a working purchase instead of a misconfiguration. Implement the controller and pass it to configure():

class RevenueCatController : EncorePurchaseController {
    override suspend fun purchase(
        activity: Activity,
        request: PurchaseRequest,
    ): EncorePurchaseResult {
        return try {
            val product = Purchases.sharedInstance
                .awaitGetProducts(listOf(request.productId))
                .firstOrNull() ?: error("Product not in RC catalog: ${request.productId}")
            Purchases.sharedInstance.awaitPurchase(
                PurchaseParams.Builder(activity, product).build()
            )
            EncorePurchaseResult.Purchased
        } catch (e: PurchasesTransactionException) {
            if (e.userCancelled) EncorePurchaseResult.Cancelled else throw e
        }
    }
}

Encore.shared.configure(
    context = this,
    apiKey = "pk_...",
    purchaseController = RevenueCatController(),
)

class AppPurchases(private val billing: MyBillingStack) : EncorePurchaseController {
    // Runs on Dispatchers.Main.immediate. Throw for real failures; map
    // "user cancelled" to Cancelled. Do not retain or finish the activity.
    override suspend fun purchase(
        activity: Activity,
        request: PurchaseRequest,
    ): EncorePurchaseResult {
        return when (billing.purchase(activity, request.productId, request.promoOfferId)) {
            MyOutcome.Success -> EncorePurchaseResult.Purchased
            MyOutcome.Cancelled -> EncorePurchaseResult.Cancelled
            MyOutcome.Deferred -> EncorePurchaseResult.Pending // parental approval / SCA
        }
    }
}

Encore.shared.configure(
    context = this,
    apiKey = "pk_...",
    purchaseController = AppPurchases(billing),
)

Return Purchased, Cancelled, or Pending; throw for real failures. The full contract is in EncorePurchaseController.

Step 3: Update show() call sites

show() returns the full result record and never throws. The 1.x scope-taking overloads become an explicit callback form:

// 1.x: fire-and-forget with a scope
Encore.placement("cancel_flow").show(activity, lifecycleScope)

// 2.0: callback form; delivered exactly once, on the main thread
Encore.placement("cancel_flow").show(activity) { 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. The suspending form works from any thread or scope:

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

Step 4: Update result handling

1.x modeled the result as a flat triad (Completed, Dismissed(reason), NoOffers), which forced a claim and a purchase to compete for a single winning case. 2.0 records the facts independently: 2.0 splits the result into NotPresented(reason) and Presented(outcome); see PresentationResult for the full shape. The record carries raw facts only: there is no SDK-computed “unlocked” verdict, so your integration decides what a claim means. Branch on the facts your flow cares about:

val result = Encore.placement("paywall").show(activity)
if (result.claim != null || result.publisher == PublisherOutcome.Purchased) {
    grantAccess()   // the user claimed an offer or completed your purchase
} else {
    result.error?.let(::log)   // presentation failures are values
    runOriginalFlow()          // dismissed, declined, no offers, control cohort, ...
}

result.claim surfaces the claimed offer whenever the advertiser funnel reached Claimed or Verified; read result.advertiser directly to tell the two apart. When the mechanism detail matters, read the record:

when (result) {
    is PresentationResult.NotPresented -> log(result.reason)
    is PresentationResult.Presented -> {
        result.claim?.let { syncEntitlement(it.campaignId, it.transactionId) }
        if (result.outcome.publisher == PublisherOutcome.Purchased) refreshSubscriptions()
        log("closed via ${result.outcome.dismissal.value}")
    }
}

Step 5: Replace global callbacks with the outcomes stream

onPassthrough and onPurchaseComplete are removed. Handle fallback inline at the call site (Step 4), and move passive observation (analytics, logging, cross-cutting state) to the Encore.outcomes stream:

// Application.onCreate, right after configure. There is no replay, so
// subscribe at startup.
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) // strict-mode cross-launch settlement
        }
    }
}

Every show() resolution lands on Encore.outcomes, including NotPresented, plus strict-unlock verifications that settle on a later launch.

Removed APIs at a glance

1.x surface	2.0 replacement
`PresentationResult.Completed(offerId, campaignId)`	`Presented(outcome)` with `outcome.advertiser` = `Claimed(offer)` / `Verified(offer)`
`PresentationResult.Dismissed(reason)`	`Presented(outcome)`; `outcome.dismissal` is the `DismissReason`
`PresentationResult.NoOffers`	`NotPresented(NoOffers)`
`DismissReason.USER_CLOSED` etc.	`DismissReason.UserTappedClose` etc.: one enum, raw values are the wire values
`onPurchaseRequest { }`	`EncorePurchaseController` at `configure()`
`onPurchaseComplete { }`	`result.publisher` `== PublisherOutcome.Purchased` / `Encore.outcomes`
`onPassthrough { }`	Inline fallback off `result.claim == null && result.publisher != PublisherOutcome.Purchased`
`Encore.shared.purchaseSubscription(...)` + Play Billing fallback	Removed; your controller owns the purchase, so you already have the result
`BillingPurchaseResult`	Removed; the transaction belongs to your billing stack
`show(activity, scope)` / `show(scope)`	`show(activity) { result -> }` / `show { result -> }`
`placements.notifyResult` observation	`Encore.outcomes` (SharedFlow)

Behavior changes to be aware of

These compile fine but behave differently at runtime:

Claim-then-purchase records both funnels. 1.x collapsed the flow to a single winner. 2.0 carries advertiser = Claimed(...) and publisher = Purchased side by side, and the result is delivered once, after the purchase resolves (later than 1.x fired its callbacks).
Strict mode records the claim, and verification upgrades it. With UnlockMode.Strict, the record says advertiser = Claimed(...) immediately, and in-session verification upgrades it to Verified(...). A claim that ends unverified re-verifies across launches and surfaces as PlacementOutcome.StrictUnlockVerified on Encore.outcomes; the persistence rules are in unlock modes.
The offer sheet no longer recreates on rotation or dark-mode changes, so mid-flow configuration changes can’t produce spurious results, and a dead flow (killed sheet) resolves as Presented(dismissal = Interrupted) instead of wedging show() in “already presenting”.
Gesture dismissal now reports swipe_dismiss in analytics (previously lumped into close_button). On the SDUI sheet, which is the default render path, this covers both dragging the sheet down and tapping outside it; on the native fallback sheet only dragging reports it. All other event names and close-reason strings are unchanged on the wire.

Backup rules caveat for strict mode. The SDK ships an include-only Auto Backup allowlist: it includes com.encorekit.encore.xml (the cross-install NCL identity file) and excludes its pending-claims file by omission. If your app replaces the SDK’s backup rules wholesale (tools:replace on the manifest attributes), keep com.encorekit.encore.xml included and keep com.encorekit.encore.pending.xml out of your include list. Runtime guards back the pending-claims exclusion up either way.

New in 2.x with no migration required: placements can declare a claim-only reward surface (Encore.placement("streak_complete").useCase(UseCase.REWARD_USERS)) with per-presentation headline() / subheadline() copy overrides. The surface fires after the user has already done something worth celebrating, and reward presentations never run a purchase and never show the paywall layout.

Verify the migration

Confirm each of these before shipping:

The project compiles with no references to removed 1.x APIs.
If a subscription product is configured for your app, an EncorePurchaseController is registered at configure time.
Every fallback path (your original paywall or flow) runs off the raw facts (result.claim == null && result.publisher != PublisherOutcome.Purchased), not a removed callback.
If you subscribe to Encore.outcomes, the subscription starts at app startup (there is no replay).
Test the full flow on a device: present a placement, claim an offer, complete a purchase, and dismiss without acting. Each path should resolve exactly once with the result you expect.

If you hit anything this guide doesn’t cover, reach out to admin@encorekit.com.

iOS

Android

Web

Bridges

Updating to 2.x

Overview

Step 1: Update the dependency

Step 2: Register a purchase controller

Step 3: Update show() call sites

Step 4: Update result handling

Step 5: Replace global callbacks with the outcomes stream

Removed APIs at a glance

Behavior changes to be aware of

Verify the migration

​Overview

​Step 1: Update the dependency

​Step 2: Register a purchase controller

​Step 3: Update show() call sites

​Step 4: Update result handling

​Step 5: Replace global callbacks with the outcomes stream

​Removed APIs at a glance

​Behavior changes to be aware of

​Verify the migration

Overview

Step 1: Update the dependency

Step 2: Register a purchase controller

Step 3: Update show() call sites

Step 4: Update result handling

Step 5: Replace global callbacks with the outcomes stream

Removed APIs at a glance

Behavior changes to be aware of

Verify the migration