feat: Add form lifecycle hooks for in-app forms (Part of MAGE-287)

Adds FormLifecycleEvent sealed interface with event-specific data,
FormLifecycleCallback registration API, and lifecycle event firing
from PresentationManager and NativeBridge.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: evan-masseau

AGENTS.md

@@ -1,6 +1,24 @@
 # AI Agent Guidelines
 
-Assume the role of an experienced Android SDK developer. Prioritize code quality, maintainability, and a smooth third-party developer experience. Search existing implementations before creating new code; refactor duplicated logic into shared utilities (typically in `sdk/core`). Default to modern, idiomatic Kotlin. Start pull requests in Draft unless told otherwise; fill in the PR template concisely.
+This file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when
+working with code in this repository.
+
+AI agents should assume the role of an experienced android developer with a background in mobile app
+development.
+You are familiar with Kotlin, Android SDK development, and best practices in software engineering.
+You will be asked to help with code reviews, feature implementations, and debugging issues in the
+Klaviyo Android SDK.
+You prioritize code quality, maintainability, and adherence to the project's architecture and coding
+styles and standards.
+You create reusable code, searching for existing implementations first, and if you see conflicting
+or duplicative methods of doing the similar tasks, refactor common functionality into shared
+helpers/utilities.
+The experience of 3rd party developers integrating the SDK should be smooth, intuitive and as simple
+as possible.
+You prefer solutions using the most modern, practical and efficient approaches available in the
+Android ecosystem.
+When creating pull requests, you should typically start in Draft unless prompted otherwise, and
+fill in the repository's PR template with concise details in the appropriate sections.
 
 ## Intro
 
@@ -16,9 +34,11 @@ analytics, push notifications, and in-app messaging (aka forms).
 # Build the entire project
 ./gradlew build
 
-# Build a specific module (pattern applies to all modules under sdk/)
-# Modules: core, analytics, forms, forms-core, push-fcm, location, location-core
-./gradlew :sdk:{module}:build
+# Build a specific module
+./gradlew :sdk:core:build
+./gradlew :sdk:analytics:build
+./gradlew :sdk:forms:build
+./gradlew :sdk:push-fcm:build
 
 # Assemble only (compile without testing)
 ./gradlew assemble
@@ -39,11 +59,15 @@ field overrides via reflection.
 # Run all tests in the project
 ./gradlew test
 
-# Run unit tests for a specific module (same module list as build)
-./gradlew :sdk:{module}:testDebugUnitTest
+# Run unit tests for a specific module
+./gradlew :sdk:core:testDebugUnitTest
+./gradlew :sdk:analytics:testDebugUnitTest
+./gradlew :sdk:forms:testDebugUnitTest
+./gradlew :sdk:push-fcm:testDebugUnitTest
 
 # Run a specific unit test with "--tests" flag
 ./gradlew :sdk:core:testDebugUnitTest --tests "com.klaviyo.core.KLogTest"
+
 ```
 
 ### Lint Commands
@@ -89,18 +113,6 @@ The Klaviyo Android SDK is organized into multiple modules, each with specific r
     - Connects to Klaviyo's CDN for form content
     - Manages form display timing and user interaction
 
-5. **Forms-Core Module** (`sdk/forms-core`):
-    - Auto-registers forms services via ContentProvider
-    - Allows forms feature to be excluded at build time without a no-op module
-
-6. **Location Module** (`sdk/location`):
-    - Provides location/geofencing capabilities (requires runtime permissions)
-    - Depends on location-core for base registration
-
-7. **Location-Core Module** (`sdk/location-core`):
-    - Auto-registers location services via ContentProvider (no runtime permissions required)
-    - Enables location feature without the full location module
-
 ### Key Components
 
 1. **Klaviyo Object** (`Klaviyo.kt`):
@@ -125,9 +137,9 @@ The Klaviyo Android SDK is organized into multiple modules, each with specific r
 
 ### CI/CD Pipeline
 
-The project uses GitHub Actions for CI/CD, particularly for running tests and lint checks on pull requests.
-Ensure that relevant tests pass and lint checks are successful before committing any changes.
-NEVER use --no-verify as a way to work around pre-commit checks unless prompted.
+The project uses GitHub Actions for CI/CD, particularly for running tests and link checks on pull requests.
+Ensure that all tests pass and lint checks are successful before committing any changes.
+Do not use --no-verify as a way to work around pre-commit checks unless prompted.
 
 ### Testing Approach
 

README.md

@@ -103,10 +103,10 @@ The sample app serves as both a reference implementation and a testing tool for
       ```kotlin
       // build.gradle.kts
       dependencies {
-          implementation("com.github.klaviyo.klaviyo-android-sdk:analytics:4.3.1")
-          implementation("com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.3.1")
-          implementation("com.github.klaviyo.klaviyo-android-sdk:forms:4.3.1")
-          implementation("com.github.klaviyo.klaviyo-android-sdk:location:4.3.1")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:analytics:4.3.0")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.3.0")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:forms:4.3.0")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:location:4.3.0")
       }
       ```
    </details>
@@ -117,10 +117,10 @@ The sample app serves as both a reference implementation and a testing tool for
       ```groovy
        // build.gradle
        dependencies {
-           implementation "com.github.klaviyo.klaviyo-android-sdk:analytics:4.3.1"
-           implementation "com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.3.1"
-           implementation "com.github.klaviyo.klaviyo-android-sdk:forms:4.3.1"
-           implementation "com.github.klaviyo.klaviyo-android-sdk:location:4.3.1"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:analytics:4.3.0"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.3.0"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:forms:4.3.0"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:location:4.3.0"
        }
       ```
    </details>

docs/filelogger-instructions.md

@@ -1,2 +1,2 @@
 <!-- Redirect to latest version -->
-<meta HTTP-EQUIV="REFRESH" content="0; url=./4.3.1/index.html">
+<meta HTTP-EQUIV="REFRESH" content="0; url=./4.3.0/index.html">

docs/index.html

@@ -4,7 +4,12 @@ import android.app.Application
 import android.content.Context
 import android.widget.Toast
 import com.klaviyo.analytics.Klaviyo
+import com.klaviyo.core.Registry
+import com.klaviyo.forms.FormLifecycleEvent.FormCtaClicked
+import com.klaviyo.forms.FormLifecycleEvent.FormDismissed
+import com.klaviyo.forms.FormLifecycleEvent.FormShown
 import com.klaviyo.forms.registerForInAppForms
+import com.klaviyo.forms.registerFormLifecycleCallback
 import com.klaviyo.location.registerGeofencing
 
 class SampleApplication : Application() {
@@ -22,6 +27,26 @@ class SampleApplication : Application() {
                 // If not using a deep link handler, Klaviyo will send an Intent to your app with the deep link in intent.data
                 showToast("Deep link to: $uri")
             }
+            .registerFormLifecycleCallback { event ->
+                // OPTIONAL SETUP NOTE: Register a callback to receive form lifecycle events
+                // This allows you to track when forms are shown, dismissed, or when CTAs are clicked
+                when (event) {
+                    is FormShown -> {
+                        Registry.log.debug("Form shown: ${event.formId} ${event.formName}")
+                        showToast("Form shown: ${event.formId} ${event.formName}")
+                    }
+                    is FormDismissed -> {
+                        Registry.log.debug("Form dismissed: ${event.formId} ${event.formName}")
+                        showToast("Form dismissed: ${event.formId} ${event.formName}")
+                    }
+                    is FormCtaClicked -> {
+                        Registry.log.debug(
+                            "Form CTA: ${event.buttonLabel} -> ${event.deepLinkUrl}"
+                        )
+                        showToast("Form CTA: ${event.buttonLabel} -> ${event.deepLinkUrl}")
+                    }
+                }
+            }
     }
 }