feat: Add form lifecycle event bridge for in-app forms (#334) (#338)

* feat: Add form lifecycle event bridge for in-app forms (#334)

* fix: batch dependabot security updates for transitive deps (#335)

fix: batch security updates for transitive dependencies

Consolidates 6 dependabot security PRs into a single lockfile update:
- handlebars 4.7.8→4.7.9 (8 security advisories)
- picomatch 2.3.1→2.3.2 (CVE-2026-33671, CVE-2026-33672)
- fast-xml-parser 4.5.3→4.5.5 (prototype pollution, entity expansion)
- flatted 3.3.3→3.4.2 (CWE-1321)
- tar 7.5.7→7.5.11 (symlink escape via drive-relative paths)
- basic-ftp 5.1.0→5.2.0 (skip invalid filenames)

All are transitive dependencies (lockfile-only, no source changes).

Closes #331, closes #330, closes #328, closes #325, closes #322, closes #316

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add form lifecycle event bridge for in-app forms

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: configure native SDK deps for form lifecycle hooks testing

Android SDK: 0a48d79980dc3f276422cf9c42ff145eb39f364a
iOS SDK branch: feat/form-lifecycle-hooks

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: unregister native lifecycle handler during re-registration

When registerFormLifecycleHandler is called again without explicit
cleanup, the re-registration path now tears down the native handler
before re-registering, matching the cleanup function's behavior.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: clear native mock between lifecycle tests to match re-registration behavior

The unregister test was failing because prior tests left the native
unregisterFormLifecycleHandler mock dirty — the re-registration path
now calls native unregister, so the mock accumulates calls across tests.
Also added assertion that re-registration calls native unregister.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(forms): validate required bridge message fields (MAGE-484) (#340)

* fix(forms): throw on missing required fields in bridge message parsing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: correct JSDoc and add integration tests for lifecycle event parsing

Fix JSDoc that said "logs a warning" when the code actually uses console.error.
Add integration tests to index.test.tsx verifying that parseFormLifecycleEvent
is correctly wired into the native event listener (invalid events filtered,
valid events forwarded, deepLinkUrl defaults).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(forms): validate deepLinkUrl as required on CTA events, normalize log level to warn

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(forms): allow empty buttonLabel on CTA events

A CTA button with no text label is still a valid click event. Only
formId and formName require non-empty strings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(forms): remove internal implementation details from public API docs

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

* fix(forms): default buttonLabel to empty string instead of rejecting

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: evan-masseau

android/gradle.properties

@@ -17,7 +17,8 @@ android.useAndroidX=true
 # http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
 # org.gradle.parallel=true
 #Tue Dec 19 15:08:27 EST 2023
-KlaviyoReactNativeSdk_klaviyoAndroidSdkVersion=4.3.1
+# saved: 4.3.1
+KlaviyoReactNativeSdk_klaviyoAndroidSdkVersion=rel~4.4.0-SNAPSHOT
 KlaviyoReactNativeSdk_kotlinVersion=1.8.0
 KlaviyoReactNativeSdk_minSdkVersion=23
 KlaviyoReactNativeSdk_targetSdkVersion=36

android/src/main/java/com/klaviyoreactnativesdk/KlaviyoReactNativeSdkModule.kt

@@ -8,6 +8,8 @@ import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.ReadableType
 import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.klaviyo.analytics.Klaviyo
 import com.klaviyo.analytics.model.Event
 import com.klaviyo.analytics.model.EventKey
@@ -19,9 +21,12 @@ import com.klaviyo.core.MissingKlaviyoModule
 import com.klaviyo.core.Registry
 import com.klaviyo.core.config.Config
 import com.klaviyo.core.utils.AdvancedAPI
+import com.klaviyo.forms.FormLifecycleEvent
 import com.klaviyo.forms.FormsProvider
 import com.klaviyo.forms.InAppFormsConfig
 import com.klaviyo.forms.registerForInAppForms
+import com.klaviyo.forms.registerFormLifecycleHandler
+import com.klaviyo.forms.unregisterFormLifecycleHandler
 import com.klaviyo.forms.unregisterFromInAppForms
 import com.klaviyo.location.GeofencingProvider
 import com.klaviyo.location.LocationManager
@@ -40,6 +45,15 @@ class KlaviyoReactNativeSdkModule(
     private const val PROPERTIES = "properties"
   }
 
+  private fun sendEvent(
+    eventName: String,
+    params: WritableMap?,
+  ) {
+    reactContext
+      .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+      .emit(eventName, params)
+  }
+
   override fun getName(): String = NAME
 
   override fun getConstants(): MutableMap<String, Any> =
@@ -288,4 +302,56 @@ class KlaviyoReactNativeSdkModule(
 
     Klaviyo.createEvent(event = klaviyoEvent)
   }
+
+  @ReactMethod
+  fun registerFormLifecycleHandler() {
+    UiThreadUtil.runOnUiThread {
+      try {
+        Klaviyo.registerFormLifecycleHandler { event ->
+          val params =
+            Arguments.createMap().apply {
+              putString("formId", event.formId)
+              putString("formName", event.formName)
+              when (event) {
+                is FormLifecycleEvent.FormShown -> {
+                  putString("type", "formShown")
+                }
+
+                is FormLifecycleEvent.FormDismissed -> {
+                  putString("type", "formDismissed")
+                }
+
+                is FormLifecycleEvent.FormCtaClicked -> {
+                  putString("type", "formCtaClicked")
+                  putString("buttonLabel", event.buttonLabel)
+                  putString("deepLinkUrl", event.deepLinkUrl.toString())
+                }
+              }
+            }
+
+          sendEvent("FormLifecycleEvent", params)
+        }
+      } catch (e: MissingKlaviyoModule) {
+        Registry.log.error("Forms module is not available", e)
+      }
+    }
+  }
+
+  @ReactMethod
+  fun unregisterFormLifecycleHandler() {
+    UiThreadUtil.runOnUiThread {
+      try {
+        Klaviyo.unregisterFormLifecycleHandler()
+      } catch (e: MissingKlaviyoModule) {
+        Registry.log.error("Forms module is not available", e)
+      }
+    }
+  }
+
+  // Required by NativeEventEmitter on the JS side
+  @ReactMethod
+  fun addListener(eventName: String) {}
+
+  @ReactMethod
+  fun removeListeners(count: Int) {}
 }

example/ios/Podfile

@@ -28,6 +28,10 @@ target 'KlaviyoReactNativeSdkExample' do
   use_frameworks! :linkage => :static
 
   # Insert override klaviyo-swift-sdk pods below this line when needed
+  pod 'KlaviyoCore', :git => 'https://github.com/klaviyo/klaviyo-swift-sdk.git', :branch => 'rel/5.3.0'
+  pod 'KlaviyoSwift', :git => 'https://github.com/klaviyo/klaviyo-swift-sdk.git', :branch => 'rel/5.3.0'
+  pod 'KlaviyoForms', :git => 'https://github.com/klaviyo/klaviyo-swift-sdk.git', :branch => 'rel/5.3.0'
+  pod 'KlaviyoLocation', :git => 'https://github.com/klaviyo/klaviyo-swift-sdk.git', :branch => 'rel/5.3.0'
 
   # Setup permissions for react-native-permissions
   setup_permissions([

example/ios/Podfile.lock

@@ -10,19 +10,19 @@ PODS:
     - hermes-engine/Pre-built (= 0.81.5)
   - hermes-engine/Pre-built (0.81.5)
   - klaviyo-react-native-sdk (2.3.1):
-    - KlaviyoForms (= 5.2.2)
-    - KlaviyoLocation (= 5.2.2)
-    - KlaviyoSwift (= 5.2.2)
+    - KlaviyoForms
+    - KlaviyoLocation
+    - KlaviyoSwift
     - React-Core
-  - KlaviyoCore (5.2.2):
+  - KlaviyoCore (5.3.0):
     - AnyCodable-FlightSchool
-  - KlaviyoForms (5.2.2):
-    - KlaviyoSwift (~> 5.2.2)
-  - KlaviyoLocation (5.2.2):
-    - KlaviyoSwift (~> 5.2.2)
-  - KlaviyoSwift (5.2.2):
+  - KlaviyoForms (5.3.0):
+    - KlaviyoSwift (~> 5.3.0)
+  - KlaviyoLocation (5.3.0):
+    - KlaviyoSwift (~> 5.3.0)
+  - KlaviyoSwift (5.3.0):
     - AnyCodable-FlightSchool
-    - KlaviyoCore (~> 5.2.2)
+    - KlaviyoCore (~> 5.3.0)
   - KlaviyoSwiftExtension (5.2.1)
   - RCT-Folly (2024.11.18.00):
     - boost
@@ -2396,6 +2396,10 @@ DEPENDENCIES:
   - glog (from `../node_modules/react-native/third-party-podspecs/glog.podspec`)
   - hermes-engine (from `../node_modules/react-native/sdks/hermes-engine/hermes-engine.podspec`)
   - klaviyo-react-native-sdk (from `../..`)
+  - KlaviyoCore (from `https://github.com/klaviyo/klaviyo-swift-sdk.git`, branch `rel/5.3.0`)
+  - KlaviyoForms (from `https://github.com/klaviyo/klaviyo-swift-sdk.git`, branch `rel/5.3.0`)
+  - KlaviyoLocation (from `https://github.com/klaviyo/klaviyo-swift-sdk.git`, branch `rel/5.3.0`)
+  - KlaviyoSwift (from `https://github.com/klaviyo/klaviyo-swift-sdk.git`, branch `rel/5.3.0`)
   - KlaviyoSwiftExtension
   - RCT-Folly (from `../node_modules/react-native/third-party-podspecs/RCT-Folly.podspec`)
   - RCTDeprecation (from `../node_modules/react-native/ReactApple/Libraries/RCTFoundation/RCTDeprecation`)
@@ -2469,10 +2473,6 @@ DEPENDENCIES:
 SPEC REPOS:
   trunk:
     - AnyCodable-FlightSchool
-    - KlaviyoCore
-    - KlaviyoForms
-    - KlaviyoLocation
-    - KlaviyoSwift
     - KlaviyoSwiftExtension
     - SocketRocket
 
@@ -2494,6 +2494,18 @@ EXTERNAL SOURCES:
     :tag: hermes-2025-07-07-RNv0.81.0-e0fc67142ec0763c6b6153ca2bf96df815539782
   klaviyo-react-native-sdk:
     :path: "../.."
+  KlaviyoCore:
+    :branch: rel/5.3.0
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+  KlaviyoForms:
+    :branch: rel/5.3.0
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+  KlaviyoLocation:
+    :branch: rel/5.3.0
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+  KlaviyoSwift:
+    :branch: rel/5.3.0
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
   RCT-Folly:
     :podspec: "../node_modules/react-native/third-party-podspecs/RCT-Folly.podspec"
   RCTDeprecation:
@@ -2627,6 +2639,20 @@ EXTERNAL SOURCES:
   Yoga:
     :path: "../node_modules/react-native/ReactCommon/yoga"
 
+CHECKOUT OPTIONS:
+  KlaviyoCore:
+    :commit: 082f13c3c0696cfc973c3f63907d35e0bf26b9ff
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+  KlaviyoForms:
+    :commit: 082f13c3c0696cfc973c3f63907d35e0bf26b9ff
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+  KlaviyoLocation:
+    :commit: 082f13c3c0696cfc973c3f63907d35e0bf26b9ff
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+  KlaviyoSwift:
+    :commit: 082f13c3c0696cfc973c3f63907d35e0bf26b9ff
+    :git: https://github.com/klaviyo/klaviyo-swift-sdk.git
+
 SPEC CHECKSUMS:
   AnyCodable-FlightSchool: 261cbe76757802b17d471b9059b21e6fa5edf57b
   boost: 7e761d76ca2ce687f7cc98e698152abd03a18f90
@@ -2636,13 +2662,13 @@ SPEC CHECKSUMS:
   fmt: a40bb5bd0294ea969aaaba240a927bd33d878cdd
   glog: 5683914934d5b6e4240e497e0f4a3b42d1854183
   hermes-engine: 9f4dfe93326146a1c99eb535b1cb0b857a3cd172
-  klaviyo-react-native-sdk: 308ea86b6b48d10be7127aba51f5800167122b7d
-  KlaviyoCore: 0104cec11bbc1c5838f9a232ea420d15a43bbdfb
-  KlaviyoForms: 4be515497a79df4876b950eb1de5742dc42754e0
-  KlaviyoLocation: edb041d083080aacdf052bc2f6a3b708ec76a721
-  KlaviyoSwift: 596bf5471ec37eed2773ffc603b3026895b93bb8
+  klaviyo-react-native-sdk: 8ee6035a0dff7eab0de01cbf128883c330df0879
+  KlaviyoCore: 0d27552664bb46b171e8256b92a3af94e7261a00
+  KlaviyoForms: 589f91cb245dbf78f657cbc46a1d3dab47bef601
+  KlaviyoLocation: 9ba7810b0cbe1205dad0903c42dc420ba8dd6025
+  KlaviyoSwift: 844dda154601d17f1b6a95dca8e5e6dd918b4664
   KlaviyoSwiftExtension: 310a32489eeca1b2a540903a55028b1ffef6b070
-  RCT-Folly: 846fda9475e61ec7bcbf8a3fe81edfcaeb090669
+  RCT-Folly: 59ec0ac1f2f39672a0c6e6cecdd39383b764646f
   RCTDeprecation: 5eb1d2eeff5fb91151e8a8eef45b6c7658b6c897
   RCTRequired: cebcf9442fc296c9b89ac791dfd463021d9f6f23
   RCTTypeSafety: b99aa872829ee18f6e777e0ef55852521c5a6788
@@ -2708,8 +2734,8 @@ SPEC CHECKSUMS:
   ReactCommon: 5cfd842fcd893bb40fc835f98fadc60c42906a20
   RNPermissions: 86933bcc014e7fa7d77e09b7b0b0b858287d611f
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
-  Yoga: 1e91d83a5286cfd3b725eade59274c92270540d4
+  Yoga: cc4a6600d61e4e9276e860d4d68eebb834a050ba
 
-PODFILE CHECKSUM: 03bdd0145df6393c4c141686be3a82ab1eb4ee5d
+PODFILE CHECKSUM: d7648bc76ebfe99a4d62dbb22c4635482634202a
 
 COCOAPODS: 1.15.2

example/src/KlaviyoReactWrapper.ts

@@ -5,6 +5,8 @@ import {
   type Profile,
   ProfileProperty,
   type FormConfiguration,
+  type FormLifecycleEvent,
+  FormLifecycleEventType,
 } from 'klaviyo-react-native-sdk';
 
 import {
@@ -30,6 +32,28 @@ export const initialize = async () => {
     // Alternate iOS Installation Step 3
     // Initialize the SDK with public key, if initializing from React Native
     Klaviyo.initialize('YOUR_KLAVIYO_PUBLIC_API_KEY');
+
+    // Register form lifecycle handler to log events
+    Klaviyo.registerFormLifecycleHandler((event: FormLifecycleEvent) => {
+      const nameInfo = event.formName ? ` (${event.formName})` : '';
+      console.log(
+        `[Form Lifecycle] ${event.type}: Form ${event.formId}${nameInfo}`
+      );
+
+      switch (event.type) {
+        case FormLifecycleEventType.Shown:
+          console.log(`Form ${event.formId}${nameInfo} is being shown`);
+          break;
+        case FormLifecycleEventType.Dismissed:
+          console.log(`Form ${event.formId}${nameInfo} was dismissed`);
+          break;
+        case FormLifecycleEventType.CtaClicked:
+          console.log(
+            `Form ${event.formId}${nameInfo} CTA was clicked: ${event.buttonLabel}, deep link: ${event.deepLinkUrl}`
+          );
+          break;
+      }
+    });
   } catch (e: any) {
     console.log(e.message, e.code);
   }

ios/KlaviyoBridge.swift

@@ -92,6 +92,38 @@ public class KlaviyoBridge: NSObject {
         #endif
     }
 
+    @MainActor
+    @objc
+    public static func registerFormLifecycleHandler(callback: @escaping ([String: Any]) -> Void) {
+        #if canImport(KlaviyoForms)
+        KlaviyoSDK().registerFormLifecycleHandler { event in
+            var params: [String: Any] = [
+                "formId": event.formId as Any,
+                "formName": event.formName as Any
+            ]
+            switch event {
+            case .formShown:
+                params["type"] = "formShown"
+            case .formDismissed:
+                params["type"] = "formDismissed"
+            case let .formCtaClicked(_, _, buttonLabel, deepLinkUrl):
+                params["type"] = "formCtaClicked"
+                params["buttonLabel"] = buttonLabel as Any
+                params["deepLinkUrl"] = deepLinkUrl.absoluteString as Any
+            }
+            callback(params)
+        }
+        #endif
+    }
+
+    @MainActor
+    @objc
+    public static func unregisterFormLifecycleHandler() {
+        #if canImport(KlaviyoForms)
+        KlaviyoSDK().unregisterFormLifecycleHandler()
+        #endif
+    }
+
     @MainActor
     @objc
     public static func registerGeofencing() {

ios/KlaviyoReactNativeSdk.h

@@ -1,6 +1,6 @@
 
-#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
 
-@interface KlaviyoReactNativeSdk : NSObject <RCTBridgeModule>
+@interface KlaviyoReactNativeSdk : RCTEventEmitter <RCTBridgeModule>
 
 @end

ios/KlaviyoReactNativeSdk.mm

@@ -14,6 +14,10 @@ + (BOOL)requiresMainQueueSetup {
     return YES;
 }
 
+- (NSArray<NSString *> *)supportedEvents {
+    return @[@"FormLifecycleEvent"];
+}
+
 // The values here eventually should come from the iOS SDK once exposed there.
 - (NSDictionary *)constantsToExport {
     return @{
@@ -142,4 +146,22 @@ - (NSDictionary *)constantsToExport {
     });
 }
 
+RCT_EXPORT_METHOD(registerFormLifecycleHandler) {
+    __weak __typeof__(self) weakSelf = self;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [KlaviyoBridge registerFormLifecycleHandlerWithCallback:^(NSDictionary *eventData) {
+            __strong __typeof__(weakSelf) strongSelf = weakSelf;
+            if (strongSelf) {
+                [strongSelf sendEventWithName:@"FormLifecycleEvent" body:eventData];
+            }
+        }];
+    });
+}
+
+RCT_EXPORT_METHOD(unregisterFormLifecycleHandler) {
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [KlaviyoBridge unregisterFormLifecycleHandler];
+    });
+}
+
 @end

klaviyo-react-native-sdk.podspec

@@ -18,13 +18,13 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = { "DEFINES_MODULE" => "YES" }
 
   s.dependency "React-Core"
-  s.dependency "KlaviyoSwift", "5.2.2"
+  s.dependency "KlaviyoSwift"
   # Optional location and forms; included by default, set to 'false' to exclude
   if ENV['KLAVIYO_INCLUDE_LOCATION'] != 'false'
-    s.dependency "KlaviyoLocation", "5.2.2"
+    s.dependency "KlaviyoLocation"
   end
   if ENV['KLAVIYO_INCLUDE_FORMS'] != 'false'
-    s.dependency "KlaviyoForms", "5.2.2"
+    s.dependency "KlaviyoForms"
   end
 
   s.default_subspecs = :none