Android Onboarding

import ai.appdna.sdk.AppDNA

val presented = AppDNA.presentOnboarding(
    activity = this,
    flowId = "main_flow",
    listener = onboardingDelegate
)

if (!presented) {
    Log.w("Onboarding", "Flow config not available — check Console or network")
}

val onboarding = AppDNA.onboarding

import ai.appdna.sdk.onboarding.OnboardingContext

val context = OnboardingContext(
    source = "app_launch",
    campaign = "winter_2025",
    referrer = "social_ad",
    userProperties = mapOf("locale" to "en_US"),
    experimentOverrides = mapOf("onboarding_variant" to "b")
)

AppDNA.onboarding.present(
    activity = this,
    flowId = "main_flow",
    context = context
)

interface AppDNAOnboardingDelegate {
    fun onOnboardingStarted(flowId: String)
    fun onOnboardingStepChanged(flowId: String, stepId: String, stepIndex: Int, totalSteps: Int)
    fun onOnboardingCompleted(flowId: String, responses: Map<String, Any>)
    fun onOnboardingDismissed(flowId: String, atStep: Int)

    // Async hooks (optional — default implementations provided)
    suspend fun onBeforeStepAdvance(
        flowId: String, fromStepId: String, stepIndex: Int,
        stepType: String, responses: Map<String, Any>, stepData: Map<String, Any>?
    ): StepAdvanceResult = StepAdvanceResult.Proceed

    suspend fun onBeforeStepRender(
        flowId: String, stepId: String, stepIndex: Int,
        stepType: String, responses: Map<String, Any>
    ): StepConfigOverride? = null

    // Backend-interactive elements (1.0.39+) — fires DURING render when an interactive element acts
    suspend fun onElementInteraction(
        flowId: String, stepId: String, blockId: String,
        action: String, value: String?, inputValues: Map<String, Any>
    ): ElementInteractionResult? = null
}

class OnboardingHandler : AppDNAOnboardingDelegate {
    override fun onOnboardingStarted(flowId: String) {
        Log.d("Onboarding", "Started: $flowId")
    }

    override fun onOnboardingStepChanged(
        flowId: String,
        stepId: String,
        stepIndex: Int,
        totalSteps: Int
    ) {
        Log.d("Onboarding", "Step ${stepIndex + 1}/$totalSteps: $stepId")
        // Update progress indicator
    }

    override fun onOnboardingCompleted(flowId: String, responses: Map<String, Any>) {
        Log.d("Onboarding", "Completed: $flowId")
        Log.d("Onboarding", "Responses: $responses")
        // Navigate to main app screen
    }

    override fun onOnboardingDismissed(flowId: String, atStep: Int) {
        Log.d("Onboarding", "Dismissed at step $atStep")
        // Handle early exit — maybe show again later
    }
}

suspend fun 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: Map<String, Any>,   // live snapshot of the step's collected values
): ElementInteractionResult? = null

data class ElementInteractionResult(
    // Per-block field_config patches to merge + re-render, keyed blockId → (key → value)
    val fieldConfigPatches: Map<String, Map<String, Any>>? = null,
    // Patches merged into the step's inputValues, keyed by field_id
    val inputValuePatches: Map<String, Any>? = null,
    // When true, advance to the next step after handling the interaction
    val advance: Boolean = false,
)

override suspend fun onElementInteraction(
    flowId: String,
    stepId: String,
    blockId: String,
    action: String,
    value: String?,
    inputValues: Map<String, Any>,
): ElementInteractionResult? {
    return when (action) {
        "health_connect" -> {
            val granted = healthClient.requestAuthorization()
            if (!granted) null   // leave the card unchanged
            else ElementInteractionResult(
                fieldConfigPatches = mapOf(blockId to mapOf("connected" to true)),
                inputValuePatches = mapOf("health_connected" to true),
            )
        }
        else -> null
    }
}

// Observe the outcome
fun onPermissionResult(flowId: String, stepId: String, permissionType: String, granted: Boolean)

// Optionally handle the request yourself instead of the SDK prompting
suspend fun onPermissionRequest(permissionType: String): PermissionHandling?
// return PermissionHandling.HandledByHost(granted) to take over, or Proceed / null to let the SDK prompt

class OnboardingHandler(
    private val activity: FragmentActivity,
    private val authClient: AuthClient,
    private val otpClient: OtpClient,
) : AppDNAOnboardingDelegate {

    override suspend fun onBeforeStepAdvance(
        flowId: String,
        fromStepId: String,
        stepIndex: Int,
        stepType: String,
        responses: Map<String, Any>,
        stepData: Map<String, Any>?,
    ): StepAdvanceResult {
        val action = stepData?.get("action") as? String ?: return StepAdvanceResult.Proceed

        return when (action) {
            "login" -> {
                val email = stepData["email"] as? String ?: ""
                val password = stepData["password"] as? String ?: ""
                try {
                    val user = authClient.signIn(email, password)
                    StepAdvanceResult.ProceedWithData(mapOf("user_id" to user.id))
                } catch (e: Exception) {
                    StepAdvanceResult.Block("Invalid email or password.")
                }
            }

            "register" -> {
                val email = stepData["email"] as? String ?: ""
                val password = stepData["password"] as? String ?: ""
                try {
                    val user = authClient.register(email, password)
                    StepAdvanceResult.ProceedWithData(mapOf("user_id" to user.id))
                } catch (e: Exception) {
                    StepAdvanceResult.Block("Couldn't create account — try a different email.")
                }
            }

            "reset_password" -> {
                val email = stepData["email"] as? String ?: ""
                runCatching { authClient.requestPasswordReset(email) }
                // Stay on step; the user is told the email was sent.
                StepAdvanceResult.Stay("If an account exists for $email, we've emailed a reset link.")
            }

            "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.
                val channel = stepData["channel"] as? String
                    ?: return StepAdvanceResult.Block(
                        "Couldn't determine OTP delivery channel — please contact support."
                    )
                val recipient = stepData["recipient"] as? String
                    ?: return StepAdvanceResult.Block("Missing recipient.")
                try {
                    otpClient.send(channel, recipient)
                    StepAdvanceResult.Proceed
                } catch (e: Exception) {
                    StepAdvanceResult.Block("Couldn't send code — please retry.")
                }
            }

            "verify_otp" -> {
                val code = stepData["otp_code"] as? String
                val recipient = stepData["recipient"] as? String
                if (code == null || recipient == null) {
                    return StepAdvanceResult.Block("Missing code or recipient.")
                }
                try {
                    otpClient.verify(code, recipient)
                    StepAdvanceResult.Proceed
                } catch (e: Exception) {
                    StepAdvanceResult.Block("Code didn't match — try again.")
                }
            }

            "enable_biometric" -> {
                val biometricManager = androidx.biometric.BiometricManager.from(activity)
                val canAuthenticate = biometricManager.canAuthenticate(
                    androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
                )
                val success = canAuthenticate ==
                    androidx.biometric.BiometricManager.BIOMETRIC_SUCCESS &&
                    authClient.promptBiometric(activity)
                StepAdvanceResult.ProceedWithData(mapOf("biometric_enabled" to success))
            }

            else -> StepAdvanceResult.Proceed
        }
    }
}

AppDNA.registerCustomView("my_view") { config ->
    MyComposableView(config)
}

// Register before presenting the onboarding flow
AppDNA.registerCustomView("terms_acceptance") { config ->
    val termsUrl = config["terms_url"] as? String
    TermsAcceptanceView(
        termsUrl = termsUrl,
        onAccept = { accepted -> /* Handle acceptance */ },
    )
}

override suspend fun onBeforeStepRender(
    flowId: String, stepId: String, stepIndex: Int,
    stepType: String, responses: Map<String, Any>,
): StepConfigOverride? {
    return StepConfigOverride(
        fieldDefaults = mapOf(
            "email" to currentUser.email,
            "name" to currentUser.displayName,
        ),
        title = "Welcome back, ${currentUser.firstName}!",
        subtitle = "Pick up where you left off",
        ctaText = "Continue",
    )
}

override fun onOnboardingCompleted(flowId: String, responses: Map<String, Any>) {
    val formData = responses["profile_step"] as? Map<String, Any>
    val name = formData?.get("full_name") as? String
    val age = formData?.get("age") as? Int
    val email = formData?.get("email") as? String
    // Use collected data to personalize the experience
}

val location = AppDNA.getLocationData(fieldId = "user_location")
if (location != null) {
    Log.d("Loc", "City: ${location.city}")           // "New York"
    Log.d("Loc", "Country: ${location.country_code}") // "US"
    Log.d("Loc", "Timezone: ${location.timezone}")    // "America/New_York"
    Log.d("Loc", "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
  });
});

override suspend fun onBeforeStepAdvance(
    flowId: String,
    fromStepId: String,
    stepIndex: Int,
    stepType: String,
    responses: Map<String, Any>,
    stepData: Map<String, Any>?,
): StepAdvanceResult {
    // Example: validate a referral code with your backend
    if (stepType == "form") {
        val formData = responses[fromStepId] as? Map<String, Any>
        val code = formData?.get("referral_code") as? String
        if (code != null) {
            val isValid = validateReferralCode(code) // your suspend function
            if (!isValid) {
                return StepAdvanceResult.Block("Invalid referral code. Please try again.")
            }
            return StepAdvanceResult.ProceedWithData(mapOf("referral_validated" to true))
        }
    }
    return StepAdvanceResult.Proceed
}

"reset_password" -> {
    val email = (responses[fromStepId] as? Map<String, Any>)?.get("email") as? String ?: ""
    try {
        myAuthBackend.sendPasswordReset(email)
        StepAdvanceResult.Stay("Reset email sent to $email")
    } catch (e: Exception) {
        StepAdvanceResult.Block("Couldn't send reset email. Please try again.")
    }
}

override suspend fun onBeforeStepRender(
    flowId: String,
    stepId: String,
    stepIndex: Int,
    stepType: String,
    responses: Map<String, Any>,
): StepConfigOverride? {
    // Pre-fill form fields based on user data
    if (stepId == "profile_step") {
        return StepConfigOverride(
            fieldDefaults = mapOf(
                "email" to currentUser.email,
                "name" to currentUser.displayName,
            ),
            title = "Welcome back, ${currentUser.firstName}!"
        )
    }
    return null
}

// 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 ai.appdna.sdk.AppDNA
import ai.appdna.sdk.onboarding.AppDNAOnboardingDelegate
import ai.appdna.sdk.onboarding.StepAdvanceResult
import ai.appdna.sdk.onboarding.StepConfigOverride
import androidx.fragment.app.FragmentActivity

class OnboardingCoordinator(
    private val activity: FragmentActivity,
) : AppDNAOnboardingDelegate {

    init {
        AppDNA.onboarding.setDelegate(this)
    }

    fun showOnboardingIfNeeded() {
        // Pass null to show the active flow from remote config
        val presented = AppDNA.presentOnboarding(
            activity = activity,
            flowId = null,
            listener = this,
        )
        if (!presented) {
            // No active flow or config not loaded yet
            navigateToMainApp()
        }
    }

    // MARK: AppDNAOnboardingDelegate

    override fun onOnboardingStarted(flowId: String) {
        Log.d("Onboarding", "Starting flow: $flowId")
    }

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

    override fun onOnboardingCompleted(flowId: String, responses: Map<String, Any>) {
        // Personalize based on responses
        val goal = responses["fitness_goal"] as? String
        if (goal != null) {
            AppDNA.identify(userId = currentUserId, traits = mapOf("fitness_goal" to goal))
        }
        navigateToMainApp()
    }

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

    private fun navigateToMainApp() { /* ... */ }
}

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