iOS API Reference

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])
    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    // Default: 30
    let batchSize: Int                 // Default: 20
    let configTTL: TimeInterval        // Default: 3600 (1 hour)
    let logLevel: LogLevel             // Default: .warning
    let billingProvider: BillingProvider // Default: .storeKit2
    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 (seconds a host veto may take)
}

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

struct StepConfigOverride {
    var fieldDefaults: [String: Any]?
    var title: String?
    var subtitle: String?
    var ctaText: String?
    var layoutOverrides: [String: Any]?
}

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
}