feat: Add form lifecycle event hooks

[ajaysubra]

Summary

Adds lifecycle event callbacks for in-app forms to enable tracking form interactions in third-party analytics platforms.

New Public API

// Register handler
KlaviyoSDK().registerFormLifecycleHandler { event, context in
    switch event {
    case .formShown:
        Analytics.track("Form Shown", properties: ["formId": context.formId ?? ""])
    case .formDismissed:
        Analytics.track("Form Dismissed", properties: ["formId": context.formId ?? ""])
    case .formCTAClicked:
        Analytics.track("Form CTA Clicked", properties: ["formId": context.formId ?? ""])
    }
}

// Unregister handler
KlaviyoSDK().unregisterFormLifecycleHandler()

Events

• formShown — Fires immediately before the form view controller is presented
• formDismissed — Fires when form is dismissed (user action, timeout, or programmatic)
• formCTAClicked — Fires when user taps a CTA button (always fires, even if no deep link is configured)

FormContext

Each event is accompanied by a FormContext struct carrying metadata about the form. Currently exposes formId; new fields (e.g. step, form type, dismissal reason) can be added without changing the callback signature.

public struct FormContext: Sendable {
    public let formId: String?
}

Implementation Details

• ✅ Handler invoked on main thread via @MainActor
• ✅ formId decoded from the formWillAppear JS bridge message and threaded through to the callback
• ✅ formCTAClicked always fires even when no deep link URL is configured
• ✅ Duplicate formDismissed events are suppressed via hasInvokedDismissed flag (covers timeout, programmatic, and user-initiated paths)
• ✅ Optional feature — forms work without a registered handler
• ✅ Follows existing registerDeepLinkHandler() pattern for consistency

New Files

• Sources/KlaviyoForms/InAppForms/Models/FormLifecycleEvent.swift — public event enum
• Sources/KlaviyoForms/InAppForms/Models/FormContext.swift — public context struct
• Tests/KlaviyoFormsTests/FormLifecycleHandlerTests.swift — test suite

Modified Files

• Sources/KlaviyoForms/KlaviyoSDK+Forms.swift — public registerFormLifecycleHandler(_:) / unregisterFormLifecycleHandler()
• Sources/KlaviyoForms/InAppForms/IAFPresentationManager.swift — handler storage, currentFormContext, invocation
• Sources/KlaviyoForms/InAppForms/IAFWebViewModel.swift — yields formId through lifecycle stream
• Sources/KlaviyoForms/InAppForms/Models/IAFNativeBridgeEvent.swift — FormWillAppearPayload decodes formId; IAFLifecycleEvent.present carries formId
• Examples/KlaviyoSwiftExamples/Shared/AppDelegate.swift — updated example

Test Plan

• All new tests pass
• All existing tests pass

Breaking Changes

None — purely additive.

---

🤖 Generated with Claude Code

[ab1470]

// STEP2C

does this correspond to something, like a reference in the readme? If not, can you remove it?

[ajaysubra]

It's a step by step order of integration in the example app that was existing and this just built on that. I think it's useful when someone is looking to integrate.

[belleklaviyo]

looks good, and thanks for adding good tests for this

[ajaysubra]

@belleklaviyo @ab1470 made a minor change and included an object in the closure to send the form id. Made this an object so that in a future where we may want to add more properties its easy to do.

[ajaysubra]

looks good, and thanks for adding good tests for this

All praise to the frenchman!

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

[cursor]

Form context overwritten before verifying successful presentation

Low Severity

currentFormContext is unconditionally set in handleFormEvent(.present(formId)) before presentForm() runs. If the presentation is rejected (e.g., another Klaviyo form is already showing), the context for the currently-displayed form gets overwritten. Subsequent formCTAClicked or formDismissed callbacks would then carry the wrong formId. Moving the context assignment into presentForm() right before the actual present() call would prevent this.