Android API Reference

interface AppDNALifecycleDelegate {
    /** Fires once on idle → locked. `reason` is billing_overdue, manual_admin or org_cancelled; `lockedAt` is ISO-8601. */
    fun onSdkRuntimeLocked(reason: String, lockedAt: String) = Unit
    /** Fires once on locked → idle. */
    fun onSdkRuntimeUnlocked() = Unit
    /**
     * Part of a published config could not be decoded and was DROPPED; the rest still renders.
     * `surface` is the kind ("onboarding_flow", "paywall", …), `id` the document when one is
     * known, and `detail` the CODING PATH and reason.
     */
    fun onConfigurationIssue(surface: String, id: String?, detail: String) = Unit
    /**
     * Fires for EVERY event the SDK tracks, with the properties sent with it, right after the
     * event is queued. Use it to forward AppDNA analytics into your own pipeline.
     */
    fun onEventTracked(name: String, properties: Map<String, Any?>) = Unit
}

interface AppDNAPushDelegate {
    fun onPushTokenRegistered(token: String)
    fun onPushReceived(notification: PushPayload, inForeground: Boolean)
    fun onPushTapped(notification: PushPayload, actionId: String?)
}

interface AppDNABillingDelegate {
    fun onPurchaseCompleted(productId: String, transaction: TransactionInfo) {}
    fun onPurchaseFailed(productId: String, error: Throwable) {}
    fun onEntitlementsChanged(entitlements: List<Entitlement>) {}
    fun onRestoreCompleted(restoredProducts: List<String>) {}
    fun onBillingUnavailable() {}
}

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)
    suspend fun onBeforeStepAdvance(flowId: String, fromStepId: String, stepIndex: Int, stepType: String, responses: Map<String, Any>, stepData: Map<String, Any>?): StepAdvanceResult
    suspend fun onBeforeStepRender(flowId: String, stepId: String, stepIndex: Int, stepType: String, responses: Map<String, Any>): StepConfigOverride?
}

interface AppDNAPaywallDelegate {
    fun onPaywallPresented(paywallId: String)
    fun onPaywallAction(paywallId: String, action: PaywallAction)
    fun onPaywallPurchaseStarted(paywallId: String, productId: String)
    fun onPaywallPurchaseCompleted(paywallId: String, productId: String, transaction: TransactionInfo)
    fun onPaywallPurchaseFailed(paywallId: String, error: Throwable)
    fun onPaywallDismissed(paywallId: String)
    fun onPromoCodeSubmit(paywallId: String, code: String, completion: (Boolean) -> Unit)
    fun onPostPurchaseDeepLink(paywallId: String, url: String)
    fun onPostPurchaseNextStep(paywallId: String)
    fun onPaywallRestoreStarted(paywallId: String)
    fun onPaywallRestoreCompleted(paywallId: String, productIds: List<String>)
    fun onPaywallRestoreFailed(paywallId: String, error: Throwable)
}

interface AppDNAInAppMessageDelegate {
    fun onMessageShown(messageId: String, trigger: String)
    fun onMessageAction(messageId: String, action: String, data: Map<String, Any>?)
    fun onMessageDismissed(messageId: String)
    fun shouldShowMessage(messageId: String): Boolean
}

interface AppDNASurveyDelegate {
    fun onSurveyPresented(surveyId: String)
    fun onSurveyCompleted(surveyId: String, responses: List<SurveyResponse>)
    fun onSurveyDismissed(surveyId: String)
}

interface AppDNADeepLinkDelegate {
    fun onDeepLinkReceived(url: String, params: Map<String, String>)
}

data class AppDNAOptions(
    val flushInterval: Long = 30L,   // Left at 30 (not set): the bootstrap's value if positive, else 30
    val batchSize: Int = 100,        // A cap on the network-sized batch; left at 100 (not set): the bootstrap's value if positive, else no cap; below 1 is ignored
    val configTTL: Long = 3600L,     // Left at 3600 (not set): the bootstrap's value if positive, else 3600
    val logLevel: LogLevel = LogLevel.WARNING,
    val notificationIcon: Int = 0,
    val framework: String = "native",
    val frameworkVersion: String? = null,
    val billingProvider: BillingProvider = BillingProvider.StoreKit2,
    val requireConsent: Boolean = false,
    val vetoTimeout: Long = 5L,
)

enum class Environment(val baseUrl: String) {
    PRODUCTION("https://api.appdna.ai"),
    SANDBOX("https://api.appdna.ai") // same URL — sandbox routed via `adn_test_` key prefix
}

enum class LogLevel(val level: Int) {
    NONE(0),
    ERROR(1),
    WARNING(2),
    INFO(3),
    DEBUG(4)
}

data class PaywallContext(
    val placement: String,
    val experiment: String? = null,
    val variant: String? = null,
    val customData: Map<String, Any>? = null // Merged into the `paywall_view` event's properties
)

data class OnboardingContext(
    val source: String? = null,
    val campaign: String? = null,
    val referrer: String? = null,
    val userProperties: Map<String, Any>? = null,
    val experimentOverrides: Map<String, String>? = null
)

data class PushPayload(
    val pushId: String,
    val title: String,
    val body: String,
    val imageUrl: String? = null,
    val data: Map<String, Any>? = null,
    val action: PushAction? = null,          // The notification's single primary action
    val actions: List<PushActionButton> = emptyList() // Every registered action button, in tray order
)

data class PushAction(
    val type: String,
    val value: String
)

data class PushActionButton(
    val id: String,
    val label: String,
    val type: String,
    val value: String? = null,
    val icon: String? = null
)

data class TransactionInfo(
    val transactionId: String,
    val productId: String,
    val purchaseDate: String,   // epoch milliseconds as a decimal string, e.g. "1721044800000"
    val environment: String
)

data class Entitlement(
    val productId: String,
    val store: String,
    val status: String,
    val expiresAt: String?,
    val isTrial: Boolean,
    val offerType: String?
)

data class ProductInfo(
    val id: String,
    val name: String,
    val description: String,
    val formattedPrice: String,
    val priceMicros: Long,
    val currencyCode: String,
    val offerToken: String?
)

sealed class PurchaseResult {
    data class Purchased(val entitlement: Entitlement) : PurchaseResult()
    object Cancelled : PurchaseResult()
    object Pending : PurchaseResult()
    object Unknown : PurchaseResult()
    data class Failed(val error: String) : PurchaseResult()
}

enum class PaywallAction(val value: String) {
    CTA_TAPPED("cta_tapped"),
    FEATURE_SELECTED("feature_selected"),
    PLAN_CHANGED("plan_changed"),
    LINK_TAPPED("link_tapped"),
    CUSTOM("custom")
}

enum class DismissReason(val value: String) {
    PURCHASED("purchased"),
    DISMISSED("dismissed"),
    TAPPED_OUTSIDE("tappedOutside"),
    PROGRAMMATIC("programmatic"),
    RESTORE_SUCCESS("restore_success")
}

data class WebEntitlement(
    val isActive: Boolean,
    val planName: String?,
    val priceId: String?,
    val interval: String?,
    val status: String,
    val currentPeriodEnd: Long?, // Unix seconds
    val trialEnd: Long?,         // Unix seconds
)

data class DeferredDeepLink(
    val screen: String,
    val params: Map<String, String>,
    val visitorId: String,
)

sealed class StepAdvanceResult {
    object Proceed : StepAdvanceResult()
    data class ProceedWithData(val data: Map<String, Any>) : StepAdvanceResult()
    data class Block(val message: String) : StepAdvanceResult()
    data class Stay(val message: String? = null) : StepAdvanceResult()
    data class SkipTo(val stepId: String, val data: Map<String, Any>? = null) : StepAdvanceResult()

    companion object {
        const val AUTH_BRIDGE_TIMEOUT_MS: Long = 120_000L
        @JvmStatic fun minimumBridgeTimeoutMs(stepData: Map<String, Any?>?): Long?
    }
}

data class StepConfigOverride(
    val fieldDefaults: Map<String, Any>? = null,
    val title: String? = null,
    val subtitle: String? = null,
    val ctaText: String? = null,
    val fieldOptions: Map<String, List<InputOption>>? = null,  // host-supplied Select options, by block id
    val dataContext: Map<String, Any>? = null,                 // host data for this step, read as {{hook_data.…}}
    val mapRoutes: Map<String, MapRouteOverride>? = null       // host-supplied map routes, by block id
)

enum class FormFieldType(val value: String) {
    TEXT("text"), TEXTAREA("textarea"), NUMBER("number"),
    EMAIL("email"), PHONE("phone"),
    PASSWORD("password"),
    URL("url"),
    DATE("date"), TIME("time"), DATETIME("datetime"),
    SELECT("select"), SLIDER("slider"), TOGGLE("toggle"),
    STEPPER("stepper"), SEGMENTED("segmented"),
    LOCATION("location"),
    RATING("rating"),
    RANGE_SLIDER("range_slider"),
    IMAGE_PICKER("image_picker"),
    COLOR("color"),
    MULTILINE_CHIPS("multiline_chips"),
    SIGNATURE("signature")
}

data class LocationData(
    val formatted_address: String = "",
    val city: String? = null,
    val state: String? = null,
    val state_code: String? = null,
    val country: String? = null,
    val country_code: String? = null,
    val latitude: Double? = null,
    val longitude: Double? = null,
    val timezone: String? = null,
    val timezone_offset: Int? = null,
    val postal_code: String? = null,
    val raw_query: String? = null,
    val mapbox_id: String? = null,
    val place_id: String? = null
)

interface AppDNAScreenDelegate {
    fun onScreenPresented(screenId: String) {}
    fun onScreenDismissed(screenId: String, result: Map<String, Any?>) {}
    fun onFlowCompleted(flowId: String, result: Map<String, Any?>) {}
    fun onScreenAction(screenId: String, action: Map<String, Any?>): Boolean = true
}

enum class ScreenError {
    CONFIG_FETCH_FAILED,
    CONFIG_FETCH_TIMEOUT,
    SCREEN_NOT_FOUND,
    CONFIG_PARSE_ERROR,
    CONFIG_INVALID,
    NESTING_DEPTH_EXCEEDED
}

data class ScreenResult(
    val screenId: String,
    val dismissed: Boolean = false,
    val responses: Map<String, Any> = emptyMap(),
    val lastAction: String? = null,
    val durationMs: Int = 0,
    val error: ScreenError? = null,
)

data class FlowResult(
    val flowId: String,
    val completed: Boolean = false,
    val lastScreenId: String = "",
    val responses: Map<String, Any> = emptyMap(),
    val screensViewed: List<String> = emptyList(),
    val durationMs: Int = 0,
    val error: ScreenError? = null,
)