Targeting Moments

Overview

Encore placements let you present targeted offers at key decision points in your app. Each moment has different user intent and conversion characteristics. Start with the highest-impact moment and expand from there.

Paywall Abandonment (Primary)

The highest-impact moment. A user has seen your paywall and is about to leave without purchasing. Present an Encore offer as a last chance to convert.

// When the user dismisses your paywall
func onPaywallDismissed() {
    Encore.placement("paywall").show()
}

Why this works:

User has already shown purchase intent by viewing the paywall
They’ve seen your pricing — an offer feels like a personalized win
Highest conversion rate of any placement moment

When to trigger:

User taps “X” or swipes to dismiss the paywall
User taps “Not now” or “Maybe later”
User navigates back from a pricing screen

This is the recommended starting point for all new integrations. Get this working first, measure results, then expand to other moments.

Churn Intercept (Secondary)

Catch users who are actively trying to cancel their subscription. Present a retention offer before they complete cancellation.

// When the user taps "Cancel Subscription"
Button("Cancel Subscription") {
    Encore.placement("cancellation_flow").show()
}

Why this works:

User is an existing subscriber — they’ve already paid before
High willingness to stay if given the right incentive
Prevents revenue loss from churn

When to trigger:

User taps a cancel/unsubscribe button in your settings
User navigates to subscription management with cancel intent
Before redirecting to the App Store subscription management page

Your onPassthrough handler is critical here — if the user dismisses the offer, you must let them proceed with cancellation. Never block the cancel flow.

Choosing a Placement ID

Placement IDs identify where in your app the offer was triggered. Use descriptive, consistent names:

Moment	Placement ID	Description
Paywall abandonment	`paywall`	User dismissed the paywall
Churn intercept	`cancellation_flow`	User initiated cancellation
Feature gate	`feature_gate`	User hit a premium feature wall
Upgrade prompt	`upgrade`	User shown an upgrade path

Placement IDs are used in your Encore dashboard to track conversion by moment and optimize offer targeting.

Handling Results

Regardless of which moment you target, the same handlers apply:

// Handle purchases (registered once at app init)
Encore.shared.onPurchaseRequest { purchaseRequest in
    // Purchase the product through your subscription manager
}

// Handle dismissals (registered once at app init)
Encore.shared.onPassthrough { placementId in
    // Resume the user's original flow
    // e.g., proceed with cancellation, dismiss paywall, etc.
}

See onPurchaseRequest and onPassthrough for full API details.

Promotional Offer Handling

For retention moments like churn intercept, Encore can include a promotional offer with the purchase request. When a promotional offer is configured in your Encore dashboard, the PurchaseRequest object will contain a promoOfferId alongside the productId. Your onPurchaseRequest handler must apply this offer during purchase.

Promotional offers are configured in App Store Connect and linked through your Encore dashboard. The promoOfferId is only present when Encore determines the user should receive a promotional offer — standard purchases will have promoOfferId set to nil.

How you handle the promotional offer depends on your subscription manager:

StoreKit
RevenueCat
Adapty
Qonversion

When no onPurchaseRequest handler is set, Encore handles promotional offer signing and purchase automatically through native StoreKit. This is the recommended approach for apps using StoreKit directly.To enable automatic signing, provide your In-App Purchase key in the Encore dashboard under Entitlements → Promotional Offer Setup. See Create a Promotional Offer for setup instructions.

If you set a custom onPurchaseRequest handler, Encore will not sign offers automatically. You must handle promo offer signing yourself using StoreKit’s Product.SubscriptionOffer APIs. Only set a custom handler if your app requires it (e.g., when routing purchases to a third-party manager).

Manually check for the promotional offer, sign it through RevenueCat, and fall back to a standard purchase if the user isn’t eligible.

Encore.shared.onPurchaseRequest { purchaseRequest in
    guard let product = try await Purchases.shared.products([purchaseRequest.productId]).first else { return }
    if let promoOfferId = purchaseRequest.promoOfferId,
        let promoDiscount = product.discounts.first(where: { $0.offerIdentifier == promoOfferId }) {
        do {
            let offer = try await Purchases.shared.promotionalOffer(
                forProductDiscount: promoDiscount, product: product
            )
            let transaction = try await Purchases.shared.purchase(product: product, promotionalOffer: offer)
            print(transaction)
        } catch {
            // Promo failed (ineligible, network error, etc.) — fall back to standard purchase
            let transaction = try await Purchases.shared.purchase(product: product)
            print(transaction)
        }
    } else {
        let transaction = try await Purchases.shared.purchase(product: product)
        print(transaction)
    }
}

Your local StoreKit configuration file must be synced with App Store Connect. Promotional offers will not work if it is out of sync.

Adapty automatically presents the promotional offer if the user is eligible (when configured correctly in the Adapty dashboard). Falls back to a standard purchase with an introductory offer.

Encore.shared.onPurchaseRequest { purchaseRequest in
    let paywall = try await Adapty.getPaywall(placementId: "YOUR_PAYWALL_PLACEMENT_ID")
    let products = try await Adapty.getPaywallProducts(paywall: paywall)
    guard let product = products.first(where: {
        $0.vendorProductId == purchaseRequest.productId
    }) else {
        return
    }
    try await Adapty.makePurchase(product: product)
}

Adapty does not fall back to StoreKit — products and offers must exist in Adapty. Sync products in the Adapty dashboard before use, and configure the promotional offer there (it does not sync from App Store Connect automatically).

Manually resolve the promotional discount from the Qonversion product catalog and apply it at purchase time. Falls back to a standard purchase if the promo is unavailable.

Encore.shared.onPurchaseRequest { purchaseRequest in
    guard let products = try? await Qonversion.shared().products(),
    let product = products.first(where: { $0.value.storeID == purchaseRequest.productId })?.value else { return }

    if let promoOfferId = purchaseRequest.promoOfferId,
      let discount = product.skProduct?.discounts.first(where: { $0.identifier == promoOfferId }),
      let promoOffer = try? await withCheckedThrowingContinuation({ (c: CheckedContinuation<Qonversion.PromotionalOffer, Error>) in
          Qonversion.shared().getPromotionalOffer(for: product, discount: discount) { offer, err in
              if let offer { c.resume(returning: offer) }
              else { c.resume(throwing: err ?? NSError(domain: "Qonversion", code: -1)) }
          }
      }) {
      let opts = Qonversion.PurchaseOptions()
      opts.promoOffer = promoOffer
      try await Qonversion.shared().purchaseProduct(product, options: opts)
    } else {
      try await Qonversion.shared().purchaseProduct(product)
    }
}

Qonversion does not fall back to StoreKit — products must be synced first. Click “Sync from Stores” in the Qonversion dashboard to import your products before using promotional offers.

Next Steps

Present Offers (Quickstart) — Basic integration walkthrough
Using RevenueCat — RevenueCat-specific purchase handling
Using Superwall — Superwall-specific purchase handling
Using Qonversion — Qonversion-specific purchase handling

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK

Overview

Paywall Abandonment (Primary)

Churn Intercept (Secondary)

Choosing a Placement ID

Handling Results

Promotional Offer Handling

Next Steps

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK

​Overview

​Paywall Abandonment (Primary)

​Churn Intercept (Secondary)

​Choosing a Placement ID

​Handling Results

​Promotional Offer Handling

​Next Steps

Overview

Paywall Abandonment (Primary)

Churn Intercept (Secondary)

Choosing a Placement ID

Handling Results

Promotional Offer Handling

Next Steps