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 CURRENT inputValues, key by key, keyed by field_id
    val inputValuePatches: Map<String, Any>? = null,
    // Replacement options for a Select, keyed by blockId (the same shape as StepConfigOverride.fieldOptions)
    val fieldOptions: Map<String, List<InputOption>>? = null,
    // When true, advance to the next step after handling the interaction
    val advance: Boolean = false,
    // New host data for this step, merged into {{hook_data.…}} per top-level key; a null value removes a key.
    // See "Show more" under Host-supplied data. Android SDK 1.0.54+.
    val dataContext: Map<String, Any?>? = null,
)

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))
            }

            // Never `Proceed` a sign-in action this `when` does not handle — nobody authenticated
            // the user. Any other action (a plain `next`, a flag CTA, …) advances as usual.
            in SIGN_IN_ACTIONS ->
                StepAdvanceResult.Block("Sign-in isn't available right now. Please try again later.")
            else -> StepAdvanceResult.Proceed
        }
    }

    private companion object {
        /** The sign-in actions (the Authentication entry and Account lifecycle tables above). */
        val SIGN_IN_ACTIONS = setOf(
            "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",
        )
    }
}

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
}

override fun onOnboardingCompleted(flowId: String, responses: Map<String, Any>) {
    val flags = responses["flags"] as? Map<String, Any> ?: emptyMap()

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

val location = AppDNA.getLocationData(fieldId = "user_location")
if (location != null) {
    Log.d("Loc", "Address: ${location.formatted_address}") // always present
    Log.d("Loc", "City: ${location.city ?: "-"}")           // "New York", or null for typed text
    Log.d("Loc", "Country: ${location.country_code ?: "-"}")
    val lat = location.latitude
    val lng = location.longitude
    if (lat != null && lng != null) Log.d("Loc", "Coords: $lat, $lng")
}

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
  });
});

class ReferralHandler : AppDNAOnboardingDelegate {
    override suspend fun onBeforeStepAdvance(
        flowId: String,
        fromStepId: String,
        stepIndex: Int,
        stepType: String,
        responses: Map<String, Any>,
        stepData: Map<String, Any>?,
    ): StepAdvanceResult {
        // This hook handles no sign-in action, so it must never advance one: nobody authenticated
        // the user.
        if ((stepData?.get("action") as? String) in SIGN_IN_ACTIONS) {
            return StepAdvanceResult.Block("Sign-in isn't available right now. Please try again later.")
        }

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

    private suspend fun validateReferralCode(code: String): Boolean {
        return code.isNotBlank() // call your backend here
    }

    private companion object {
        /** The sign-in actions (the Authentication entry and Account lifecycle tables above). */
        val SIGN_IN_ACTIONS = setOf(
            "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",
        )
    }
}

"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"

override suspend fun onBeforeStepRender(
    flowId: String, stepId: String, stepIndex: Int, stepType: String,
    responses: Map<String, Any>,
): StepConfigOverride? {
    val booking = myBackend.booking(stepId)   // your client, your auth
    return StepConfigOverride(dataContext = mapOf(
        "booking" to mapOf("unitPrice" to booking.unitPrice, "venue" to booking.venueName),
    ))
}

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

override suspend fun onBeforeStepRender(
    flowId: String, stepId: String, stepIndex: Int, stepType: String,
    responses: Map<String, Any>,
): StepConfigOverride? {
    if (stepId != "step8") return null
    val venues = myBackend.recommendations(responses)   // your client, your auth
    return StepConfigOverride(dataContext = mapOf(
        "recommendations" to venues.map { w ->
            mapOf("id" to w.id, "name" to w.name, "subtitle" to w.region, "imageUrl" to w.photoUrl)
        },
    ))
}

// Your paging state, per step. Also answer onBeforeStepRender with it on a revisit (below).
private val shownVenues = mutableMapOf<String, List<Venue>>()

override suspend fun onElementInteraction(
    flowId: String, stepId: String, blockId: String,
    action: String, value: String?, inputValues: Map<String, Any>,
): ElementInteractionResult? {
    if (action != "refresh" || stepId != "step8") return null   // value == "recs_more"
    val shown = shownVenues[stepId].orEmpty()
    val all = shown + myBackend.recommendations(after = shown.size)   // your client, your auth
    shownVenues[stepId] = all
    return ElementInteractionResult(
        advance = false,
        dataContext = mapOf(
            // The WHOLE list so far — page 1 + page 2 … — under the key the Select repeats over.
            "recommendations" to all.map { w ->
                mapOf("id" to w.id, "name" to w.name, "subtitle" to w.region, "imageUrl" to w.photoUrl)
            },
        ),
    )
}

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