> ## Documentation Index > Fetch the complete documentation index at: https://docs.appdna.ai/llms.txt > Use this file to discover all available pages before exploring further. # Flutter Onboarding > Present server-driven onboarding flows **Supported on:** iOS SDK `1.0.61+` · Android SDK `1.0.33+` · Flutter SDK `1.0.3+` The AppDNA Flutter SDK delivers full onboarding parity through native platform rendering. The onboarding module lets you present server-driven onboarding flows that are configured in the AppDNA Console, with native UI primitives on each platform — SwiftUI on iOS, Jetpack Compose on Android. Flows are delivered to the SDK via the remote config bundle, so you can update onboarding experiences without shipping app updates. ## Present an Onboarding Flow Present a specific onboarding flow by ID. The method returns a `Future` that completes once the native flow surface is shown: ```dart theme={null} try { await AppDNA.presentOnboarding("main_flow"); } catch (e) { print("Flow config not available — check Console or network: $e"); } ``` If the flow ID is unknown to the SDK or the remote config bundle has not finished loading, the call returns immediately as a no-op and a debug-level log entry is emitted. The Flutter API takes the flow ID as a positional argument. To present the active flow configured in remote config from the AppDNA Console, the canonical pattern is to pick an explicit flow ID at the call site — the Console controls which flow is active by toggling published flows. ## Module Access Access the onboarding module directly to use additional methods like `setDelegate` and to pass an `OnboardingContext`: ```dart theme={null} final onboarding = AppDNA.onboarding; ``` ### Module Methods | Method | Signature | Description | | ------------- | --------------------------------------------------------------------- | --------------------------------- | | `present` | `Future present(String flowId, { OnboardingContext? context })` | Present an onboarding flow | | `setDelegate` | `void setDelegate(AppDNAOnboardingDelegate? delegate)` | Set a delegate for flow callbacks | The static `AppDNA.presentOnboarding(flowId)` is a convenience that calls `AppDNA.onboarding.present(flowId)` with no context. ## OnboardingContext Pass additional context when presenting a flow: ```dart theme={null} 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, ); ``` | Property | Type | Description | | --------------------- | ----------------------- | --------------------------------------------------- | | `source` | `String?` | Where the flow was triggered from | | `campaign` | `String?` | Attribution campaign identifier | | `referrer` | `String?` | Referral source | | `userProperties` | `Map?` | Additional user properties for personalization | | `experimentOverrides` | `Map?` | Override experiment variant assignments for testing | The `experimentOverrides` parameter is intended for development and QA only. In production, experiment variants are assigned automatically by the AppDNA backend. ## Paywalls inside onboarding flows Steps with `outcome: present_paywall` open a paywall and route the user based on the result (purchase / fail / dismiss → next step). The host's `AppDNAPaywallDelegate` (registered via `AppDNA.paywall.setDelegate(...)`) fires for these embedded paywalls **identically to standalone presentations** — purchase, restore, action, and post-purchase callbacks all reach the host. See the [Flutter paywall docs](/sdks/flutter/paywall) for the full delegate surface. ## AppDNAOnboardingDelegate Implement the `AppDNAOnboardingDelegate` abstract class to receive onboarding flow lifecycle events. The delegate fires for every step transition and at flow completion / dismissal. For server-driven async hooks that can block or redirect step advancement, see [Async Step Hooks](#async-step-hooks) below. ```dart theme={null} abstract class AppDNAOnboardingDelegate { void onOnboardingStarted(String flowId); void onOnboardingStepChanged( String flowId, String stepId, int stepIndex, int totalSteps, ); void onOnboardingCompleted( String flowId, Map 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> onBeforeStepAdvance( String flowId, String fromStepId, int stepIndex, String stepType, Map responses, Map? stepData, ) async => {}; // {} == proceed Future?> onBeforeStepRender( String flowId, String stepId, int stepIndex, String stepType, Map responses, ) async => null; // null == no override } ``` ### Set the Delegate ```dart theme={null} AppDNA.onboarding.setDelegate(myOnboardingDelegate); ``` ### Example Implementation ```dart theme={null} 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 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 } } ``` ## Step Types Onboarding flows support the following step types, configured in the AppDNA Console: | Step Type | Description | | ------------------ | -------------------------------------------------------------- | | `welcome` | Welcome screen with title, subtitle, and hero image | | `question` | Single-select or multi-select question for user input | | `value_prop` | Value proposition screen highlighting a key feature or benefit | | `form` | Structured form with multiple native input fields | | `interactive_chat` | Conversational step backed by your webhook | | `info` | Informational screen rendered through the custom-step pipeline | | `permission` | Push notification or tracking permission request | | `custom` | Custom content rendered via a template | Step types and their content are defined entirely in the Console. The SDK renders them natively — you do not need to build UI for individual step types from Flutter. ### Selection Modes Question steps support two selection modes: | Mode | Description | | -------- | -------------------------------- | | `SINGLE` | User selects exactly one option | | `MULTI` | User can select multiple options | ## Content Blocks Each onboarding step is composed of content blocks that control the visual layout. Blocks are configured in the Console and rendered natively on each platform. The block string the Console emits is the same string the native SDK switches on. The following block types are available: ### Layout primitives | Block Type | Description | | ----------------- | ---------------------------------------------------------------------------------- | | `heading` | Primary heading text | | `text` | Body / subtitle text | | `rich_text` | Markdown-style rich text with inline formatting | | `list` | Bulleted or numbered list | | `badge` | Pill-shaped label | | `icon` | Single icon (Lucide / Material / SF / emoji) | | `image` | Static image with sizing and corner radius | | `lottie` | Lottie animation (JSON or dotLottie) | | `rive` | Rive state-machine animation | | `video` | Inline video (MP4, HLS) with autoplay and loop options | | `divider` | Horizontal separator | | `spacer` | Configurable vertical spacing | | `stack` | Vertical container that groups child blocks | | `row` | Horizontal container that arranges child blocks side by side | | `star_background` | Animated starfield or particle background effect | | `custom_view` | Host-app-provided view (see [Custom View Registration](#custom-view-registration)) | ### Interactive blocks | Block Type | Description | | ------------------- | ------------------------------------------------------------ | | `button` | Tappable button with configurable action | | `social_login` | Social sign-in buttons (Apple, Google, etc.) | | `wheel_picker` | Scrollable wheel-style picker for value selection | | `pulsing_avatar` | Animated avatar with a pulsing ring effect | | `timeline` | Vertical timeline with labeled milestones | | `animated_loading` | Skeleton or spinner loading animation between steps | | `countdown_timer` | Countdown timer with configurable duration and expiry action | | `rating` | Star or emoji rating selector | | `progress_bar` | Horizontal progress bar with percentage or label | | `circular_gauge` | Circular progress indicator with value label | | `date_wheel_picker` | Native date wheel picker (day/month/year columns) | | `page_indicator` | Dot or bar indicator showing current step progress | | `pricing_card` | Product pricing card with plan details and CTA | ### Form input blocks Form inputs are individual blocks (not a single `form` block). Each input type emits its current value through the step's `inputValues` map and is included in the step `responses` on completion. | Block Type | Renders | | -------------------- | ---------------------------------- | | `input_text` | Single-line text input | | `input_textarea` | Multi-line text input | | `input_number` | Numeric input | | `input_email` | Email input with validation | | `input_phone` | Phone-number input | | `input_url` | URL input | | `input_password` | Secure text with visibility toggle | | `input_date` | Date picker | | `input_time` | Time picker | | `input_datetime` | Combined date + time picker | | `input_select` | Dropdown / stacked / grid picker | | `input_slider` | Numeric slider | | `input_range_slider` | Dual-handle range slider | | `input_toggle` | On/off switch | | `input_stepper` | Increment/decrement counter | | `input_segmented` | Segmented control | | `input_rating` | Star rating input | | `input_chips` | Tag-style multi-select chips | | `input_color` | Color picker or preset swatches | | `input_image_picker` | Photo picker (gallery + camera) | | `input_signature` | Freehand signature drawing pad | | `input_location` | Autocomplete location search | Blocks are configured entirely in the Console. The SDK renders them automatically — no Dart code is needed unless you want to register a host-provided custom view (see [Custom View Registration](#custom-view-registration) below). ### Advanced blocks Available on iOS SDK `1.0.67+` / Android SDK `1.0.39+`. A batch of richer, interactive blocks render through the native layer on both platforms: | Block Type | Renders | | -------------------- | --------------------------------------------------------------------- | | `otp_input` | Boxed one-time / verification code entry | | `warning_banner` | Inline warning / error / info / success banner with an icon | | `password_strength` | Four-segment strength meter with a label | | `speech_bubble` | Mascot / dialogue bubble with a positionable tail | | `feedback_panel` | Quiz-style correct / wrong / info result panel | | `summary_screen` | Headline above a grid of stat cards | | `press_hold_confirm` | Press-and-hold confirmation pill | | `health_connect` | Connect-health-data card (Apple Health on iOS, Google Fit on Android) | | `settings_footer` | Dark-mode toggle + language-switcher row | | `memory_match` | Pair-matching memory-game grid | | `calendar_month` | Single-month calendar with selectable days | These wrap the native renderers — see the [iOS](/sdks/ios/onboarding#advanced-content-blocks) and [Android](/sdks/android/onboarding#advanced-content-blocks) onboarding docs for each block's `field_config` fields and for the `onElementInteraction` hook that powers the interactive ones. ## Button Actions `button` and `social_login` blocks emit a structured payload when tapped. The `action` value on the button (configured in the Console) determines what shape the payload takes and lets you route to the right backend call (sign in, register, request OTP, etc.). If the user has not completed required form fields on the step, the native SDK shows an inline validation toast and **does not** emit the action — same gate as the standard `next` button. ### Flow control | Action | What the SDK does | | ------------ | -------------------------------------------------------------------------- | | `next` | Advances to the next step. Payload includes all collected input values. | | `skip` | Skips the step (subject to `skip_enabled` config). | | `link` | Opens `action_value` (a URL) in the in-app browser. Step does not advance. | | `permission` | Triggers a platform permission prompt and advances on grant or denial. | ### Authentication entry When the user taps a button with one of these actions, the SDK calls your `onBeforeStepAdvance` handler with the payload below. Show a "Signing in…" spinner by returning `{'type': 'block', 'message': …}` while async auth runs, then return `{}` (proceed) / `{'type': 'proceedWithData', 'data': {...}}` when the backend responds. If you do not implement `AppDNAOnboardingDelegate`, the SDK stays on the step and logs a warning rather than advancing past credential collection. Auth actions require a host to perform the actual side effect (sign in, register, send OTP, …) — silently advancing would leak credentials into the response bundle without ever calling your backend. | Action | Typical button label | Payload to your handler | | --------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `login` | "Sign In" | `{action: "login", email, password}` | | `register` | "Sign Up" / "Create Account" | `{action: "register", email, password, ...optional fields}` | | `social_login` | "Continue with Google" / Apple / etc. | `{action: "social_login", provider, ...inputs}` | | `email_login` | "Continue with Email" (the email provider button inside a `social_login` block) | `{action: "email_login", email, password, ...inputs}` — added in v1.0.60. Email button still emits `social_login` in parallel one final release for back-compat; will be removed in v1.1.0. Migrate to `email_login` for clean handler routing. | | `reset_password` | "Forgot password?" | `{action: "reset_password", email}` | | `magic_link` | "Email me a sign-in link" | `{action: "magic_link", email}` | | `request_otp` | "Send code" | `{action: "request_otp", [channel], [recipient]}` — see channel resolution below | | `verify_otp` | "Verify" | `{action: "verify_otp", otp_code, [channel], [recipient]}` | | `verify_email` | "Confirm email" | `{action: "verify_email", verification_code}` | | `resend_verification` | "Resend code" | `{action: "resend_verification"}` | | `enable_biometric` | "Enable Face ID / Fingerprint" | `{action: "enable_biometric"}` — your handler calls `local_auth`'s `authenticate(...)` | ### Account lifecycle | Action | Typical button label | Payload to your handler | | ------------------ | -------------------- | ------------------------------------------------------------------------------------------- | | `logout` | "Sign out" | `{action: "logout"}` | | `change_password` | "Change password" | `{action: "change_password", current_password, new_password}` | | `set_new_password` | "Set new password" | `{action: "set_new_password", new_password, [reset_token]}` (post-reset / first-time setup) | | `delete_account` | "Delete account" | `{action: "delete_account", [confirmation_text]}` | | `update_profile` | "Save" | `{action: "update_profile", ...all step inputs}` | ### `request_otp` channel resolution `request_otp` and `verify_otp` include a `channel` field so your handler knows which delivery method to call back on. The SDK resolves it in this order: 1. **Explicit** — set the button's `action_value` to `"sms"`, `"email"`, `"whatsapp"`, or `"voice"` in the Console (case-insensitive). 2. **Auto-detect** — if the step has exactly one phone-typed input (`input_phone`) → `channel: "sms"`; exactly one email-typed input (`input_email`) → `channel: "email"`. 3. **Omitted** — if the step has both an email AND a phone input (or neither), the `channel` key is **absent** from the payload. Check with `stepData?['channel'] as String?` and fail explicitly if `null` rather than guessing. Set `action_value` on the button to disambiguate. The matching input field's value is included as `recipient` so you don't have to look it up from the step responses. ### Handling auth actions ```dart theme={null} import 'package:appdna_sdk/appdna_sdk.dart'; import 'package:local_auth/local_auth.dart'; class OnboardingHandler extends AppDNAOnboardingDelegate { final _auth = LocalAuthentication(); @override Future> onBeforeStepAdvance( String flowId, String fromStepId, int stepIndex, String stepType, Map responses, Map? stepData, ) async { final action = stepData?['action'] as String?; if (action == null) return {}; // {} == proceed 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 {}; // 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 {}; // proceed } catch (_) { return {'type': 'block', 'message': "Code didn't match — try again."}; } case 'enable_biometric': final available = await _auth.canCheckBiometrics; if (!available) return {}; // proceed final success = await _auth.authenticate( localizedReason: 'Enable Face ID / Fingerprint for faster sign-in', ); return {'type': 'proceedWithData', 'data': {'biometric_enabled': success}}; default: return {}; // proceed } } } ``` The advance hook returns a plain map (there is no `StepAdvanceResult` Dart class). Recognized shapes: | Map | Meaning | | ------------------------------------------------------ | -------------------------------------------------- | | `{}` or `{'type': 'proceed'}` | Advance normally (the default). | | `{'type': 'proceedWithData', 'data': {...}}` | Advance and merge `data` into the flow responses. | | `{'type': 'block', 'message': String}` | Stop the advance and show `message`. | | `{'type': 'skipTo', 'stepId': String, 'data': {...}?}` | Jump to `stepId` (optionally merging `data`). | | `{'type': 'stay', 'message': String?}` | Keep the current step (optionally show `message`). | Existing `next`, `skip`, `link`, `permission`, and `social_login` button actions are unchanged. Host apps that **already implement** `AppDNAOnboardingDelegate` keep working without changes — the default `onBeforeStepAdvance` returns `{}` (proceed), so flows that don't switch on `stepData?['action']` advance normally. Host apps that have NO delegate set will see the no-delegate warning above when an auth action fires; for those flows, either implement the delegate or keep using `next` as the button action. ### Custom View Registration `custom_view` blocks are rendered by a **host-native** view registered on each platform, not by a Dart widget — the Flutter plugin is a thin wrapper and does not host a Flutter surface inside the native onboarding step. There is no `AppDNA.registerCustomView(...)` in the Dart API. Register the view on the native side and reference its identifier from the `custom_view` block in the Console: * **iOS** — register a SwiftUI/UIKit view factory with the native AppDNA SDK in your `AppDelegate`. * **Android** — register a native view factory with the AppDNA SDK in your `Application`. The identifier used at registration must match the custom view identifier configured in the Console for the `custom_view` block. ### Block Styling Every content block supports a `block_style` design token that controls appearance properties such as padding, margin, background color, corner radius, border, shadow, and opacity. Block styles are configured in the Console and applied automatically by the native renderers. ### Visibility Conditions Blocks can be shown or hidden based on user responses, bindings, or device attributes. Visibility conditions are configured per-block in the Console using rules like `answer_equals`, `binding_not_empty`, `platform_is`, and `locale_matches`. The native SDK evaluates conditions client-side before rendering each block. ### Entrance Animations Each block supports an entrance animation that plays when the block first appears. Animations are configured per-block in the Console. Supported animation types include `fade`, `slide_up`, `slide_down`, `slide_left`, `slide_right`, `scale`, `flip`, and `bounce`. You can configure duration, delay, and easing curve. ## Form Steps The `form` step type provides native input fields for collecting structured user data. Each form can contain multiple fields with validation, conditional visibility, and custom configuration. Fields are rendered using native iOS controls (UIKit / SwiftUI) and native Android controls (Jetpack Compose). ### Supported Input Types | Type | Description | Example Use Case | | -------------- | ---------------------------------------- | -------------------------- | | `text` | Single-line text input | Name, username | | `textarea` | Multi-line text input | Bio, notes | | `number` | Numeric input with stepper | Age, quantity | | `email` | Email input with validation | Email address | | `phone` | Phone number input | Contact number | | `date` | Date picker | Birthday, start date | | `time` | Time picker | Preferred time | | `datetime` | Combined date and time picker | Appointment scheduling | | `select` | Dropdown or scrollable picker | Country, category | | `slider` | Numeric slider with min/max | Budget, intensity level | | `toggle` | On/off switch | Opt-in preferences | | `stepper` | Increment/decrement counter | Number of items | | `segmented` | Segmented control for few options | Gender, frequency | | `password` | Secure text input with visibility toggle | Password, PIN | | `rating` | Star rating input | Satisfaction, preference | | `range_slider` | Dual-handle range slider | Price range, age range | | `image_picker` | Photo picker from library or camera | Profile photo, document | | `color` | Color picker or preset swatches | Theme preference, branding | | `url` | URL input with validation | Website, portfolio link | | `chips` | Tag-style multi-select chips | Interests, skills | | `signature` | Freehand signature drawing pad | Agreement, consent | | `location` | Autocomplete location search | City, address, country | ### Field Validation Form fields support built-in and custom validation: * **Required fields** — marked in the Console, the SDK prevents advancing until filled. * **Regex patterns** — custom validation (e.g., `^[A-Z]{2}\d{4}$` for a code format). * **Min/max values** — for `number`, `slider`, and `stepper` fields. * **Max length** — for `text` and `textarea` fields. ### Conditional Fields Fields can depend on other fields using `depends_on` rules. For example, a "Company name" field can appear only when the user selects "Employed" in a previous field. Supported operators: `equals`, `not_equals`, `contains`, `not_empty`, `empty`, `gt`, `lt`, `is_set`. ### Form Responses Form field values are included in the `responses` map passed to `onOnboardingCompleted`, keyed by step ID. Each step's value is a map of field ID to field value. ```dart theme={null} @override void onOnboardingCompleted( String flowId, Map responses, ) { final formData = responses["profile_step"] as Map?; if (formData != null) { 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 } } ``` ### Location Fields The `location` field type provides an autocomplete search input that returns structured location data including city, state, country, coordinates, and timezone. When the user starts typing (e.g., "New York"), the native SDK debounces the input (300ms), calls the AppDNA geocoding proxy, and displays a dropdown of suggestions. The user selects a result and the SDK stores the complete structured data. #### Location Data Structure Each location selection contains: | Field | Type | Example | | ------------------- | --------- | ------------------------------------- | | `formatted_address` | `String` | `"New York, New York, United States"` | | `city` | `String` | `"New York"` | | `state` | `String` | `"New York"` | | `state_code` | `String` | `"NY"` | | `country` | `String` | `"United States"` | | `country_code` | `String` | `"US"` | | `latitude` | `double` | `40.7128` | | `longitude` | `double` | `-74.0060` | | `timezone` | `String` | `"America/New_York"` | | `timezone_offset` | `int` | `-300` (minutes from UTC) | | `postal_code` | `String?` | `null` | #### Accessing Location Data Location data is returned as a nested map in the `responses` payload to `onOnboardingCompleted`: ```dart theme={null} @override void onOnboardingCompleted( String flowId, Map responses, ) { final formData = responses["location_step"] as Map?; final location = formData?["user_location"] as Map?; 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']}"); } } ``` #### Template Engine Location data is accessible in dynamic content templates rendered by the native SDK: ``` Welcome from {{onboarding.location_step.user_location.city}}! Your timezone: {{onboarding.location_step.user_location.timezone}} ``` #### Configuration in Console In the onboarding flow editor, add a `location` field to a form step and configure: | Option | Description | Default | | -------------- | ------------------------------------------------------ | ------- | | Location Type | Filter results: `city`, `address`, `region`, `country` | `city` | | Bias Country | ISO country code to prioritize results (e.g., `US`) | None | | Language | Language for results (e.g., `en`, `fr`) | `en` | | Min Characters | Characters required before search triggers | `2` | Location autocomplete uses a server-side proxy — no third-party SDK is added to your app binary. The geocoding provider (Mapbox by default) can be configured in **Settings > Geocoding**. ## Interactive Chat Steps The `interactive_chat` step type renders a conversational UI that forwards each user message to your webhook and renders the reply. This is how you integrate your own LLM, agent, or rule-based backend into an onboarding flow. ### How it works 1. User types a message in the chat step. 2. The native SDK `POST`s the conversation payload to the `webhook_url` configured in the Console (with any custom headers you set). 3. Your server responds with JSON in the schema below. 4. The native SDK renders the AI reply, quick-reply buttons, media, etc. Turn limits, typing indicators, ratings, and quick-reply routing are handled by the native SDK — your webhook only needs to return the next reply. The conversation never round-trips through Dart. ### Request payload (SDK → your webhook) ```json theme={null} { "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 } ``` Your headers are forwarded verbatim. For bearer-token APIs, set the header value to `Bearer YOUR_TOKEN` (the SDK does **not** add the `Bearer ` prefix automatically). The `context` object is **opaque session state you control** — whatever you returned in `data` on a previous turn gets echoed back here on every subsequent call. This is how you integrate threaded AI backends (OpenAI Assistants, hosted LLMs with `threadId`, etc.) without replaying the full history on every request. `context` is absent on turn 1 (your server hasn't written anything yet) and accumulates across turns; later values overwrite earlier ones per-key (last-write-wins). See **Threaded backends** below for the full pattern. ### Response schema (your webhook → SDK) ```json theme={null} { "action": "reply", "messages": [ { "content": "Tell me more about the most recent one." } ] } ``` **Only `messages[].content` is required** — every other field is optional. The SDK reads `messages[]` to render chat bubbles, so if you omit it or return a different shape, the reply won't render. Returning a response like `{"reply": "..."}` without wrapping it in the `messages` array will silently fail — the SDK decodes unknown fields as `null` and shows nothing. Always wrap your reply in `messages[{ "content": "..." }]`. #### Full response schema | Field | Type | Description | | --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | `"reply"` \| `"reply_and_complete"` \| `"error"` | Default `"reply"`. `"reply_and_complete"` renders the reply then ends the chat. | | `messages` | `Array<{ content, media?, delay_ms? }>` | Messages to render. Empty array = silent turn. | | `messages[].content` | `string` | The bubble text. | | `messages[].media` | `{ type, url, alt_text? }` | Optional media — `type` is `"image"`, `"lottie"`, or `"link"`. | | `messages[].delay_ms` | `number` | Delay before the bubble appears (typing simulation). | | `quick_replies` | `Array<{ id, text }>` | Buttons rendered under the latest AI reply. Tapping one sends it as the user's next message. | | `force_complete` | `boolean` | End the conversation after this reply. | | `completion_message` | `string` | Final message shown when the chat completes. | | `data` | `object` | Free-form JSON. Two uses: (1) stored in the onboarding response bundle as `webhook_data` for analytics / later steps; (2) **echoed back to your webhook in `context` on every subsequent turn** — use this for `threadId`, `session_id`, or any opaque server state you need to round-trip. | Unknown fields in your response are ignored, so you can also include your own server-side state at the top level (it just won't round-trip — use `data` for anything you want back). ### Minimal working example Node.js (Express): ```javascript theme={null} 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 }], }); }); ``` ### Threaded backends: round-tripping session state If your AI service uses a thread/session handle (OpenAI Assistants API, a hosted LLM with conversation memory, or any third-party AI proxy that mints a session id), **do not replay the full conversation history on every turn** — latency and cost grow linearly with conversation length. Instead, return your session handle in `data` once; the SDK accumulates it and echoes it back in `context` on every subsequent turn. The wire contract in plain English: * **You write** to `context` by returning fields under `data` in any response. * **You read** from `context` off `req.body.context` on every request after the first. * Keys are merged across turns; later values overwrite earlier ones per-key. * The SDK never inspects or mutates `context` — it's opaque to your server. You choose the keys and the shape. Example: integrating a threaded AI service keyed by `threadId`. If your backend rotates the thread (expiry, failure, migration), just return the new id in `data` — the SDK overwrites the cached value and uses it on the next turn automatically. ```javascript theme={null} 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 }); }); ``` No server-side session store, no per-user cache, no history replay. The `context` round-trip IS your session storage. The same pattern works for anything opaque you need per-conversation: API rate-limit bucket IDs, A/B cohort labels, tool-call state, reasoning scratchpads — whatever your AI backend needs to resume, stash it in `data` and read it from `context` on the next turn. ### Console configuration In the onboarding flow editor, add a step of type **Interactive Chat**, then set: | Field | Purpose | | ----------------- | ------------------------------------------------------------------------- | | **Webhook URL** | Where the SDK `POST`s each turn | | **Headers** | Custom headers — for bearer auth, the full value must be `Bearer ` | | **Timeout (ms)** | How long to wait before showing `error_text` | | **Retry count** | Number of retries on transient network errors | | **Error text** | Shown in-chat when the webhook fails or times out | | **Persona** | Name, role, avatar — rendered in the header | | **Max turns** | Caps the conversation length | | **Auto-messages** | Pre-scripted AI messages keyed by turn number | | **Quick replies** | Static buttons always shown | | **Turn actions** | Trigger rating prompts / inject messages at specific turns | | **Style** | Colors, fonts, bubble styling | ### Auto-tracked events | Event | When | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chat_message_sent` | User sends a message | | `chat_message_received` | Webhook reply is received (even if empty) | | `chat_webhook_error` | Webhook throws, times out, returns a non-2xx status, or returns invalid JSON. Includes `http_status` and a truncated `response_body` when the error is a non-2xx response, so integration bugs surface immediately instead of silently showing an empty reply. | | `chat_rating_submitted` | User submits a rating in a turn action | The standard onboarding step events (`onboarding_step_viewed`, `onboarding_step_completed`) also fire for chat steps. ## Async Step Hooks The onboarding delegate supports two async hooks that let you intercept step transitions for server-side validation, dynamic content loading, or custom routing logic. ### onBeforeStepAdvance Called before the SDK advances to the next step. Return a `Future>` describing what happens next (there is no `StepAdvanceResult` Dart class): ```dart theme={null} @override Future> onBeforeStepAdvance( String flowId, String fromStepId, int stepIndex, String stepType, Map responses, Map? stepData, ) async { // Example: validate a referral code with your backend if (stepType == 'form') { final stepResponses = responses[fromStepId] as Map?; 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 {}; // {} == proceed } ``` #### Advance result map | Map | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{}` or `{'type': 'proceed'}` | Continue to the next step normally | | `{'type': 'proceedWithData', 'data': {...}}` | Continue and merge `data` into the session | | `{'type': 'block', 'message': String}` | Block advancement and show an error message (red banner) to the user | | `{'type': 'stay', 'message': String?}` | Stay on the current step without advancing and without showing an error. Pass a non-null `message` to render a green success banner; omit it to stay silent and let your code handle UI | | `{'type': 'skipTo', 'stepId': String}` | Skip to a specific step by ID | | `{'type': 'skipTo', 'stepId': String, 'data': {...}}` | Skip to a specific step and merge additional data (`skipToWithData`) | ##### Use `stay` for "I handled it; keep the user here" Return a `stay` map when your hook handled the user's action — for example, sent a password-reset email — and you want the user to remain on the same step. This is distinct from `block` (error styling) and from `proceed` (advances). ```dart theme={null} 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."}; } ``` ### onBeforeStepRender Called before a step is rendered. Return a `Future?>` config-override map to dynamically modify the step's content, or `null` for no override (there is no `StepConfigOverride` Dart class): ```dart theme={null} @override Future?> onBeforeStepRender( String flowId, String stepId, int stepIndex, String stepType, Map 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; } ``` Recognized keys in the override map: `fieldDefaults`, `title`, `subtitle`, `ctaText`, `layoutOverrides`. The SDK merges these into the step config before rendering. Both hooks are `async` — the SDK shows a loading indicator while waiting for your response. If either hook throws an error or times out, the SDK proceeds normally. ## Row Direction and Distribution The `row` content block supports configurable direction and distribution, set in the Console: | Property | Options | Description | | -------------- | -------------------------------------------------------------------------- | ----------------------------------------------- | | `direction` | `horizontal`, `vertical` | Axis along which child blocks are arranged | | `distribution` | `equal`, `fill`, `start`, `center`, `end`, `space_between`, `space_around` | How child blocks are distributed within the row | ``` // Example: Two buttons side by side, equally spaced Row (direction: horizontal, distribution: equal) ├── Button "Skip" └── Button "Continue" ``` ## Button Gradients Buttons support gradient backgrounds configured in the Console: | Property | Type | Description | | -------------------- | -------------- | ------------------------------------------------------------ | | `gradient_colors` | `List` | Array of hex color stops (e.g., `["#FF6B6B", "#4ECDC4"]`) | | `gradient_direction` | `String` | `horizontal`, `vertical`, `diagonal_tl_br`, `diagonal_tr_bl` | Gradients override the solid `background_color` when set. ## Select Display Styles `input_select` form-input blocks (and `select` form fields) support three display styles: | Style | Description | | ---------- | -------------------------------------------------------------------- | | `dropdown` | Native dropdown picker. Best for long option lists (5+ items). | | `stacked` | Vertically stacked option buttons. Default style. | | `grid` | Grid layout with 2 or 3 columns. Good for visual options with icons. | The display style is configured per select field in the Console under `field_config.display_style`. Question-step option lists always render in a fixed grid layout; the styles above apply specifically to `input_select` / `select`. ## Progress Bar Custom Colors The `progress_bar` content block supports custom color configuration: | Property | Type | Description | | --------------- | -------------- | ---------------------------------------------------------- | | `fill_color` | `String` | Hex color for the filled portion | | `track_color` | `String` | Hex color for the unfilled track | | `fill_gradient` | `List` | Gradient color stops for the fill (overrides `fill_color`) | | `corner_radius` | `Number` | Corner radius of the progress bar | | `height` | `Number` | Height of the progress bar in logical pixels | Colors are configured per block in the Console. When not set, the SDK uses the app's primary theme color. ## Per-Step Progress Visibility The progress indicator can be hidden on specific steps while still counting them in the total progress. This is useful for splash screens, permission prompts, or transition steps where the progress bar would be distracting. Configure `hide_progress` per step in the Console under **Step Design > Logic**. When enabled, the progress bar is hidden on that step but the step still contributes to the overall progress calculation (e.g., step 3 of 5 still advances progress to 60%). | Property | Type | Default | Description | | --------------- | ------ | ------- | ---------------------------------------------- | | `hide_progress` | `bool` | `false` | Hides the progress indicator on this step only | This is a per-step override of the flow-level `show_progress` setting. If `show_progress` is `false` at the flow level, the progress bar is hidden on all steps regardless of `hide_progress`. ## Conditional Branching Onboarding flows support conditional branching — the next step can change based on the user's answer. Branching is configured entirely in the Console. **Example:** ``` 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 ``` To configure branching: 1. In the Console, open your onboarding flow (**Onboarding > Flows**). 2. On a question step, click **Add branching rule**. 3. Map each answer option to a target step. 4. The SDK handles routing automatically — no Dart code needed. All answers (including branched paths) are returned in the `responses` map in `onOnboardingCompleted`. ## Auto-Tracked Events The native SDK automatically tracks the following onboarding-related events: | Event | Triggered When | | --------------------------- | -------------------------------------------------- | | `onboarding_flow_started` | An onboarding flow begins | | `onboarding_step_viewed` | A step is displayed to the user | | `onboarding_step_completed` | A user completes a step (e.g., answers a question) | | `onboarding_step_skipped` | A user skips a step | | `onboarding_flow_completed` | The user completes the entire flow | | `onboarding_flow_dismissed` | The user dismisses the flow before completing | Each event includes the `flowId`, `stepId`, and `stepIndex` where applicable. ## Configuration in Console Onboarding flows are managed in the AppDNA Console: 1. Navigate to **Onboarding > Flows**. 2. Create a new flow or edit an existing one. 3. Add steps (welcome, question, value\_prop, form, interactive\_chat, custom) and configure their content. 4. Set targeting rules to control which users see the flow. 5. Publish the flow to make it available to the SDK via the config bundle. Flows must be published in the Console before they appear in the SDK. Draft flows are not delivered to client devices. ## Full Example ```dart theme={null} import 'package:appdna_sdk/appdna_sdk.dart'; import 'package:flutter/material.dart'; class OnboardingScreen extends StatefulWidget { const OnboardingScreen({super.key}); @override State createState() => _OnboardingScreenState(); } class _OnboardingScreenState extends State implements AppDNAOnboardingDelegate { @override void initState() { super.initState(); AppDNA.onboarding.setDelegate(this); _showOnboardingIfNeeded(); } Future _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 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> onBeforeStepAdvance(String flowId, String fromStepId, int stepIndex, String stepType, Map responses, Map? stepData) async => {}; @override Future?> onBeforeStepRender(String flowId, String stepId, int stepIndex, String stepType, Map responses) async => null; @override Future?> onElementInteraction(String flowId, String stepId, String blockId, String action, String? value, Map inputValues) async => null; @override Future?> 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()), ); } } ``` ## Paywall trigger nodes — entitlement-aware skip + restore behavior Onboarding flows can include `paywall_trigger` graph nodes that present a paywall in the middle of a flow and route the user via per-outcome targets (`on_success_target`, `on_fail_target`, `on_dismiss_target`). Triggers are configured in the AppDNA Console and the SDK presents them automatically when the flow reaches the node. ### Entitlement-aware skip (default ON) Each paywall\_trigger node carries a `skip_if_subscribed` flag (default `true`). When the native SDK reaches the trigger, it checks the user's entitlement state first: * **User has an active subscription** → SDK skips presentation, emits an `onboarding_paywall_skip` event with `reason=user_already_subscribed`, and routes the flow via the configured skip target (see below). * **User has no active subscription** → SDK presents the paywall as before; outcome routing is unchanged. This stops returning users from seeing a paywall they already paid for. Already-subscribed users move past the trigger silently. If you sell **upsell paywalls** (a higher tier to a user who already owns the base plan), open the trigger in the onboarding flow editor and uncheck **Skip if user already has an active subscription**. The trigger then always presents. ```text theme={null} ☑ Skip if user already has an active subscription ← default for new + legacy nodes ``` Existing flows authored before this version require no migration: nodes without the field default to `true` at read time. From Flutter you can check the same entitlement state used by the gate via: ```dart theme={null} final hasSub = await AppDNA.billing.hasActiveSubscription(); ``` ### Subscribed-user skip routing — picking the target The console editor exposes a dedicated dropdown directly under the **Skip if user already has an active subscription** toggle: **When skipped (user is already subscribed), go to**. Four options: | Option | Stored value | When to pick | | ------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Complete flow (recommended)** | `complete_flow` | Subscribed user bypasses the paywall **and** everything downstream — flow ends, host's `onOnboardingCompleted` fires. **Default for new paywall\_trigger nodes.** | | Use post-purchase target | `''` (empty) | Falls back to whatever `on_success_target` is set to — useful when the post-purchase target and the skip target should be identical. | | Follow downstream edge | `continue` | Subscribed user continues through the rest of the graph (rare — used for chain-of-paywalls flows that intentionally show more upsells after the gate). | | Go to: `` | the node ID | Route directly to a specific step or end node. | The native SDKs resolve the target with this chain at runtime: `on_subscribed_skip_target` → falls back to `on_success_target` → falls back to "follow downstream edge". The fallback means flows authored without an explicit skip target that worked around this by setting `on_success_target = complete_flow` continue to behave identically. #### Warning callout in the editor If you open a paywall\_trigger that has **Skip if user already has an active subscription** on but the resolved skip target is "Follow downstream edge" **and** the next node in the graph is another paywall\_trigger, the editor displays an inline warning: > Heads up: this paywall is set to skip for subscribed users, but the next step is another paywall trigger — subscribed users will still see it. Set "When skipped" to "Complete flow" to bypass the rest of the paywall chain. One click on **Complete flow** in the dropdown clears the warning and fixes the chain. This is the most common authoring trap with multi-paywall flows (main paywall → winback paywall → end); the warning surfaces it before publish. ### Restore now auto-dismisses + routes to success Tapping **Restore Subscription** on a paywall now: 1. Fires `onPaywallRestoreCompleted(paywallId, restoredProductIds)` on your `AppDNAPaywallDelegate`. 2. **Auto-dismisses the native paywall surface** when `restoredProductIds` is non-empty (i.e., the restore actually found entitlements). 3. Routes the onboarding flow via the trigger's `on_success_target` — same path as a real purchase. When the restore call succeeds but finds NO entitlements (`restoredProductIds: []`) the paywall stays up so the user can attempt a fresh purchase or close manually. ```dart theme={null} class MyPaywallDelegate extends AppDNAPaywallDelegate { @override void onPaywallRestoreCompleted( String paywallId, List 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 } ``` #### Hosts that handle their own dismiss If your `onPaywallRestoreCompleted` handler already dismisses the paywall itself (e.g., to show a "Restored — tap continue when ready" overlay), the SDK's internal `dispatchedDismiss` guard ensures the auto-dismiss never fires twice — the first caller wins. `onPaywallDismissed` fires exactly once regardless of who triggered the dismissal. ```dart theme={null} class MyPaywallDelegate extends AppDNAPaywallDelegate { @override void onPaywallRestoreCompleted(String paywallId, List productIds) { // Your custom UI handling — show overlay, etc. // No need to dismiss yourself; the SDK auto-dismiss path // handles dismissal once your synchronous body returns. If you // want to suppress the SDK auto-dismiss (e.g., to show your own // overlay), call AppDNA.skipNextAutoDismissOnRestore(true) first // — the dispatchedDismiss guard prevents a second auto-dismiss. } } ``` Synchronous host-side dismisses inside the delegate body always win the race. ### `AppDNA.identify(userId)` refreshes the entitlement cache When you call `AppDNA.identify(...)` after the user signs in, the native SDK silently refreshes its entitlement cache in the background. The next paywall\_trigger gate then reflects the identified user's StoreKit / Play Billing subscriptions instead of the prior anonymous user's empty entitlement state. ```dart theme={null} 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. ``` If your app completes auth out-of-band (SSO callback, OAuth web flow) and you need the entitlement cache refreshed manually, call `AppDNA.identify(...)` again with the same user ID — the cache refresh is idempotent. ### Migration risk callout **Behavioral change**: paywall\_trigger nodes now skip presentation for subscribed users by default. If your app intentionally relies on the legacy "always present" behavior (e.g., a confirmation / legal-acceptance screen rendered as a paywall), open the trigger node in the console editor and uncheck **Skip if user already has an active subscription**. **Web-side entitlements** (Stripe subscriptions, manually-granted entitlements via web tooling) are NOT consulted by this gate today — only StoreKit (iOS) and Play Billing (Android) entitlements are. If your premium users have only web-side subscriptions, leave **Skip if user already has an active subscription** unchecked, or implement a host-side gate via `AppDNAOnboardingDelegate.onBeforeStepRender` that consults your own backend. ## Measurement mode (wheel\_picker) `wheel_picker` supports an optional **measurement mode** for capturing a weight, height, temperature, or any custom quantity with a unit toggle. Enable it in the console by setting a **measurement type** (Weight, Height, Temperature, or Custom) on the wheel picker. When set, the picker renders with: * a **unit toggle** (e.g. kg ⇄ lbs, cm ⇄ in, °C ⇄ °F) that converts the value live, and * a measurement visual **style** — `ruler` (tick tape), `gauge` (radial dial), `dial` (rotary drum), or `wheel` (classic drum). Each unit defines its own range and step; toggling converts the current value and re-clamps it to the new unit's range. ### Reported value The SDK stores the value in the **base unit** (the first unit you define) so it stays stable when the user flips units. Alongside it, the SDK reports the chosen unit and the displayed value: | Key | Meaning | | -------------------------- | ---------------------------------------------- | | `` | value in the base unit (stable across toggles) | | `_unit` | the base unit id | | `_display_unit` | the unit the user selected | | `_display_value` | value shown in the selected unit | The element-interaction callback receives `{ value, display_value, unit }`, where `value` is the base-unit value. When no measurement type is set, `wheel_picker` behaves exactly as before.