iOS Onboarding

let presented = AppDNA.presentOnboarding(
    flowId: "main_flow",
    from: viewController,
    delegate: self
)

if !presented {
    print("Flow config not available — check Console or network")
}

let onboarding = AppDNA.onboarding

let context = OnboardingContext(
    source: "app_launch",
    campaign: "winter_2025",
    referrer: "social_ad",
    userProperties: ["locale": "en_US"],
    experimentOverrides: ["onboarding_variant": "b"]
)

AppDNA.onboarding.present(
    flowId: "main_flow",
    from: viewController,
    context: context
)

protocol AppDNAOnboardingDelegate {
    func onOnboardingStarted(flowId: String)
    func onOnboardingStepChanged(flowId: String, stepId: String, stepIndex: Int, totalSteps: Int)
    func onOnboardingCompleted(flowId: String, responses: [String: Any])
    func onOnboardingDismissed(flowId: String, atStep: Int)

    // Async hooks (optional — default implementations provided)
    func onBeforeStepAdvance(flowId: String, fromStepId: String, stepIndex: Int, stepType: String, responses: [String: Any], stepData: [String: Any]?) async -> StepAdvanceResult
    func onBeforeStepRender(flowId: String, stepId: String, stepIndex: Int, stepType: String, responses: [String: Any]) async -> StepConfigOverride?

    // Backend-interactive elements (1.0.67+) — fires DURING render when an interactive element acts
    func onElementInteraction(flowId: String, stepId: String, blockId: String, action: String, value: String?, inputValues: [String: Any]) async -> ElementInteractionResult?
}

class OnboardingHandler: AppDNAOnboardingDelegate {
    func onOnboardingStarted(flowId: String) {
        print("Onboarding started: \(flowId)")
    }

    func onOnboardingStepChanged(
        flowId: String,
        stepId: String,
        stepIndex: Int,
        totalSteps: Int
    ) {
        print("Step \(stepIndex + 1)/\(totalSteps): \(stepId)")
        // Update progress indicator
    }

    func onOnboardingCompleted(flowId: String, responses: [String: Any]) {
        print("Onboarding completed: \(flowId)")
        print("User responses: \(responses)")
        // Navigate to main app screen
        // Use responses to personalize the experience
    }

    func onOnboardingDismissed(flowId: String, atStep: Int) {
        print("Onboarding dismissed at step \(atStep)")
        // Handle early exit — maybe show again later
    }
}

func onElementInteraction(
    flowId: String,
    stepId: String,
    blockId: String,        // the interacting block's id
    action: String,         // canonical per-element string — see the table below
    value: String?,         // optional payload (e.g. the tapped value)
    inputValues: [String: Any]   // live snapshot of the step's collected values
) async -> ElementInteractionResult?

public struct ElementInteractionResult {
    // Per-block field_config patches to merge + re-render, keyed blockId → (key → value)
    public var fieldConfigPatches: [String: [String: Any]]?
    // Patches merged into the step's CURRENT inputValues, key by key, keyed by field_id
    public var inputValuePatches: [String: Any]?
    // Replacement options for a Select, keyed by blockId (the same shape as StepConfigOverride.fieldOptions)
    public var fieldOptions: [String: [InputOption]]?
    // When true, advance to the next step after handling the interaction
    public var advance: Bool
    // New host data for this step, merged into {{hook_data.…}} per top-level key; NSNull() removes a key.
    // See "Show more" under Host-supplied data. iOS SDK 1.0.82+.
    public var dataContext: [String: Any]?
}

func onElementInteraction(
    flowId: String,
    stepId: String,
    blockId: String,
    action: String,
    value: String?,
    inputValues: [String: Any]
) async -> ElementInteractionResult? {
    switch action {
    case "health_connect":
        let granted = await healthClient.requestAuthorization()
        guard granted else { return nil }   // leave the card unchanged
        return ElementInteractionResult(
            fieldConfigPatches: [blockId: ["connected": true]],
            inputValuePatches: ["health_connected": true]
        )
    default:
        return nil
    }
}

// Observe the outcome
func onPermissionResult(flowId: String, stepId: String, permissionType: String, granted: Bool)

// Optionally handle the request yourself instead of the SDK prompting
func onPermissionRequest(_ permissionType: String) async -> PermissionHandling?
// return .handledByHost(granted: Bool) to take over, or .proceed / nil to let the SDK prompt

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

class OnboardingHandler: AppDNAOnboardingDelegate {
    /// The sign-in actions (the Authentication entry and Account lifecycle tables above).
    private static let signInActions: Set<String> = [
        "social_login", "login", "register", "reset_password", "magic_link", "email_login",
        "request_otp", "verify_otp", "verify_email", "resend_verification", "enable_biometric",
        "logout", "change_password", "set_new_password", "delete_account", "update_profile",
    ]

    func onBeforeStepAdvance(
        flowId: String,
        fromStepId: String,
        stepIndex: Int,
        stepType: String,
        responses: [String: Any],
        stepData: [String: Any]?
    ) async -> StepAdvanceResult {
        guard let action = stepData?["action"] as? String else {
            return .proceed
        }

        switch action {
        case "login":
            let email = stepData?["email"] as? String ?? ""
            let password = stepData?["password"] as? String ?? ""
            do {
                let user = try await authClient.signIn(email: email, password: password)
                return .proceedWithData(["user_id": user.id])
            } catch {
                return .block(message: "Invalid email or password.")
            }

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

        case "reset_password":
            let email = stepData?["email"] as? String ?? ""
            try? await authClient.requestPasswordReset(email: email)
            // Stay on step; the user is told the email was sent (a green banner, not an error).
            return .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.
            guard let channel = stepData?["channel"] as? String,
                  let recipient = stepData?["recipient"] as? String else {
                return .block(message: "Couldn't determine OTP delivery channel — please contact support.")
            }
            do {
                try await otpClient.send(channel: channel, to: recipient)
                return .proceed
            } catch {
                return .block(message: "Couldn't send code — please retry.")
            }

        case "verify_otp":
            guard let code = stepData?["otp_code"] as? String,
                  let recipient = stepData?["recipient"] as? String else {
                return .block(message: "Missing code or recipient.")
            }
            do {
                try await otpClient.verify(code: code, recipient: recipient)
                return .proceed
            } catch {
                return .block(message: "Code didn't match — try again.")
            }

        case "enable_biometric":
            let context = LAContext()
            var error: NSError?
            if context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {
                let success = (try? await context.evaluatePolicy(
                    .deviceOwnerAuthenticationWithBiometrics,
                    localizedReason: "Enable Face ID for faster sign-in"
                )) ?? false
                return .proceedWithData(["biometric_enabled": success])
            }
            return .proceed

        default:
            // Never `.proceed` a sign-in action this switch does not handle — nobody authenticated
            // the user. Any other action (a plain `next`, a flag CTA, …) advances as usual.
            if Self.signInActions.contains(action) {
                return .block(message: "Sign-in isn't available right now. Please try again later.")
            }
            return .proceed
        }
    }
}

AppDNA.registerCustomView("my_view") {
    AnyView(MySwiftUIView())
}

// Register before presenting the onboarding flow
AppDNA.registerCustomView("terms_acceptance") {
    AnyView(TermsAcceptanceView(onAccept: { accepted in
        // Handle acceptance
    }))
}

func onOnboardingCompleted(flowId: String, responses: [String: Any]) {
    if let formData = responses["profile_step"] as? [String: Any] {
        let name = formData["full_name"] as? String
        let age = formData["age"] as? Int
        let email = formData["email"] as? String
        // Use collected data to personalize the experience
    }
}

func onOnboardingCompleted(flowId: String, responses: [String: Any]) {
    let flags = responses["flags"] as? [String: Any] ?? [:]

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

if let location = AppDNA.getLocationData(fieldId: "user_location") {
    print("Address: \(location.formatted_address)")
    if let lat = location.latitude, let lng = location.longitude {
        print("Coords: \(lat), \(lng)")          // a selected suggestion
    } else {
        print("Typed: \(location.raw_query ?? "")") // typed without selecting
    }
    print("City: \(location.city ?? "-")")
    print("Timezone: \(location.timezone ?? "-")")
}

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

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

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

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

  const replyText = await myLLM.complete(userMessage);

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

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

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

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

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

class ReferralHandler: AppDNAOnboardingDelegate {
    /// The sign-in actions (the same set as in "Handling auth actions" above).
    private static let signInActions: Set<String> = [
        "social_login", "login", "register", "reset_password", "magic_link", "email_login",
        "request_otp", "verify_otp", "verify_email", "resend_verification", "enable_biometric",
        "logout", "change_password", "set_new_password", "delete_account", "update_profile",
    ]

    func onBeforeStepAdvance(
        flowId: String,
        fromStepId: String,
        stepIndex: Int,
        stepType: String,
        responses: [String: Any],
        stepData: [String: Any]?
    ) async -> StepAdvanceResult {
        // This hook handles no sign-in action, so it must never advance one: nobody authenticated the user.
        if let action = stepData?["action"] as? String, Self.signInActions.contains(action) {
            return .block(message: "Sign-in isn't available right now. Please try again later.")
        }

        // Example: validate a referral code with your backend
        if stepType == "form",
           let code = (responses[fromStepId] as? [String: Any])?["referral_code"] as? String {
            let isValid = await validateReferralCode(code)
            if !isValid {
                return .block(message: "Invalid referral code. Please try again.")
            }
            return .proceedWithData(["referral_validated": true])
        }
        return .proceed
    }

    private func validateReferralCode(_ code: String) async -> Bool {
        // Call your backend here.
        return !code.isEmpty
    }
}

case "reset_password":
    let email = (responses[fromStepId] as? [String: Any])?["email"] as? String ?? ""
    do {
        try await myAuthBackend.sendPasswordReset(to: email)
        return .stay(message: "Reset email sent to \(email)")
    } catch {
        return .block(message: "Couldn't send reset email. Please try again.")
    }

func onBeforeStepRender(
    flowId: String,
    stepId: String,
    stepIndex: Int,
    stepType: String,
    responses: [String: Any]
) async -> StepConfigOverride? {
    // Pre-fill form fields based on user data
    if stepId == "profile_step" {
        return StepConfigOverride(
            fieldDefaults: [
                "email": currentUser.email,
                "name": currentUser.displayName
            ],
            title: "Welcome back, \(currentUser.firstName)!"
        )
    }
    return nil
}

AppDNA.registerMapView("default") { config in
    AnyView(MyMapView(config: config))
}

// Example: Two buttons side by side, equally spaced
Row (row_direction: horizontal, row_distribution: space_between, row_child_fill: false)
  ├── Button "Skip"
  └── Button "Continue"

func onBeforeStepRender(
    flowId: String, stepId: String, stepIndex: Int, stepType: String,
    responses: [String: Any]
) async -> StepConfigOverride? {
    let booking = await myBackend.booking(for: stepId)   // your client, your auth
    return StepConfigOverride(dataContext: [
        "booking": ["unitPrice": booking.unitPrice, "venue": booking.venueName],
    ])
}

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

func onBeforeStepRender(
    flowId: String, stepId: String, stepIndex: Int, stepType: String,
    responses: [String: Any]
) async -> StepConfigOverride? {
    guard stepId == "step8" else { return nil }
    let venues = await myBackend.recommendations(for: responses)   // your client, your auth
    return StepConfigOverride(dataContext: [
        "recommendations": venues.map { w in
            ["id": w.id, "name": w.name, "subtitle": w.region, "imageUrl": w.photoURL.absoluteString]
        },
    ])
}

// Your paging state, per step. Also answer onBeforeStepRender with it on a revisit (below).
var shownVenues: [String: [Venue]] = [:]

func onElementInteraction(
    flowId: String, stepId: String, blockId: String,
    action: String, value: String?, inputValues: [String: Any]
) async -> ElementInteractionResult? {
    guard action == "refresh", stepId == "step8" else { return nil }   // value == "recs_more"
    let shown = shownVenues[stepId] ?? []
    let all = shown + (await myBackend.recommendations(after: shown.count))   // your client, your auth
    shownVenues[stepId] = all
    return ElementInteractionResult(
        advance: false,
        dataContext: [
            // The WHOLE list so far — page 1 + page 2 … — under the key the Select repeats over.
            "recommendations": all.map { w in
                ["id": w.id, "name": w.name, "subtitle": w.region, "imageUrl": w.photoURL.absoluteString]
            },
        ]
    )
}