Flutter Onboarding

final presented = await AppDNA.presentOnboarding("main_flow");
if (!presented) {
  // The flow ID is not in the published config, the SDK is not configured yet, or there was no
  // view controller / foreground Activity to present from. Nothing was shown.
  print("Onboarding not presented — check the flow ID in Console, or wait for config to load.");
}

final onboarding = AppDNA.onboarding;

final context = OnboardingContext(
  source: "app_launch",
  campaign: "winter_2025",
  referrer: "social_ad",
  userProperties: {"locale": "en_US"},
  experimentOverrides: {"onboarding_variant": "b"},
);

await AppDNA.onboarding.present(
  "main_flow",
  context: context,
);

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 "Async Step Hooks" below. Both return plain maps
  // (there is no StepAdvanceResult / StepConfigOverride Dart class).
  Future<Map<String, dynamic>> onBeforeStepAdvance(
    String flowId,
    String fromStepId,
    int stepIndex,
    String stepType,
    Map<String, dynamic> responses,
    Map<String, dynamic>? stepData,
  ) async =>
      <String, dynamic>{}; // {} proceeds — except on a sign-in action, which it blocks

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

  // A user acted on an interactive element (or tapped a "Refresh this step" button, action
  // 'refresh'). Return a map with any of: 'fieldConfigPatches', 'inputValuePatches',
  // 'fieldOptions', 'dataContext', 'advance' — or null for no change. See "Show more".
  Future<Map<String, dynamic>?> onElementInteraction(
    String flowId,
    String stepId,
    String blockId,
    String action,
    String? value,
    Map<String, dynamic> inputValues,
  ) async =>
      null;
}

AppDNA.onboarding.setDelegate(myOnboardingDelegate);

class OnboardingHandler extends AppDNAOnboardingDelegate {
  @override
  void onOnboardingStarted(String flowId) {
    print("Onboarding started: $flowId");
  }

  @override
  void onOnboardingStepChanged(
    String flowId,
    String stepId,
    int stepIndex,
    int totalSteps,
  ) {
    print("Step ${stepIndex + 1}/$totalSteps: $stepId");
    // Update progress indicator
  }

  @override
  void onOnboardingCompleted(
    String flowId,
    Map<String, dynamic> responses,
  ) {
    print("Onboarding completed: $flowId");
    print("User responses: $responses");
    // Navigate to main app screen
    // Use responses to personalize the experience
  }

  @override
  void onOnboardingDismissed(String flowId, int atStep) {
    print("Onboarding dismissed at step $atStep");
    // Handle early exit — maybe show again later
  }
}

import 'package:appdna_sdk/appdna_sdk.dart';
import 'package:local_auth/local_auth.dart';

class OnboardingHandler extends AppDNAOnboardingDelegate {
  final _auth = LocalAuthentication();

  @override
  Future<Map<String, dynamic>> onBeforeStepAdvance(
    String flowId,
    String fromStepId,
    int stepIndex,
    String stepType,
    Map<String, dynamic> responses,
    Map<String, dynamic>? stepData,
  ) async {
    final action = stepData?['action'] as String?;
    if (action == null) return {}; // no button action: {} advances this ordinary step

    switch (action) {
      case 'login':
        final email = stepData?['email'] as String? ?? '';
        final password = stepData?['password'] as String? ?? '';
        try {
          final user = await authClient.signIn(email: email, password: password);
          return {'type': 'proceedWithData', 'data': {'user_id': user.id}};
        } catch (_) {
          return {'type': 'block', 'message': 'Invalid email or password.'};
        }

      case 'register':
        final email = stepData?['email'] as String? ?? '';
        final password = stepData?['password'] as String? ?? '';
        try {
          final user = await authClient.register(email: email, password: password);
          return {'type': 'proceedWithData', 'data': {'user_id': user.id}};
        } catch (_) {
          return {'type': 'block', 'message': "Couldn't create account — try a different email."};
        }

      case 'reset_password':
        final email = stepData?['email'] as String? ?? '';
        try {
          await authClient.requestPasswordReset(email: email);
        } catch (_) {}
        // Stay on step; show inline confirmation banner.
        return {
          'type': 'stay',
          'message': "If an account exists for $email, we've emailed a reset link.",
        };

      case 'request_otp':
        // Fail explicitly when the SDK couldn't resolve the channel
        // (step has both phone and email inputs, or neither). Set the
        // button's action_value in the Console to disambiguate.
        final channel = stepData?['channel'] as String?;
        final recipient = stepData?['recipient'] as String?;
        if (channel == null || recipient == null) {
          return {
            'type': 'block',
            'message': "Couldn't determine OTP delivery channel — please contact support.",
          };
        }
        try {
          await otpClient.send(channel: channel, to: recipient);
          return {'type': 'proceed'};
        } catch (_) {
          return {'type': 'block', 'message': "Couldn't send code — please retry."};
        }

      case 'verify_otp':
        final code = stepData?['otp_code'] as String?;
        final recipient = stepData?['recipient'] as String?;
        if (code == null || recipient == null) {
          return {'type': 'block', 'message': 'Missing code or recipient.'};
        }
        try {
          await otpClient.verify(code: code, recipient: recipient);
          return {'type': 'proceed'};
        } catch (_) {
          return {'type': 'block', 'message': "Code didn't match — try again."};
        }

      case 'enable_biometric':
        final available = await _auth.canCheckBiometrics;
        if (!available) return {'type': 'proceed'};
        final success = await _auth.authenticate(
          localizedReason: 'Enable Face ID / Fingerprint for faster sign-in',
        );
        return {'type': 'proceedWithData', 'data': {'biometric_enabled': success}};

      default:
        // {} proceeds an ordinary step and BLOCKS a sign-in action this switch does not
        // handle — the safe default. Never answer {'type': 'proceed'} for a sign-in action
        // you have not actually authenticated.
        return {};
    }
  }
}

@override
void onOnboardingCompleted(
  String flowId,
  Map<String, dynamic> responses,
) {
  // `Map.from`, not `as Map<String, dynamic>`: the platform channel decodes nested maps as
  // `Map<Object?, Object?>`, so a direct cast throws at runtime.
  final raw = responses["profile_step"] as Map?;
  if (raw != null) {
    final formData = Map<String, dynamic>.from(raw);
    final name = formData["full_name"] as String?;
    final age = formData["age"] as int?;
    final email = formData["email"] as String?;
    // Use collected data to personalize the experience
  }
}

@override
void onOnboardingCompleted(
  String flowId,
  Map<String, dynamic> responses,
) {
  // `Map.from`, not `as Map<String, dynamic>`: the platform channel decodes nested maps as
  // `Map<Object?, Object?>`, so a direct cast throws at runtime.
  final flags = Map<String, dynamic>.from(responses["flags"] as Map? ?? {});

  if (flags["upsell_choice"] == "booking") {
    router.showBooking();
  }
  if (flags["wants_callback"] == "true") {
    scheduleCallback();
  }
}

@override
void onOnboardingCompleted(
  String flowId,
  Map<String, dynamic> responses,
) {
  final formData = responses["location_step"] as Map<String, dynamic>?;
  final location = formData?["user_location"] as Map<String, dynamic>?;
  if (location != null) {
    print("City: ${location['city']}");           // "New York"
    print("Country: ${location['country_code']}"); // "US"
    print("Timezone: ${location['timezone']}");    // "America/New_York"
    print("Coords: ${location['latitude']}, ${location['longitude']}");
  }
}

Welcome from {{onboarding.location_step.user_location.city}}!
Your timezone: {{onboarding.location_step.user_location.timezone}}

{
  "event": "chat_message",
  "flow_id": "onboarding_v1",
  "step_id": "chat_intro",
  "app_id": "app_abc123",
  "user_id": "user_xyz",
  "conversation": {
    "turn": 2,
    "user_message": "I've been having vivid dreams lately",
    "max_turns": 5,
    "remaining_turns": 3,
    "messages": [
      { "role": "ai",   "content": "Hi, what brings you here?",       "id": "msg_a0", "timestamp": "2026-04-15T10:00:00Z" },
      { "role": "user", "content": "I've been having vivid dreams...", "id": "msg_u1", "timestamp": "2026-04-15T10:00:12Z" }
    ]
  },
  "context": { "threadId": "thread_UXJWTKpSvBRWpGEhHLXqnA6O" },
  "rating": null
}

{
  "action": "reply",
  "messages": [
    { "content": "Tell me more about the most recent one." }
  ]
}

app.post('/chat', async (req, res) => {
  const { conversation } = req.body;
  const userMessage = conversation.user_message;

  const replyText = await myLLM.complete(userMessage);

  res.json({
    action: "reply",
    messages: [{ content: replyText }],
  });
});

app.post('/chat', async (req, res) => {
  const { conversation, context } = req.body;

  // Resume if we have a threadId; create a fresh one otherwise
  let threadId = context?.threadId;
  if (!threadId) {
    threadId = await aiService.createThread();
  }

  let replyText;
  try {
    replyText = await aiService.sendMessage(threadId, conversation.user_message);
  } catch (err) {
    // Thread expired or invalid — start fresh and retry once
    if (err.code === 'thread_expired') {
      threadId = await aiService.createThread();
      replyText = await aiService.sendMessage(threadId, conversation.user_message);
    } else {
      throw err;
    }
  }

  res.json({
    action: "reply",
    messages: [{ content: replyText }],
    data: { threadId },   // round-tripped to every subsequent call
  });
});

@override
Future<Map<String, dynamic>> onBeforeStepAdvance(
  String flowId,
  String fromStepId,
  int stepIndex,
  String stepType,
  Map<String, dynamic> responses,
  Map<String, dynamic>? stepData,
) async {
  // This hook handles no sign-in action. A step advanced by a button action — a sign-in action
  // among them — gets {}: it advances an ordinary step and BLOCKS a sign-in action. Never answer
  // {'type': 'proceed'} for a sign-in action you have not actually authenticated.
  if (stepData?['action'] != null) return {};

  // Example: validate a referral code with your backend
  if (stepType == 'form') {
    final stepResponses = responses[fromStepId] as Map<String, dynamic>?;
    final code = stepResponses?['referral_code'] as String?;
    if (code != null) {
      final isValid = await validateReferralCode(code);
      if (!isValid) {
        return {'type': 'block', 'message': 'Invalid referral code. Please try again.'};
      }
      return {'type': 'proceedWithData', 'data': {'referral_validated': true}};
    }
  }
  return {}; // {} proceeds — except on a sign-in action, which needs an explicit type
}

case 'reset_password':
  final email = (responses[fromStepId] as Map<String, dynamic>?)?['email'] as String? ?? '';
  try {
    await myAuthBackend.sendPasswordReset(to: email);
    return {'type': 'stay', 'message': 'Reset email sent to $email'};
  } catch (_) {
    return {'type': 'block', 'message': "Couldn't send reset email. Please try again."};
  }

@override
Future<Map<String, dynamic>?> onBeforeStepRender(
  String flowId,
  String stepId,
  int stepIndex,
  String stepType,
  Map<String, dynamic> responses,
) async {
  // Pre-fill form fields based on user data
  if (stepId == 'profile_step') {
    return {
      'fieldDefaults': {
        'email': currentUser.email,
        'name': currentUser.displayName,
      },
      'title': 'Welcome back, ${currentUser.firstName}!',
    };
  }
  return null;
}

// Example: Two buttons side by side, equally spaced
Row (direction: horizontal, distribution: equal)
  ├── Button "Skip"
  └── Button "Continue"

@override
Future<Map<String, dynamic>?> onBeforeStepRender(
  String flowId, String stepId, int stepIndex, String stepType,
  Map<String, dynamic> responses,
) async {
  final booking = await myBackend.booking(stepId);   // your client, your auth
  return {
    'dataContext': {
      'booking': {'unitPrice': booking.unitPrice, 'venue': booking.venueName},
    },
  };
}

{ "type": "image", "image_url": "https://…/uploaded-fallback.png",
  "data_templates": { "image_url": "{{hook_data.hero.imageUrl}}" } }

@override
Future<Map<String, dynamic>?> onBeforeStepRender(
  String flowId, String stepId, int stepIndex, String stepType,
  Map<String, dynamic> responses,
) async {
  if (stepId != 'step8') return null;
  final venues = await myBackend.recommendations(responses);   // your client, your auth
  return {
    'dataContext': {
      'recommendations': [
        for (final w in venues)
          {'id': w.id, 'name': w.name, 'subtitle': w.region, 'imageUrl': w.photoUrl},
      ],
    },
  };
}

// Your paging state, per step. Also answer onBeforeStepRender with it on a revisit (below).
final _shownVenues = <String, List<Venue>>{};

@override
Future<Map<String, dynamic>?> onElementInteraction(String flowId, String stepId, String blockId,
    String action, String? value, Map<String, dynamic> inputValues) async {
  if (action != 'refresh' || stepId != 'step8') return null; // value == 'recs_more'
  final shown = _shownVenues[stepId] ?? const <Venue>[];
  final all = [...shown, ...await myBackend.recommendations(after: shown.length)]; // your client
  _shownVenues[stepId] = all;
  return {
    'dataContext': {
      // The WHOLE list so far — page 1 + page 2 … — under the key the Select repeats over.
      'recommendations': [
        for (final w in all) {'id': w.id, 'name': w.name, 'subtitle': w.region, 'imageUrl': w.photoUrl},
      ],
    },
    'advance': false,
  };
}

Step 1: "What's your fitness goal?"
  → "Lose weight"  → Step 2a: Weight loss program
  → "Build muscle" → Step 2b: Muscle building program
  → "Stay active"  → Step 2c: General fitness

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

class OnboardingScreen extends StatefulWidget {
  const OnboardingScreen({super.key});

  @override
  State<OnboardingScreen> createState() => _OnboardingScreenState();
}

class _OnboardingScreenState extends State<OnboardingScreen>
    implements AppDNAOnboardingDelegate {
  @override
  void initState() {
    super.initState();
    AppDNA.onboarding.setDelegate(this);
    _showOnboardingIfNeeded();
  }

  Future<void> _showOnboardingIfNeeded() async {
    try {
      await AppDNA.onboarding.present(
        "main_flow",
        context: OnboardingContext(source: "app_launch"),
      );
    } catch (e) {
      // No active flow or config not loaded yet
      _navigateToMainApp();
    }
  }

  // MARK: - AppDNAOnboardingDelegate

  @override
  void onOnboardingStarted(String flowId) {
    print("Starting flow: $flowId");
  }

  @override
  void onOnboardingStepChanged(
    String flowId,
    String stepId,
    int stepIndex,
    int totalSteps,
  ) {
    // Track progress
  }

  @override
  void onOnboardingCompleted(
    String flowId,
    Map<String, dynamic> responses,
  ) {
    // Personalize based on responses
    final goal = responses["fitness_goal"] as String?;
    if (goal != null) {
      AppDNA.identify(
        "current_user_id",
        traits: {"fitness_goal": goal},
      );
    }
    _navigateToMainApp();
  }

  @override
  void onOnboardingDismissed(String flowId, int atStep) {
    _navigateToMainApp();
  }

  void _navigateToMainApp() {
    if (!mounted) return;
    Navigator.of(context).pushReplacementNamed('/home');
  }

  // This State IS the delegate, so it `implements` the interface and must provide every member (unlike
  // a standalone `extends AppDNAOnboardingDelegate` class, which inherits the defaults). The async
  // veto/permission hooks keep their default (no-op) behavior:
  @override
  Future<Map<String, dynamic>> onBeforeStepAdvance(String flowId, String fromStepId, int stepIndex,
          String stepType, Map<String, dynamic> responses, Map<String, dynamic>? stepData) async =>
      <String, dynamic>{};
  @override
  Future<Map<String, dynamic>?> onBeforeStepRender(String flowId, String stepId, int stepIndex,
          String stepType, Map<String, dynamic> responses) async =>
      null;
  @override
  Future<Map<String, dynamic>?> onElementInteraction(String flowId, String stepId, String blockId,
          String action, String? value, Map<String, dynamic> inputValues) async =>
      null;
  @override
  Future<Map<String, dynamic>?> onPermissionRequest(String permissionType) async => null;
  @override
  void onPermissionResult(String flowId, String stepId, String permissionType, bool granted) {}

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(child: CircularProgressIndicator()),
    );
  }
}

☑ Skip if user already has an active subscription   ← default for new + legacy nodes

final hasSub = await AppDNA.billing.hasActiveSubscription();

class MyPaywallDelegate extends AppDNAPaywallDelegate {
  @override
  void onPaywallRestoreCompleted(
    String paywallId,
    List<String> restoredProductIds,
  ) {
    if (restoredProductIds.isNotEmpty) {
      print("Restored ${restoredProductIds.length} product(s) — SDK is dismissing the paywall.");
    } else {
      print("Restore returned no entitlements — paywall stays open.");
    }
  }

  // ... other 8 AppDNAPaywallDelegate methods
}

class MyPaywallDelegate extends AppDNAPaywallDelegate {
  @override
  void onPaywallRestoreCompleted(String paywallId, List<String> productIds) {
    // Update your own state (e.g., unlock content) — not UI over the paywall.
    // The dismiss decision has already been made natively by the time this
    // runs. To keep the paywall up, call
    // AppDNA.skipNextAutoDismissOnRestore(true) BEFORE the Restore tap,
    // not here.
  }
}

await AppDNA.identify("user_abc", traits: {"plan": "free"});
// Native entitlement cache is refreshed in the background.
// The next paywall_trigger node will see the updated state.