ZeroSettle class

Main entry point for the ZeroSettle Flutter SDK.

Use ZeroSettle.instance to access the singleton. Call configure before any other methods.

await ZeroSettle.instance.configure(publishableKey: 'zs_pk_live_...');
final catalog = await ZeroSettle.instance.bootstrap(userId: 'user_123');

Properties

applePayStateUpdates → Stream<ApplePayAvailabilityState>
Hot stream of ApplePayAvailabilityState changes from the iOS Kit's applePayAvailability.statePublisher. Emits the current state on subscription so late subscribers don't have to wait.
no setter
checkoutEvents → Stream<Map<String, dynamic>>
Stream of checkout lifecycle events from the native SDK.
no setter
currentUserIdUpdates → Stream<String?>
Stream of the currently-identified user id, or null when no user is identified (initial state and after logout). Emits the current value on listen and every subsequent change. Convenience for binding signed-in/out UI to a single stream rather than polling getCurrentUserId after each identify / logout call.
no setter
entitlementUpdates → Stream<List<Entitlement>>
Stream of entitlement updates from the native SDK.
no setter
events → Stream<ZeroSettleEvent>
SDK analytics/lifecycle events. Fully populated on Android; on iOS emits the subset translatable from delegate callbacks (wired in the next task).
no setter
hashCode → int
The hash code for this object.
no setterinherited
isBootstrappedUpdates → Stream<bool>
Stream of the "has identify completed successfully?" flag. Emits the current value on listen, then true on first successful identify and false on logout. Use this to gate post-identify UI (catalog, entitlements, etc.).
no setter
isUcbEnabledUpdates → Stream<bool>
Reactive getIsUcbEnabled. Emits false once on iOS.
no setter
pendingActionsUpdates → Stream<List<PendingAction>>
Reactive stream of pending-action list snapshots. Emits whenever the SDK's pendingActions StateFlow mutates on Android. iOS emits [] once on subscribe and never again.
no setter
pendingCheckoutUpdates → Stream<bool>
Stream of the "is a web checkout in-flight?" flag. Emits the current value on listen, then true when purchase enters the web flow and false when it returns (success, cancel, or failure). Useful for driving a loading overlay without juggling Future state in your widget.
no setter
pendingClaimsUpdates → Stream<List<PendingClaim>>
Stream of PendingClaim list snapshots, emitting whenever the SDK's pending-claim list mutates (claim added or removed).
no setter
productsUpdates → Stream<List<Product>>
Stream of product catalog updates from the native SDK. Mirrors the native SDK's reactive products observable — emits the current catalog on listen and every subsequent change. Use this instead of polling getProducts when you want to react to catalog mutations (e.g. server-driven price changes or A/B-tested product visibility).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

acceptSaveOffer({required String productId, String? userId}) → Future<CancelFlowSaveOfferResult>
Accept the save offer for a subscription about to be cancelled.
bootstrap({required String userId}) → Future<ProductCatalog>
Fetch products and restore entitlements.
cancelSubscription({required String productId, bool immediate = false, String? userId}) → Future<void>
Cancel a subscription immediately or at end of period.
configure({required String publishableKey, bool syncStoreKitTransactions = true, String? appleMerchantId, bool preloadCheckout = false, int? maxPreloadedWebViews, ApplePaySetupBehavior? applePaySetupBehavior, String? playLicenseKey, bool syncPlayPurchases = true, bool strictAck = false}) → Future<void>
Configure the SDK with your publishable key. Must be called before any other methods.
dismissPendingAction({required String transactionId}) → Future<void>
Dismiss a pending action by transactionId. No-op on iOS.
fetchCancelFlowConfig({String? userId}) → Future<CancelFlowConfig>
Fetch the cancel flow configuration without presenting any UI.
fetchProducts({String? userId}) → Future<ProductCatalog>
Fetch the product catalog from ZeroSettle.
fetchTransactionHistory({String? userId}) → Future<List<CheckoutTransaction>>
Fetch the full transaction history for the currently identified user.
fetchUpgradeOfferConfig({String? productId, String? userId}) → Future<UpgradeOfferConfig>
Fetch the upgrade offer configuration without presenting any UI.
fetchUserOffer() → Future<UserOfferResponse>
Fetches the server-resolved offer for the currently-identified user.
getApplePayState() → Future<ApplePayAvailabilityState>
Reads the current ApplePayAvailabilityState once. Mirrors ZeroSettle.shared.applePayAvailability.state on iOS.
getCancelFlowConfig() → Future<CancelFlowConfig?>
Get the cancel flow configuration from the cached config.
getCurrentUserId() → Future<String?>
The currently identified user ID, or null if no user is identified.
getDetectedJurisdiction() → Future<Jurisdiction?>
Get the detected jurisdiction.
getEntitlements() → Future<List<Entitlement>>
Get the current cached entitlements.
getIsApplePayOnly() → Future<bool>
Whether the SDK is currently treating this merchant as Apple-Pay-only. Drives banner CTA swap and the imperative-checkout pre-flight gate on iOS. Mirrors ZeroSettle.shared.isApplePayOnly.
getIsBootstrapped() → Future<bool>
Whether identify (or the deprecated bootstrap path) has completed and entitlements have been fetched.
getIsConfigured() → Future<bool>
Whether the SDK has been configured.
getIsUcbEnabled() → Future<bool>
Whether User Choice Billing is active for this tenant/market. Always false on iOS (UCB is an Android/Play concept).
getPendingActions() → Future<List<PendingAction>>
Returns the current list of backend-driven pending actions. Android only; iOS always returns an empty list. Action types this plugin version does not recognize are skipped (see _decodePendingActions).
getPendingCheckout() → Future<bool>
Whether a checkout is currently in progress.
getPendingClaims() → Future<List<PendingClaim>>
Returns the list of PendingClaims currently surfaced by the SDK — StoreKit purchases the current user could claim from a different ZeroSettle account.
getProducts() → Future<List<Product>>
Get the cached products from the last fetch.
getRemoteConfig() → Future<RemoteConfig?>
Get the remote configuration from the last fetch.
getSdkVersion() → Future<String>
The native SDK version string (e.g. "1.4.0").
Handle a universal link callback from web checkout. Returns true if the URL was handled by ZeroSettle.
hasActiveEntitlement({required String productId}) → Future<bool>
Quick check: does the user have an active entitlement for productId?
identify(Identity identity) → Future<ProductCatalog?>
Identify the current session. Mirrors native identify(_:).
logout() → Future<void>
Clear user-scoped state. Call when the user logs out of your app.
migrationManager({String? stripeCustomerId}) → Future<MigrationManager>
Returns a MigrationManager handle bound to the currently-identified user and the optional stripeCustomerId. The iOS-side manager is cached; calling this twice returns handles wired to the same underlying state.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
offerManager({String? stripeCustomerId}) → Future<OfferManager>
Returns an OfferManager handle bound to the currently-identified user and the optional stripeCustomerId. The iOS-side manager is cached; calling this twice returns handles wired to the same underlying state.
openCustomerPortal({required String userId}) → Future<void>
Open the Stripe customer portal for subscription management. Removed in ZeroSettleKit 1.x. The Dart facade is kept for source compatibility but the iOS bridge throws not_implemented. Use presentCancelFlow (or the headless cancelSubscription) for subscription retention / cancellation flows. Removed in zerosettle 2.0.
pauseSubscription({required String productId, int? pauseDurationDays, String? userId, int? pauseOptionId}) → Future<DateTime?>
Pause a subscription.
preloadPaymentSheet({required String productId, String? userId}) → Future<void>
Preload the payment sheet for faster presentation.
presentApplePaySetup() → Future<void>
Launches the system Wallet setup flow so the user can add a card for Apple Pay. Mirrors ZeroSettle.shared.presentApplePaySetup() on iOS.
presentCancelFlow({required String productId, String? userId}) → Future<CancelFlowResult>
Present the cancel flow questionnaire for a subscription cancellation.
presentPaymentSheet({required String productId, String? userId, bool dismissible = true}) → Future<CheckoutTransaction>
Present the payment sheet for a product.
presentSaveTheSaleSheet() → Future<ZSSaveTheSaleResult>
Present the save-the-sale retention sheet.
presentUpgradeOffer({String? productId, String? userId}) → Future<UpgradeOfferResult>
Present the upgrade offer sheet for a subscription upgrade.
product({required String productId}) → Future<Product?>
Look up a single cached product by ID. Returns null if not in the catalog.
purchase({required String productId, CheckoutType? presentation}) → Future<CheckoutTransaction>
Unified purchase entry point. Routes to web checkout (Stripe) or native StoreKit depending on jurisdiction, remote config, and the per-call presentation override.
purchaseViaPlayBilling({required String productId}) → Future<CheckoutTransaction>
Purchase via Google Play Billing (Android-specific).
purchaseViaStoreKit({required String productId}) → Future<CheckoutTransaction>
Force a StoreKit (App Store IAP) purchase, bypassing web checkout. Use for jurisdictions where web checkout is disabled or when the app wants explicit control over the purchase channel.
recommendedAppAccountToken() → Future<String>
Returns the recommended appAccountToken to use when calling StoreKit directly (e.g. StoreKit.Product.purchase(options: [.appAccountToken(...)])).
releasePendingCheckout() → Future<void>
Cancels an in-flight web checkout. No-op on iOS.
resetMigrateTipState() → Future<void>
Resets the persisted dismissal state for the migration tip view. After calling this, the migration tip will appear again for eligible users.
restoreEntitlements({String? userId}) → Future<List<Entitlement>>
Restore entitlements from both web checkout and StoreKit.
resumeSubscription({required String productId, String? userId}) → Future<void>
Resume a paused subscription.
setBaseUrlOverride(String? url) → Future<void>
Override the backend base URL for local development. Set before calling configure. Pass null to clear.
setCustomer({String? name, String? email}) → Future<void>
Update the Stripe customer's name/email metadata.
showManageSubscription({required String userId}) → Future<void>
Removed in ZeroSettleKit 1.x. The Dart facade is kept for source compatibility but the iOS bridge throws not_implemented. Use presentCancelFlow (or the headless cancelSubscription) for subscription retention / cancellation flows. Removed in zerosettle 2.0.
submitCancelFlowResponse(CancelFlowResponse response) → Future<void>
Submit the complete cancel flow response for analytics and processing.
toString() → String
A string representation of this object.
inherited
trackMigrationConversion({String? userId}) → Future<void>
Track a successful migration conversion.
transferPlayOwnershipToCurrentUser({required String productId, required String originalTransactionId}) → Future<void>
Transfer a Google Play purchase's ownership to the currently-identified user. Use after an identify call when you want to claim a Play purchase that was previously made under a different ZeroSettle account.
transferStoreKitOwnershipToCurrentUser({required String productId}) → Future<void>
Transfer a StoreKit-originated entitlement to the currently identified user. Replaces the deprecated claimEntitlement.
warmUpPaymentSheet({required String productId, String? userId}) → Future<void>
Warm up the payment sheet (preload + cache).

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

instance → ZeroSettle
final

Static Methods

trackEvent(FunnelEventType type, {required String productId, String? screenName, Map<String, String>? metadata}) → Future<void>
Fire-and-forget analytics event for paywall and checkout funnel tracking.