Configure the SDK

Overview

As soon as your app launches, configure the SDK with your API Key. This initializes the native Encore SDK on whichever platform the app is running on (iOS or Android). If your Encore flows include an in-app purchase, you register your purchase controller here too, and only here: both native SDKs bind the controller inside configure and expose no setter afterwards.

Initialize Encore in Your App

Call configure early in your app lifecycle, before identifying users or presenting offers. The recommended place is in main():

import 'package:flutter/material.dart';
import 'package:encore_flutter/encore_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Encore.shared.configure(
    apiKey: 'pk_your_api_key_here',
    purchaseController: AppPurchases(),   // your billing stack
  );

  runApp(const MyApp());
}

Replace pk_your_api_key_here with your publishable Live key, which you retrieve yourself from the Dashboard under Settings → Project API Keys (use the Test key for staging and local development).

Can’t find your API key? Open your project’s Settings → Project API Keys in the Encore Dashboard and copy the Live key (or Test for non-production builds).

Register a purchase controller

Encore controls when a purchase happens; your app owns how. Implement EncorePurchaseController and pass the instance to configure. This is the SDK’s only purchase path: it never runs purchase code you did not write.

class AppPurchases implements EncorePurchaseController {
  @override
  Future<EncorePurchaseResult> purchase(EncorePurchaseRequest request) async {
    // request.productId   - store product to purchase
    // request.placementId - which placement triggered this (optional)
    // request.promoOfferId - App Store promotional offer (iOS, optional)
    // request.basePlanId  - Play base plan to select (Android, optional)
    try {
      await mySubscriptionManager.purchase(request.productId);
      return EncorePurchaseResult.purchased;
    } on UserCancelled {
      return EncorePurchaseResult.cancelled;
    } on PurchaseDeferred {
      return EncorePurchaseResult.pending;
    }
    // Throw for a real failure — Encore records it and resolves the
    // presentation with EncorePublisherOutcome.failed.
  }
}

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.The 1.x boolean handler could not express this state, so it reported every deferred purchase as a failure. Returning EncorePurchaseResult.cancelled for a deferred purchase silently misreports revenue, recording a sale that is still in flight as a decline. Route your billing library’s deferred branch to EncorePurchaseResult.pending.

Registration survives reset(): the controller is app-level infrastructure, not user state. If your Encore flows have no in-app purchase, omit the argument. The SDK then never attempts a purchase at all, and every presentation records EncorePublisherOutcome.notAttempted. That is a supported configuration, and a different behavior from registering a controller that always fails.

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

Configuration options

await Encore.shared.configure(
  apiKey: 'pk_your_api_key_here',
  purchaseController: AppPurchases(),
  logLevel: EncoreLogLevel.debug,
  unlock: EncoreUnlockMode.optimistic,
);

Option	Type	Default	Description
`purchaseController`	`EncorePurchaseController?`	`null`	Your purchase path. Omit if your flows include no in-app purchase
`logLevel`	`EncoreLogLevel`	`none`	Logging verbosity. Set back to `none` before shipping
`unlock`	`EncoreUnlockMode`	`optimistic`	How a claim is verified. `strict` verifies server-side and persists unverified claims across launches, surfacing late confirmations as `EncoreStrictUnlockVerified` on `Encore.shared.outcomes`

unlock selects how a claim flow runs, never how a result is read: the presentation record is written identically in both modes.

Next Steps

Now that Encore is configured, you’re ready to:

User Management: identify users for entitlement tracking
Present Offers: show promotional offers and read the result

iOS

Android

Web

Bridges

Configure the SDK

Overview

Initialize Encore in Your App

Register a purchase controller

Configuration options

Next Steps

​Overview

​Initialize Encore in Your App

​Register a purchase controller

​Configuration options

​Next Steps

Overview

Initialize Encore in Your App

Register a purchase controller

Configuration options

Next Steps