Flutter API Reference

abstract class AppDNAOnboardingDelegate {
  void onOnboardingStarted(String flowId);
  void onOnboardingStepChanged(String flowId, String stepId, int stepIndex, int totalSteps);
  void onOnboardingCompleted(String flowId, Map<String, dynamic> responses);
  void onOnboardingDismissed(String flowId, int atStep);

  // Async hooks — see Onboarding > Async Step Hooks.
  // These return plain Maps (there are no StepAdvanceResult / StepConfigOverride classes);
  // For the other hooks an empty map / null means "use the defaults". For onBeforeStepAdvance,
  // {'type': 'proceed'} advances; {} advances every step except a sign-in action, which it blocks
  // (see Onboarding > Authentication entry).
  Future<Map<String, dynamic>> onBeforeStepAdvance(
    String flowId,
    String fromStepId,
    int stepIndex,
    String stepType,
    Map<String, dynamic> responses,
    Map<String, dynamic>? stepData,
  ) async => <String, dynamic>{};

  Future<Map<String, dynamic>?> onBeforeStepRender(
    String flowId,
    String stepId,
    int stepIndex,
    String stepType,
    Map<String, dynamic> responses,
  ) async => null;

  Future<Map<String, dynamic>?> onElementInteraction(
    String flowId,
    String stepId,
    String blockId,
    String action,
    String? value,
    Map<String, dynamic> inputValues,
  ) async => null;

  Future<Map<String, dynamic>?> onPermissionRequest(String permissionType) async => null;

  void onPermissionResult(String flowId, String stepId, String permissionType, bool granted) {}
}

abstract class AppDNAPaywallDelegate {
  void onPaywallPresented(String paywallId);
  void onPaywallAction(String paywallId, String action);
  void onPaywallPurchaseStarted(String paywallId, String productId);
  void onPaywallPurchaseCompleted(String paywallId, String productId, Map<String, dynamic> transaction);
  void onPaywallPurchaseFailed(String paywallId, Object error, String errorType, String? productId);
  void onPaywallRestoreStarted(String paywallId);
  void onPaywallRestoreCompleted(String paywallId, List<String> restoredProductIds);
  void onPaywallRestoreFailed(String paywallId, Object error);
  void onPaywallDismissed(String paywallId);

  Future<bool> onPromoCodeSubmit(String paywallId, String code) async => false;
  void onPostPurchaseDeepLink(String paywallId, String url) {}
  void onPostPurchaseNextStep(String paywallId) {}
}

abstract class AppDNAPushDelegate {
  void onPushTokenRegistered(String token);
  void onPushReceived(Map<String, dynamic> notification, bool inForeground);
  void onPushTapped(Map<String, dynamic> notification, String? actionId);
}

abstract class AppDNABillingDelegate {
  void onPurchaseCompleted(String productId, Map<String, dynamic> transaction);
  void onPurchaseFailed(String productId, Object error);
  void onEntitlementsChanged(List<Map<String, dynamic>> entitlements); // both platforms; fires with the stream
  void onRestoreCompleted(List<String> restoredProductIds);
  void onBillingUnavailable() {} // Android-only; never fires on iOS.
}

abstract class AppDNAInAppMessageDelegate {
  void onMessageShown(String messageId, String trigger);
  void onMessageAction(String messageId, String action, Map<String, dynamic>? data);
  void onMessageDismissed(String messageId);
  bool shouldShowMessage(String messageId) => true;
}

abstract class AppDNASurveyDelegate {
  void onSurveyPresented(String surveyId);
  void onSurveyCompleted(String surveyId, List<Map<String, dynamic>> responses);
  void onSurveyDismissed(String surveyId);
}

abstract class AppDNADeepLinkDelegate {
  bool shouldOpen(String url, Map<String, dynamic> params);
  void onDeepLinkReceived(String url, Map<String, dynamic> params);
}

abstract class AppDNAScreenDelegate {
  void onScreenPresented(String screenId);
  void onScreenDismissed(String screenId, Map<String, dynamic> result);
  void onFlowCompleted(String flowId, Map<String, dynamic> result);
  bool onScreenAction(String screenId, Map<String, dynamic> action);
}

enum AppDNAEnvironment { production, staging }

class AppDNAOptions {
  final int? flushInterval;            // Not set: the bootstrap's value if positive, else 30 (seconds)
  final int? batchSize;                // A cap on the network-sized batch; not set: the bootstrap's value if positive, else no cap; below 1 is ignored
  final int? configTTL;                // Not set: the bootstrap's value if positive, else 3600 (seconds)
  final AppDNALogLevel? logLevel;      // Default: warning
  final AppDNABillingProvider? billingProvider; // Default: storeKit2 (Google Play Billing on Android)
  final int? notificationIcon;         // Android only: notification small-icon drawable resource id
  @Deprecated('Ignored since 1.0.8 — the native bridge injects the framework tag itself.')
  final String? framework;             // Ignored; the bridge injects `flutter` unconditionally
  final bool? requireConsent;          // Default: false (analytics opt-out)
  final int? vetoTimeout;              // Default: 5. Bounds host hooks on this bridge; sign-in actions wait at least 120 s; a `refresh` gets 8 s (a larger vetoTimeout does not extend it); `onBeforeStepRender` is cut off at 3 s

  const AppDNAOptions({
    this.flushInterval,
    this.batchSize,
    this.configTTL,
    this.logLevel,
    this.billingProvider,
    this.notificationIcon,
    this.framework,
    this.requireConsent,
    this.vetoTimeout,
  });
}

enum AppDNALogLevel { none, error, warning, info, debug }

class AppDNABillingProvider {
  static const AppDNABillingProvider storeKit2 = ...;
  static const AppDNABillingProvider revenueCat = ...;
  static const AppDNABillingProvider none = ...;

  /// Adapty billing, keyed by your Adapty public SDK key.
  factory AppDNABillingProvider.adapty(String apiKey);
}

// Advance to the next step:
{'type': 'proceed'}

// The default: advances every step except a sign-in action, which it blocks:
<String, dynamic>{}

// Advance and merge extra data into the flow responses:
{'type': 'proceedWithData', 'data': {...}}

// Block the advance and show an error message:
{'type': 'block', 'message': 'Invalid email or password.'}

// Jump to a specific step (optionally merging data):
{'type': 'skipTo', 'stepId': 'plan_step', 'data': {...}}

// Stay on the current step without an error. A 'message' shows a green success banner;
// omit it to stay silent:
{'type': 'stay', 'message': 'Reset email sent.'}

// null == no override, or a config-override map, e.g.:
{
  'fieldDefaults': {...},   // pre-fill form fields, keyed by Console field ID
  'title': 'Welcome back',  // override the step title
  'subtitle': '...',        // override the step subtitle
  'ctaText': 'Continue',    // override the primary CTA label
  'fieldOptions': {'blockId': [{'value': 'a', 'label': 'A'}]}, // host-supplied Select options
  'dataContext': {'booking': {'unitPrice': 4500}},             // read in the Console as {{hook_data.booking.unitPrice}}
  'mapRoutes': {'blockId': {'polyline': 'a~l~F...', 'stops': [{'lat': 51.5, 'lng': -0.1}]}},
}

// result map:
{
  'dismissed': bool,
  'responses': <String, dynamic>{...},
}

// result map:
{
  'completed': bool,
  'screensViewed': <String>[...], // ordered list of screen IDs viewed during the flow
  'lastScreenId': String?,
  'responses': <String, dynamic>{...},
}

class LocationData {
  final String formattedAddress; // always present
  // Every field below is null when the answer has no value for it — the same on
  // iOS and Android, in a form-step Location field and a Location content block.
  final String? city;
  final String? state;
  final String? stateCode;      // never from the iOS content block (Apple's place search has none)
  final String? country;
  final String? countryCode;
  final double? latitude;       // a finite number, else null
  final double? longitude;
  final String? timezone;       // IANA zone id
  final int? timezoneOffset;    // minutes from UTC; only with a timezone
  final String? postalCode;
  final String? rawQuery;       // the text the user typed
}

class PaywallContext {
  final String? placement;
  final String? experiment;
  final String? variant;
  final Map<String, dynamic>? customData;

  const PaywallContext({
    this.placement,
    this.experiment,
    this.variant,
    this.customData,
  });
}

class OnboardingContext {
  final String? source;
  final String? campaign;
  final String? referrer;
  final Map<String, dynamic>? userProperties;
  final Map<String, String>? experimentOverrides;

  const OnboardingContext({
    this.source,
    this.campaign,
    this.referrer,
    this.userProperties,
    this.experimentOverrides,
  });
}

class Entitlement {
  final String productId;
  final String store;          // iOS: always "app_store". Android: the store that granted it —
                               // "google_play", "app_store" or "stripe" (the server syncs every entitled
                               // store subscription of the user, whichever store sold it; not those
                               // reported only by RevenueCat, Adapty or Superwall)
  final String status;         // iOS: "active", or "expired" once the entitlement is no longer active.
                               // Android: the server's subscription status, e.g. active, trialing,
                               // grace_period, billing_retry, on_hold, pending, paused, expired, canceled;
                               // active, trialing, grace_period and billing_retry count as active
  final String? expiresAt;     // ISO 8601 timestamp
  final bool isTrial;
  final String? offerType;     // e.g. "introductory"
}

class PurchaseResult {
  final String status;            // "purchased", "cancelled", "pending", "unknown"
  final Entitlement? entitlement; // Non-null when status == "purchased"
}

class ProductInfo {
  final String id;
  final String name;
  final String description;
  final String displayPrice;   // Localized formatted price
  final double price;          // Numeric price value
  final String? offerToken;    // Android base-plan offer token
}

class WebEntitlement {
  final bool isActive;
  final String? planName;
  final String? priceId;
  final String? interval;          // e.g. "month", "year"
  final String status;             // e.g. "active", "canceled", "trialing"
  final DateTime? currentPeriodEnd;
  final DateTime? trialEnd;
}

class DeferredDeepLink {
  final String screen;
  final Map<String, String> params;
  final String visitorId;
}

class SurveyResult {
  final String surveyId;
  final bool completed;            // false if dismissed early
  final int questionsAnswered;
  final List<SurveyAnswer>? answers;
}

class SurveyAnswer {
  final String questionId;
  final dynamic answer;            // int, String, List, etc. depending on question type
}