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 inputValues, keyed by field_id
    public var inputValuePatches: [String: Any]?
    // When true, advance to the next step after handling the interaction
    public var advance: Bool
}

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

class OnboardingHandler: AppDNAOnboardingDelegate {
    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; show inline confirmation via your own UI binding
            return .block(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:
            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
    }
}

if let location = AppDNA.getLocationData(fieldId: "user_location") {
    print("City: \(location.city)")           // "New York"
    print("Country: \(location.country_code)") // "US"
    print("Timezone: \(location.timezone)")    // "America/New_York"
    print("Coords: \(location.latitude), \(location.longitude)")
}

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

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

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

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

  const replyText = await myLLM.complete(userMessage);

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

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

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

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

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

func onBeforeStepAdvance(
    flowId: String,
    fromStepId: String,
    stepIndex: Int,
    stepType: String,
    responses: [String: Any],
    stepData: [String: Any]?
) async -> StepAdvanceResult {
    // 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
}

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
}

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

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

import AppDNASDK

class OnboardingCoordinator: AppDNAOnboardingDelegate {
    private let rootViewController: UIViewController

    init(rootViewController: UIViewController) {
        self.rootViewController = rootViewController
        AppDNA.onboarding.setDelegate(self)
    }

    func showOnboardingIfNeeded() {
        // Pass nil to show the active flow from remote config
        let presented = AppDNA.presentOnboarding(
            flowId: nil,
            from: rootViewController,
            delegate: self
        )

        if !presented {
            // No active flow or config not loaded yet
            navigateToMainApp()
        }
    }

    // MARK: - AppDNAOnboardingDelegate

    func onOnboardingStarted(flowId: String) {
        print("Starting flow: \(flowId)")
    }

    func onOnboardingStepChanged(
        flowId: String,
        stepId: String,
        stepIndex: Int,
        totalSteps: Int
    ) {
        // Track progress
    }

    func onOnboardingCompleted(flowId: String, responses: [String: Any]) {
        // Personalize based on responses
        if let goal = responses["fitness_goal"] as? String {
            AppDNA.identify(userId: currentUserId, traits: ["fitness_goal": goal])
        }
        navigateToMainApp()
    }

    func onOnboardingDismissed(flowId: String, atStep: Int) {
        navigateToMainApp()
    }
}

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

class MyDelegate: AppDNAPaywallDelegate {
    func onPaywallRestoreCompleted(paywallId: String, productIds: [String]) {
        // Your custom UI handling — show overlay, etc.
        // No need to call 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), set the flag synchronously inside this method.
    }
}