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
  Future<StepAdvanceResult> onBeforeStepAdvance(
    String flowId,
    String fromStepId,
    int stepIndex,
    String stepType,
    Map<String, dynamic> responses,
    Map<String, dynamic>? stepData,
  ) async => StepAdvanceResult.proceed();

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

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);
  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<String> entitlements);
  void onRestoreCompleted(List<String> restoredProductIds);
}

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, 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;            // Default: 30 (seconds)
  final int? batchSize;                // Default: 20
  final int? configTTL;                // Default: 3600 (seconds)
  final AppDNALogLevel? logLevel;      // Default: warning
  final AppDNABillingProvider? billingProvider; // Default: storeKit2 (iOS)

  const AppDNAOptions({
    this.flushInterval,
    this.batchSize,
    this.configTTL,
    this.logLevel,
    this.billingProvider,
  });
}

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

enum AppDNABillingProvider { storeKit2, revenueCat, adapty, none }

sealed class StepAdvanceResult {
  /// Continue to the next step normally.
  const factory StepAdvanceResult.proceed() = _Proceed;

  /// Continue and merge additional data into the session.
  const factory StepAdvanceResult.proceedWithData(Map<String, dynamic> data) = _ProceedWithData;

  /// Block advancement and show an error message (red banner).
  const factory StepAdvanceResult.block({required String message}) = _Block;

  /// Stay on the current step without advancing. Pass a non-null `message` to render a green success banner.
  const factory StepAdvanceResult.stay({String? message}) = _Stay;

  /// Skip to a specific step by ID.
  const factory StepAdvanceResult.skipTo({required String stepId}) = _SkipTo;

  /// Skip to a specific step and merge additional data.
  const factory StepAdvanceResult.skipToWithData({
    required String stepId,
    required Map<String, dynamic> data,
  }) = _SkipToWithData;
}

class StepConfigOverride {
  /// Pre-fill form fields. Keys match the field IDs configured in the Console.
  final Map<String, dynamic>? fieldDefaults;

  /// Override the step's title.
  final String? title;

  /// Override the step's subtitle.
  final String? subtitle;

  /// Override the primary CTA label.
  final String? ctaText;

  /// Override layout-level config (alignment, spacing, theme tokens).
  final Map<String, dynamic>? layoutOverrides;

  const StepConfigOverride({
    this.fieldDefaults,
    this.title,
    this.subtitle,
    this.ctaText,
    this.layoutOverrides,
  });
}

abstract class PaywallAction {
  static const String ctaTapped = 'cta_tapped';
  static const String featureSelected = 'feature_selected';
  static const String planChanged = 'plan_changed';
  static const String linkTapped = 'link_tapped';
  static const String custom = 'custom';
}

abstract class DismissReason {
  static const String purchased = 'purchased';
  static const String restoreSuccess = 'restore_success';
  static const String dismissed = 'dismissed';
  static const String tappedOutside = 'tappedOutside';
  static const String programmatic = 'programmatic';
}

class ScreenResult {
  final bool dismissed;
  final Map<String, dynamic> responses;

  const ScreenResult({required this.dismissed, required this.responses});
}

class FlowResult {
  final bool completed;
  final List<String> screensViewed; // Ordered list of screen IDs viewed during the flow
  final String? lastScreenId;
  final Map<String, dynamic> responses;

  const FlowResult({
    required this.completed,
    required this.screensViewed,
    this.lastScreenId,
    required this.responses,
  });
}

class LocationData {
  final double latitude;
  final double longitude;
  final double? accuracy;
  final String? address;
  final String? city;
  final String? region;
  final String? country;
  final String? postalCode;
  final DateTime timestamp;

  const LocationData({
    required this.latitude,
    required this.longitude,
    this.accuracy,
    this.address,
    this.city,
    this.region,
    this.country,
    this.postalCode,
    required this.timestamp,
  });
}

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 PushPayload {
  final String pushId;
  final String title;
  final String body;
  final String? imageUrl;
  final Map<String, dynamic>? data;
  final String? actionType;
  final String? actionValue;
}

class Entitlement {
  final String productId;
  final String store;          // e.g. "app_store", "play_store"
  final String status;         // e.g. "active", "expired"
  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? currency;             // ISO-4217 currency code
  final String? offerToken;           // Android base-plan offer token
  final SubscriptionInfo? subscription; // Subscription details, if applicable
}

class SubscriptionInfo {
  final String period;                // ISO-8601 (e.g., P1M, P1Y)
  final String periodDescription;     // Localized period label
  final String? freeTrialPeriod;
  final IntroductoryOffer? introductoryOffer;
}

class IntroductoryOffer {
  final String price;
  final String period;
  final String paymentMode;           // pay_as_you_go | pay_up_front | free_trial
}

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
}