EncorePurchaseController

Every purchase triggered by an Encore offer runs through an EncorePurchaseController your app registers with configure(). The SDK has no built-in billing and never runs purchase code you did not write: your controller owns product lookup, receipt validation, restore handling, and entitlement bookkeeping, exactly as it does for every other purchase in your app. Encore controls when a purchase happens; you own how.

Definition

abstract class EncorePurchaseController {
  // Called when a user accepts an offer that carries an in-app purchase.
  // Awaited: the offer flow waits for your answer. Throw for a real failure.
  Future<EncorePurchaseResult> purchase(EncorePurchaseRequest request);
}

enum EncorePurchaseResult {
  purchased, // the purchase completed
  cancelled, // the user backed out
  pending,   // the store deferred the purchase; it may complete later
}

Each native plugin owns the native conformance and forwards every request over the method channel, waiting until your Dart code answers.

Throwing records a failure. A throw lands on the result as EncorePublisherOutcome.failed, and the flow continues. Map your billing layer’s “user cancelled” error to cancelled rather than throwing it.
An unrecognized answer is a failure, never purchased, because a phantom success would grant access nobody paid for.
The controller survives reset(). It is app-level wiring, not user state.

pending is a first-class result, not a soft failure. It means Ask to Buy (parental approval) on iOS, or SCA or a pending Play transaction on Android: the user has neither bought nor abandoned, and the store’s eventual webhook is the source of truth. Returning cancelled for a deferred purchase records a sale still in flight as a decline. Route your billing library’s deferred branch to pending.

EncorePurchaseRequest

What your controller receives when Encore needs a purchase.

class EncorePurchaseRequest {
  final String productId;      // store product to purchase
  final String? placementId;   // placement that triggered it
  final String? promoOfferId;  // App Store promotional offer (iOS)
  final String? basePlanId;    // Play base plan to select (Android)
}

Property	Type	Description
`productId`	`String`	The store product identifier to purchase, for example `com.app.monthly_premium`
`placementId`	`String?`	Which placement triggered this purchase. On iOS the SDK generates an ID when the placement had none
`promoOfferId`	`String?`	App Store Connect promotional offer identifier. iOS only; `null` for standard purchases and on Android
`basePlanId`	`String?`	Google Play subscription base plan ID, when the product exposes several. Android only; `null` on iOS and for single-base-plan products

Android’s native controller also hands over the foreground Activity. The plugin keeps it on the native side, since it is valid only for the duration of the call, so one Dart contract covers both platforms.

Implementations

RevenueCat
Custom

import 'package:encore_flutter/encore_flutter.dart';
import 'package:flutter/services.dart';
import 'package:purchases_flutter/purchases_flutter.dart';

class AppPurchases implements EncorePurchaseController {
  @override
  Future<EncorePurchaseResult> purchase(EncorePurchaseRequest request) async {
    // Buys the product's default option. If your Play products expose several
    // base plans, purchase the subscription option matching request.basePlanId.
    final products = await Purchases.getProducts([request.productId]);
    if (products.isEmpty) {
      throw StateError('Unknown product ${request.productId}');
    }
    try {
      await Purchases.purchaseStoreProduct(products.first);
      return EncorePurchaseResult.purchased;
    } on PlatformException catch (e) {
      final code = PurchasesErrorHelper.getErrorCode(e);
      if (code == PurchasesErrorCode.purchaseCancelledError) {
        return EncorePurchaseResult.cancelled;
      }
      if (code == PurchasesErrorCode.paymentPendingError) {
        return EncorePurchaseResult.pending;
      }
      rethrow; // recorded as EncorePublisherOutcome.failed
    }
  }
}

import 'package:encore_flutter/encore_flutter.dart';

class AppPurchases implements EncorePurchaseController {
  AppPurchases(this.billing);

  final BillingService billing; // your app's existing billing layer

  @override
  Future<EncorePurchaseResult> purchase(EncorePurchaseRequest request) async {
    final outcome = await billing.purchase(
      request.productId,
      basePlanId: request.basePlanId,     // Android, optional
      promoOfferId: request.promoOfferId, // iOS, optional
    );
    if (outcome.userCancelled) return EncorePurchaseResult.cancelled;
    if (outcome.deferred) return EncorePurchaseResult.pending;
    return EncorePurchaseResult.purchased;
  }
}

configure(): accepts the controller, and defines what happens when none is registered
EncorePresentationResult: where the controller’s answer lands as publisher

iOS

Android

Web

Bridges

EncorePurchaseController

Definition

EncorePurchaseRequest

Implementations

​Definition

​EncorePurchaseRequest

​Implementations

​Related

Definition

EncorePurchaseRequest

Implementations

Related