iOS API Reference

public protocol AppDNALifecycleDelegate: AnyObject {
    /// Fires once on idle → locked. `reason` is `billing_overdue`, `manual_admin` or `org_cancelled`;
    /// `lockedAt` is ISO-8601.
    func onSdkRuntimeLocked(reason: String, lockedAt: String)
    /// Fires once on locked → idle.
    func onSdkRuntimeUnlocked()
    /// 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 — e.g.
    /// `steps[9].content_blocks[3]: Dictionary<String, Any> was null`.
    func onConfigurationIssue(surface: String, id: String?, detail: String)
    /// 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.
    func onEventTracked(name: String, properties: [String: Any])
}

protocol AppDNAPushDelegate {
    func onPushTokenRegistered(token: String)
    func onPushReceived(notification: PushPayload, inForeground: Bool)
    func onPushTapped(notification: PushPayload, actionId: String?)
}

protocol AppDNABillingDelegate {
    func onPurchaseCompleted(productId: String, transaction: TransactionInfo)
    func onPurchaseFailed(productId: String, error: Error)
    func onEntitlementsChanged(entitlements: [Entitlement])  // optional; fires with the
                                                             // AppDNA.billing.onEntitlementsChanged closures
    func onRestoreCompleted(restoredProducts: [String])
}

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

protocol AppDNAPaywallDelegate {
    func onPaywallPresented(paywallId: String)
    func onPaywallAction(paywallId: String, action: PaywallAction)
    func onPaywallPurchaseStarted(paywallId: String, productId: String)
    func onPaywallPurchaseCompleted(paywallId: String, productId: String, transaction: TransactionInfo)
    func onPaywallPurchaseFailed(paywallId: String, error: Error)
    func onPaywallDismissed(paywallId: String)
    func onPromoCodeSubmit(paywallId: String, code: String, completion: @escaping (Bool) -> Void)
    func onPostPurchaseDeepLink(paywallId: String, url: String)
    func onPostPurchaseNextStep(paywallId: String)
    func onPaywallRestoreStarted(paywallId: String)
    func onPaywallRestoreCompleted(paywallId: String, productIds: [String])
    func onPaywallRestoreFailed(paywallId: String, error: Error)
}

public protocol AppDNAInAppMessageDelegate: AnyObject {
    func onMessageShown(messageId: String, trigger: String)
    func onMessageAction(messageId: String, action: String, data: [String: Any]?)
    func onMessageDismissed(messageId: String)
    func shouldShowMessage(messageId: String) -> Bool
}

protocol AppDNASurveyDelegate {
    func onSurveyPresented(surveyId: String)
    func onSurveyCompleted(surveyId: String, responses: [SurveyResponse])
    func onSurveyDismissed(surveyId: String)
}

public protocol AppDNADeepLinkDelegate: AnyObject {
    func onDeepLinkReceived(url: URL, params: [String: String])
}

struct AppDNAOptions {
    let flushInterval: TimeInterval    // init(flushInterval: TimeInterval? = nil); not set: the bootstrap's value if positive, else 30
    let batchSize: Int                 // init(batchSize: Int? = nil); a cap on the network-sized batch; not set: the bootstrap's value is the cap if positive, else no cap (this property then reads 100); below 1 is ignored
    let configTTL: TimeInterval        // init(configTTL: TimeInterval? = nil); not set: the bootstrap's value if positive, else 3600
    let requestedFlushInterval: TimeInterval? // What you passed; nil when not set
    let requestedBatchSize: Int?       // What you passed; nil when not set
    let requestedConfigTTL: TimeInterval?     // What you passed; nil when not set
    let logLevel: LogLevel             // Default: .warning
    let billingProvider: BillingProvider // Default: .storeKit2 (AppDNA's own billing)
    let framework: String              // Default: "native" (wrapper attribution)
    let frameworkVersion: String?      // Default: nil (wrapper's own version)
    let requireConsent: Bool           // Default: false (analytics opt-out)
    let vetoTimeout: TimeInterval      // Default: 5 — bounds every host hook on the Flutter / RN bridges;
                                       // sign-in actions wait at least 120 s and a `refresh` interaction
                                       // max(vetoTimeout, 8 s). In a native iOS host it is unused:
                                       // onBeforeStepAdvance is not timed out, onBeforeStepRender ends at 3 s and
                                       // a `refresh` interaction at 8 s
}

enum Environment {
    case production
    case sandbox
}

enum LogLevel {
    case none
    case error
    case warning
    case info
    case debug
}

enum BillingProvider {
    case storeKit2
    case revenueCat
    case adapty(apiKey: String)
    case none
}

struct PaywallContext {
    let placement: String
    let experiment: String?
    let variant: String?
    let customData: [String: Any]?   // Merged into the `paywall_view` event's properties
}

struct OnboardingContext {
    var source: String?
    var campaign: String?
    var referrer: String?
    var userProperties: [String: Any]?
    var experimentOverrides: [String: String]?
}

struct PushPayload {
    let pushId: String
    let title: String
    let body: String
    let imageUrl: String?
    let data: [String: Any]?
    let action: PushAction?       // The notification-body tap-through action
    let actions: [PushAction]     // The registered action BUTTONS (defaults to [])
}

struct PushAction {
    let type: String
    let value: String
    let id: String?      // Button identifier — matches `actionId` in onPushTapped. Nil for the body action.
    let label: String?   // Button label as displayed. Nil for the body action.
}

struct TransactionInfo {
    var transactionId: String
    var productId: String
    var purchaseDate: Date
    var environment: String
}

struct ProductInfo {
    var id: String
    var displayName: String
    var description: String
    var price: Decimal
    var displayPrice: String
    var subscription: SubscriptionInfo?
}

struct Entitlement {
    var identifier: String
    var isActive: Bool
    var expiresAt: Date?
    var productId: String
}

struct WebEntitlement {
    let isActive: Bool
    let planName: String?
    let priceId: String?
    let interval: String?            // "month", "year"
    let status: EntitlementStatus
    let currentPeriodEnd: Date?
    let trialEnd: Date?
}

struct DeferredDeepLink {
    var screen: String
    var params: [String: String]
    var visitorId: String
}

enum PaywallAction {
    case ctaTapped
    case featureSelected
    case planChanged
    case linkTapped
    case custom
}

enum DismissReason {
    case purchased
    case dismissed
    case tappedOutside
    case programmatic
}

enum StepAdvanceResult {
    case proceed
    case proceedWithData([String: Any])
    case block(message: String)
    case skipTo(stepId: String)
    case skipToWithData(stepId: String, data: [String: Any])
    case stay(message: String? = nil)
}

extension StepAdvanceResult {
    /// 120 s for a sign-in action (`stepData["action"]` is one of the sign-in actions), else `nil`.
    public static func minimumBridgeTimeout(stepData: [String: Any]?) -> TimeInterval?
}

struct StepConfigOverride {
    var fieldDefaults: [String: Any]?
    var title: String?
    var subtitle: String?
    var ctaText: String?
    var fieldOptions: [String: [InputOption]]?  // host-supplied Select options, by block id
    var dataContext: [String: Any]?             // host data for this step, read as {{hook_data.…}}
    var mapRoutes: [String: MapRouteOverride]?  // host-supplied map routes, by block id
}

enum FormFieldType: String, Codable {
    case text, textarea, number, email, phone
    case password
    case url
    case date, time, datetime
    case select, slider, toggle, stepper, segmented
    case location
    case rating
    case range_slider
    case image_picker
    case color
    case multiline_chips
    case signature
}

protocol AppDNAScreenDelegate {
    func onScreenPresented(screenId: String)
    func onScreenDismissed(screenId: String, result: ScreenResult)
    func onFlowCompleted(flowId: String, result: FlowResult)
    func onScreenAction(screenId: String, action: SectionAction) -> Bool
}

enum ScreenError: String, Codable {
    case configFetchFailed
    case configFetchTimeout
    case screenNotFound
    case configParseError
    case configInvalid
    case nestingDepthExceeded
}

struct ScreenResult {
    let screenId: String
    let dismissed: Bool
    let responses: [String: Any]
    let lastAction: String?
    let duration_ms: Int
    let error: ScreenError?
}

struct FlowResult {
    let flowId: String
    let completed: Bool
    let lastScreenId: String
    let responses: [String: Any]
    let screensViewed: [String]
    let duration_ms: Int
    let error: ScreenError?
}

enum SectionAction {
    case next
    case back
    case dismiss
    case navigate(screenId: String)
    case openURL(url: String)
    case openWebview(url: String)
    case openAppSettings
    case share(text: String)
    case deepLink(url: String)
    case showPaywall(id: String?)
    case showSurvey(id: String?)
    case showScreen(id: String)
    case submitForm(data: [String: Any])
    case track(event: String, properties: [String: Any]?)
    case haptic(type: String)
    case custom(type: String, value: String?)

    // Flow-level verbs (routed by FlowManager; ignored on the single-screen path)
    case restart
    case complete
    case setResponse(key: String, value: Any?)
    case presentPaywall(id: String?)
    case dismissPaywall
    case showMessage(id: String?)
    case setUserProperty(key: String, value: Any?)
    case purchase(productId: String)
    case restore
}