> ## 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.
# React Native Onboarding
> Present server-driven onboarding flows
**Supported on:** iOS SDK `1.0.70+` · Android SDK `1.0.42+` · React Native SDK `1.0.7+` (New Architecture only)
The AppDNA React Native 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 `Promise` that resolves `true` once the native flow surface is shown, or `false` when nothing could present it. It never rejects:
```typescript theme={null}
import { AppDNA } from '@appdna-ai/react-native-sdk';
const shown = await AppDNA.presentOnboarding('main_flow');
if (!shown) {
console.log('Flow config not available — check Console or network');
}
```
If the flow ID is unknown to the SDK or the remote config bundle has not finished loading, the call resolves `false` as a no-op and a debug-level log entry is emitted.
The React Native 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`:
```typescript theme={null}
const onboarding = AppDNA.onboarding;
```
### Module Methods
| Method | Signature | Description |
| ------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `present` | `present(flowId: string): Promise` | Present an onboarding flow. Resolves `false` when nothing could present it. |
| `setDelegate` | `setDelegate(delegate: Partial \| null): void` | Set a delegate for flow callbacks. Pass `null` to clear it — registering again replaces it |
The static `AppDNA.presentOnboarding(flowId)` is a convenience that calls `AppDNA.onboarding.present(flowId)`.
`present()` takes a flow ID and nothing else. To personalize a flow, set user traits
(`AppDNA.identify(userId, traits)`) or session data (`AppDNA.session.set(...)`) before presenting —
the flow's audience rules and templated copy read from those. Experiment variants are assigned by the
AppDNA backend; there is no client-side override.
## 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 [React Native paywall docs](/sdks/react-native/paywall) for the full delegate surface.
## AppDNAOnboardingDelegate
Implement the `AppDNAOnboardingDelegate` interface 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.
```typescript theme={null}
interface AppDNAOnboardingDelegate {
onOnboardingStarted(flowId: string): void;
onOnboardingStepChanged(
flowId: string,
stepId: string,
stepIndex: number,
totalSteps: number,
): void;
onOnboardingCompleted(flowId: string, responses: Record): void;
onOnboardingDismissed(flowId: string, atStep: number): void;
/** Observe-only: fires after an onboarding permission resolves, however it resolved. */
onPermissionResult(
flowId: string,
stepId: string,
permissionType: string,
granted: boolean,
): void;
// Async veto hooks — see "Async Step Hooks" below. Each returns a plain object that native
// decodes; the TypeScript return type is Record.
onBeforeStepAdvance?(
flowId: string,
fromStepId: string,
stepIndex: number,
stepType: string,
responses: Record,
stepData: Record | undefined,
): Promise>;
onBeforeStepRender?(
flowId: string,
stepId: string,
stepIndex: number,
stepType: string,
responses: Record,
): Promise | null>;
onElementInteraction?(
flowId: string,
stepId: string,
blockId: string,
action: string,
value: string | undefined,
inputValues: Record,
): Promise | null>;
onPermissionRequest?(permissionType: string): Promise | null>;
}
```
### Set the Delegate
```typescript theme={null}
declare const myOnboardingDelegate: AppDNAOnboardingDelegate;
AppDNA.onboarding.setDelegate(myOnboardingDelegate);
```
### Example Implementation
```typescript theme={null}
const onboardingHandler: AppDNAOnboardingDelegate = {
onOnboardingStarted(flowId) {
console.log(`Onboarding started: ${flowId}`);
},
onOnboardingStepChanged(flowId, stepId, stepIndex, totalSteps) {
console.log(`Step ${stepIndex + 1}/${totalSteps}: ${stepId}`);
// Update progress indicator
},
onOnboardingCompleted(flowId, responses) {
console.log(`Onboarding completed: ${flowId}`);
console.log('User responses:', responses);
// Navigate to main app screen
// Use responses to personalize the experience
},
onOnboardingDismissed(flowId, atStep) {
console.log(`Onboarding dismissed at step ${atStep}`);
// Handle early exit — maybe show again later
},
onPermissionResult(flowId, stepId, permissionType, granted) {
console.log(`${permissionType} permission: ${granted ? 'granted' : 'denied'}`);
},
};
```
## 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 React Native.
### 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 TypeScript 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 `{ type: '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 `react-native-biometrics` or `expo-local-authentication` |
### 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 | undefined` and fail explicitly if `null` / `undefined` 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
```typescript theme={null}
import { AppDNA, type AppDNAOnboardingDelegate } from '@appdna-ai/react-native-sdk';
import ReactNativeBiometrics from 'react-native-biometrics';
declare const authClient: {
signIn(a: { email: string; password: string }): Promise<{ id: string }>;
register(a: { email: string; password: string }): Promise<{ id: string }>;
requestPasswordReset(a: { email: string }): Promise;
};
declare const otpClient: {
send(a: { channel: string; to: string }): Promise;
verify(a: { code: string; recipient: string }): Promise;
};
const biometrics = new ReactNativeBiometrics();
const onboardingHandler: AppDNAOnboardingDelegate = {
onOnboardingStarted: () => {},
onOnboardingStepChanged: () => {},
onOnboardingCompleted: () => {},
onOnboardingDismissed: () => {},
onPermissionResult: () => {},
async onBeforeStepAdvance(flowId, fromStepId, stepIndex, stepType, responses, stepData) {
const action = stepData?.action as string | undefined;
if (!action) return { type: 'proceed' };
switch (action) {
case 'login': {
const email = (stepData?.email as string) ?? '';
const password = (stepData?.password as string) ?? '';
try {
const user = await authClient.signIn({ email, password });
return { type: 'proceedWithData', data: { user_id: user.id } };
} catch {
return { type: 'block', message: 'Invalid email or password.' };
}
}
case 'register': {
const email = (stepData?.email as string) ?? '';
const password = (stepData?.password as string) ?? '';
try {
const user = await authClient.register({ email, 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': {
const email = (stepData?.email as string) ?? '';
try {
await authClient.requestPasswordReset({ email });
} catch {
// Stay quiet; we always show the same confirmation banner
}
// 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.
const channel = stepData?.channel as string | undefined;
const recipient = stepData?.recipient as string | undefined;
if (!channel || !recipient) {
return {
type: 'block',
message: "Couldn't determine OTP delivery channel — please contact support.",
};
}
try {
await otpClient.send({ channel, to: recipient });
return { type: 'proceed' };
} catch {
return { type: 'block', message: "Couldn't send code — please retry." };
}
}
case 'verify_otp': {
const code = stepData?.otp_code as string | undefined;
const recipient = stepData?.recipient as string | undefined;
if (!code || !recipient) {
return { type: 'block', message: 'Missing code or recipient.' };
}
try {
await otpClient.verify({ code, recipient });
return { type: 'proceed' };
} catch {
return { type: 'block', message: "Code didn't match — try again." };
}
}
case 'enable_biometric': {
const { available } = await biometrics.isSensorAvailable();
if (!available) return { type: 'proceed' };
const { success } = await biometrics.simplePrompt({
promptMessage: 'Enable Face ID / Fingerprint for faster sign-in',
});
return { type: 'proceedWithData', data: { biometric_enabled: success } };
}
default:
return { type: 'proceed' };
}
},
};
AppDNA.onboarding.setDelegate(onboardingHandler);
```
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 `{ type: '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 Views
A `custom_view` block renders a view **you** supply. On React Native it is registered from your
**native** code — Swift or Kotlin — not from JavaScript:
```swift theme={null}
// ios/AppDelegate.swift
AppDNA.registerCustomView("terms_acceptance") {
AnyView(TermsAcceptanceView()) // your SwiftUI view
}
```
```kotlin theme={null}
// android/app/.../MainApplication.kt
AppDNA.registerCustomView("terms_acceptance") { config ->
TermsAcceptanceView(config) // your @Composable
}
```
The key must match the custom-view identifier configured in the Console for the `custom_view` block.
**You cannot register a React component here, and earlier revisions of this page were wrong to say
you could.** The onboarding flow is rendered by the native SDK (SwiftUI / Jetpack Compose), and
`registerCustomView` takes a native view factory — an `AnyView` or a `@Composable`. JavaScript has
neither to hand it.
Hosting a React surface inside a native onboarding step is genuinely possible (via
`RCTFabricSurface` / `ReactHost.createSurface`), but it is a real piece of engineering with a real
failure mode — Yoga and SwiftUI/Compose disagree about intrinsic sizing, and a surface that reports
zero height collapses the block. It is tracked separately and is not in this release. If your custom
view must be React, keep that content outside the flow for now, or use
[``](/sdks/react-native/screens), which embeds a server-driven screen inline in
your own React layout.
### 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.
```typescript theme={null}
const delegate: Pick = {
onOnboardingCompleted(flowId, responses) {
const formData = responses['profile_step'] as Record | undefined;
if (formData) {
const name = formData['full_name'] as string | undefined;
const age = formData['age'] as number | undefined;
const email = formData['email'] as string | undefined;
// Use collected data to personalize the experience
console.log(flowId, name, age, email);
}
},
};
```
### 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` | `number` | `40.7128` |
| `longitude` | `number` | `-74.0060` |
| `timezone` | `string` | `"America/New_York"` |
| `timezone_offset` | `number` | `-300` (minutes from UTC) |
| `postal_code` | `string?` | `null` |
#### Accessing Location Data
Location data is returned as a nested object in the `responses` payload to `onOnboardingCompleted`:
```typescript theme={null}
const delegate: Pick = {
onOnboardingCompleted(flowId, responses) {
const formData = responses['location_step'] as Record | undefined;
const location = formData?.user_location as Record | undefined;
if (location) {
console.log('City:', location.city); // "New York"
console.log('Country:', location.country_code); // "US"
console.log('Timezone:', location.timezone); // "America/New_York"
console.log('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 JavaScript.
### 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 carries four **async veto hooks**. They are not observations: native pauses
the flow and waits for your answer before it proceeds. Each is optional; if you omit one — or take
longer than `vetoTimeout` (5 seconds by default) — native applies the hook's own default and moves on.
| Hook | Answer with | Default if you don't answer |
| ---------------------- | --------------------------------------------- | --------------------------- |
| `onBeforeStepAdvance` | a `StepAdvanceResult` object | proceed |
| `onBeforeStepRender` | a `StepConfigOverride` object, or `null` | render unchanged |
| `onElementInteraction` | a live-state result, or `null` | no state change |
| `onPermissionRequest` | `{ handledByHost: true, granted }`, or `null` | run the OS prompt |
Their TypeScript return type is `Promise>` (or `| null`) — the objects below
are what native decodes out of it.
### onBeforeStepAdvance
Called before the SDK advances to the next step. Return a `StepAdvanceResult` to control what happens
next:
```typescript theme={null}
declare function validateReferralCode(code: string): Promise;
const delegate: Pick = {
async onBeforeStepAdvance(flowId, fromStepId, stepIndex, stepType, responses, stepData) {
// Example: validate a referral code with your backend
if (stepType === 'form') {
const stepResponses = responses[fromStepId] as Record | undefined;
const code = stepResponses?.referral_code as string | undefined;
if (code) {
const isValid = await validateReferralCode(code);
if (!isValid) {
return { type: 'block', message: 'Invalid referral code. Please try again.' };
}
return { type: 'proceedWithData', data: { referral_validated: true } };
}
}
return { type: 'proceed' };
},
};
AppDNA.onboarding.setDelegate(delegate as AppDNAOnboardingDelegate);
```
#### StepAdvanceResult
| Case | Description |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ type: 'proceed' }` | Continue to the next step normally |
| `{ type: 'proceedWithData', data }` | Continue and merge additional data into the session |
| `{ type: 'block', message }` | Block advancement and show an error message (red banner) to the user |
| `{ type: 'stay', message? }` | Stay on the current step without advancing and without showing an error. Pass a `message` to render a green success banner; omit it to stay silent and handle the UI yourself |
| `{ type: 'skipTo', stepId, data? }` | Skip to a specific step by ID, merging `data` into the session when you pass it |
An unrecognised `type` is **not** an error — native falls back to `proceed` and the user advances to
the next step. Get the string right: a typo routes the user somewhere you did not intend, silently.
##### Use `stay` for "I handled it; keep the user here"
Use `{ type: 'stay', ... }` 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).
```typescript theme={null}
declare const myAuthBackend: { sendPasswordReset(args: { to: string }): Promise };
const delegate: Pick = {
async onBeforeStepAdvance(flowId, fromStepId, stepIndex, stepType, responses, stepData) {
switch (stepData?.action) {
case 'reset_password': {
const email = ((responses[fromStepId] as Record)?.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." };
}
}
default:
return { type: 'proceed' };
}
},
};
```
### onBeforeStepRender
Called before a step is rendered. Return a `StepConfigOverride` to dynamically modify the step's
content, or `null` to leave it as authored:
```typescript theme={null}
declare const currentUser: { email: string; displayName: string; firstName: string };
const delegate: Pick = {
async onBeforeStepRender(flowId, stepId, stepIndex, stepType, responses) {
// 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;
},
};
```
Available fields on `StepConfigOverride`: `fieldDefaults`, `title`, `subtitle`, `ctaText`,
`layoutOverrides`. The SDK merges these into the step config before rendering.
### onElementInteraction
Called when the user interacts with a block inside a step — a button, a chip, a toggle. Return a
live-state result to update the step in place, or `null` for no change.
```typescript theme={null}
const delegate: Pick = {
async onElementInteraction(flowId, stepId, blockId, action, value, inputValues) {
if (blockId === 'check_availability' && typeof value === 'string') {
const taken = await fetch(`https://api.example.com/handle/${value}`).then((r) => r.ok);
return { fieldErrors: { handle: taken ? 'That handle is taken' : null } };
}
return null;
},
};
```
### onPermissionRequest
Called *before* the SDK shows an OS permission prompt from a `permission` step. Return
`{ handledByHost: true, granted }` to short-circuit it (you asked for the permission yourself, or you
know the answer), or `null` to let the native flow run.
```typescript theme={null}
const delegate: Pick = {
async onPermissionRequest(permissionType) {
if (permissionType === 'notifications' && __DEV__) {
return { handledByHost: true, granted: true }; // never prompt in dev builds
}
return null;
},
onPermissionResult(flowId, stepId, permissionType, granted) {
console.log(`${permissionType} → ${granted}`);
},
};
```
Every hook is `async` — the SDK shows a loading indicator while waiting. If a hook throws or times
out, the SDK applies the default in the table above and continues; it never hangs the flow.
## 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` | `string[]` | 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` | `string[]` | 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` | `boolean` | `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 TypeScript 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
```tsx theme={null}
import React, { useEffect } from 'react';
import { View, ActivityIndicator } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import { AppDNA, AppDNAOnboardingDelegate } from '@appdna-ai/react-native-sdk';
export function OnboardingScreen() {
const navigation = useNavigation();
useEffect(() => {
const delegate: AppDNAOnboardingDelegate = {
onOnboardingStarted(flowId) {
console.log(`Starting flow: ${flowId}`);
},
onOnboardingStepChanged(flowId, stepId, stepIndex, totalSteps) {
// Track progress
},
onOnboardingCompleted(flowId, responses) {
// Personalize based on responses
const goal = responses['fitness_goal'] as string | undefined;
if (goal) {
AppDNA.identify('current_user_id', { fitness_goal: goal });
}
navigation.replace('Home');
},
onOnboardingDismissed(flowId, atStep) {
navigation.replace('Home');
},
onPermissionResult(flowId, stepId, permissionType, granted) {
// Observe-only
},
};
// Pass null to clear the delegate; registering a new one replaces it.
AppDNA.onboarding.setDelegate(delegate);
showOnboardingIfNeeded();
}, [navigation]);
async function showOnboardingIfNeeded() {
// `present` takes the flow ID and nothing else, and resolves `false` when there was no
// view controller / activity to present from.
const presented = await AppDNA.onboarding.present('main_flow');
if (!presented) {
navigation.replace('Home');
}
}
return (
);
}
```
## 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 React Native you can check the same entitlement state used by the gate via:
```typescript theme={null}
const 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.
```typescript theme={null}
const paywallDelegate: Pick = {
// ... plus the other AppDNAPaywallDelegate methods
onPaywallRestoreCompleted(paywallId, restoredProductIds) {
if (restoredProductIds.length > 0) {
console.log(`Restored ${restoredProductIds.length} product(s) — SDK is dismissing the paywall.`);
} else {
console.log('Restore returned no entitlements — paywall stays open.');
}
},
};
AppDNA.paywall.setDelegate(paywallDelegate as AppDNAPaywallDelegate);
```
#### 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.
```typescript theme={null}
const paywallDelegate: Pick = {
// ... plus the other AppDNAPaywallDelegate methods
onPaywallRestoreCompleted(paywallId, productIds) {
// Your custom UI handling — show overlay, etc.
// No need to dismiss anything yourself: the SDK's auto-dismiss path
// runs once your body returns. (Earlier revisions of this page told
// you to call `AppDNA.paywall.dismiss()` — no such method has ever
// existed on any platform. There is no host-callable paywall dismiss;
// the SDK owns the paywall's lifecycle.)
},
};
```
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.
```typescript theme={null}
await AppDNA.identify('user_abc', { 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.