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
  }
}

{
  "type": "rive",
  "rive_url": "https://cdn.example.com/celebrate.riv",
  "state_machine": "State Machine 1",
  "inputs": { "level": 3, "isPro": true, "celebrate": "now" }
}

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,
) {
  // `as Map?`, not `as Map<String, dynamic>?`: the platform channel decodes nested maps as
  // `Map<Object?, Object?>`, so that cast throws at runtime.
  final stepData = responses["location_step"] as Map?;
  final answer = stepData?["user_location"];
  if (answer is Map) {
    // The user selected a suggestion.
    print("City: ${answer['city']}");           // "New York"
    print("Country: ${answer['country_code']}"); // "US"
    print("Timezone: ${answer['timezone']}");    // "America/New_York"
    print("Coords: ${answer['latitude']}, ${answer['longitude']}");
  } else if (answer is String) {
    // The user typed without selecting a suggestion: the answer is the typed text.
    print("Typed: $answer");
  }
}

Welcome from {{responses.location_step.user_location.city}}!
Your timezone: {{responses.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?; // nested maps are Map<Object?, Object?>
    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?)?['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 (row_direction: horizontal, row_distribution: space_between, row_child_fill: false)
  ├── 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,
  };
}