Version 4.4.0 (#436)

Author: evan-masseau

README.md

@@ -28,6 +28,7 @@ send them timely push notifications via [FCM (Firebase Cloud Messaging)](https:/
   - [Collecting Push Tokens](#collecting-push-tokens)
   - [Receiving Push Notifications](#receiving-push-notifications)
     - [Rich Push](#rich-push)
+    - [Push Action Buttons](#push-action-buttons)
     - [Tracking Open Events](#tracking-open-events)
     - [Silent Push Notifications](#silent-push-notifications)
     - [Custom Data](#custom-data)
@@ -37,6 +38,7 @@ send them timely push notifications via [FCM (Firebase Cloud Messaging)](https:/
   - [Setup](#setup-1)
   - [In-App Forms Session Configuration](#in-app-forms-session-configuration)
   - [Unregistering from In-App Forms](#unregistering-from-in-app-forms)
+  - [Monitoring Form Lifecycle Events](#monitoring-form-lifecycle-events)
 - [Geofencing](#geofencing)
   - [Setup](#setup-2)
   - [Requesting Permissions](#requesting-permissions)
@@ -103,10 +105,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.2")
-          implementation("com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.3.2")
-          implementation("com.github.klaviyo.klaviyo-android-sdk:forms:4.3.2")
-          implementation("com.github.klaviyo.klaviyo-android-sdk:location:4.3.2")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:analytics:4.4.0")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.4.0")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:forms:4.4.0")
+          implementation("com.github.klaviyo.klaviyo-android-sdk:location:4.4.0")
       }
       ```
    </details>
@@ -117,10 +119,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.2"
-           implementation "com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.3.2"
-           implementation "com.github.klaviyo.klaviyo-android-sdk:forms:4.3.2"
-           implementation "com.github.klaviyo.klaviyo-android-sdk:location:4.3.2"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:analytics:4.4.0"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:push-fcm:4.4.0"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:forms:4.4.0"
+           implementation "com.github.klaviyo.klaviyo-android-sdk:location:4.4.0"
        }
       ```
    </details>
@@ -479,6 +481,11 @@ attaching it to the notification is handled within `KlaviyoPushService`. If an i
 (e.g. if the device has a poor network connection) the notification will be displayed without an image
 after the download times out.
 
+#### Push Action Buttons
+[Push Action Buttons](https://help.klaviyo.com/hc/en-us/article/46285872166683) provide the ability to add clickable buttons to
+push notification messages. These buttons can show custom text, and, when clicked, deep link or open your app.
+A notification can include up to 3 buttons. No additional SDK setup is required.
+
 #### Tracking Open Events
 To track push notification opens, you must call `Klaviyo.handlePush(intent)` when your app is launched from an intent.
 This method will check if the app was opened from a notification originating from Klaviyo and if so, create an 
@@ -695,6 +702,7 @@ See the table below to understand available features by SDK version.
 | Time Delay           | 4.0.0               |
 | Audience Targeting   | 4.0.0               |
 | Event Triggers       | 4.1.0               |
+| Form Lifecycle Hooks | 4.4.0               |
 
 ### Setup
 To begin, call `Klaviyo.registerForInAppForms()` after initializing the SDK with your public API key.
@@ -787,6 +795,76 @@ object to the `registerForInAppForms()` method. For example, to set a session ti
 
 **Note:** After unregistering, the next call to `registerForInAppForms()` will be considered a new session by the SDK.
 
+### Monitoring Form Lifecycle Events
+
+> Form lifecycle events are available in SDK version 4.4.0 and higher.
+
+You can register a handler to receive callbacks whenever a form is shown, dismissed, or a CTA button is tapped.
+This is useful for forwarding engagement data to a third-party analytics platform such as Amplitude, Segment, or Mixpanel.
+
+The handler is invoked on the **main thread**, so avoid performing long-running or blocking work inside it.
+
+<details open>
+   <summary>Kotlin</summary>
+
+   ```kotlin
+   import com.klaviyo.analytics.Klaviyo
+   import com.klaviyo.forms.FormLifecycleEvent.FormCtaClicked
+   import com.klaviyo.forms.FormLifecycleEvent.FormDismissed
+   import com.klaviyo.forms.FormLifecycleEvent.FormShown
+   import com.klaviyo.forms.registerFormLifecycleHandler
+   import com.klaviyo.forms.unregisterFormLifecycleHandler
+
+   Klaviyo.registerFormLifecycleHandler { event ->
+       when (event) {
+           is FormShown -> {
+               // e.g. myAnalytics.track("Form Shown", mapOf("formId" to event.formId, "formName" to event.formName))
+           }
+           is FormDismissed -> {
+               // e.g. myAnalytics.track("Form Dismissed", mapOf("formId" to event.formId, "formName" to event.formName))
+           }
+           is FormCtaClicked -> {
+               // e.g. myAnalytics.track("Form CTA Clicked", mapOf(
+               //     "formId" to event.formId,
+               //     "formName" to event.formName,
+               //     "buttonLabel" to event.buttonLabel,
+               //     "deepLinkUrl" to event.deepLinkUrl.toString()
+               // ))
+           }
+       }
+   }
+
+   // To stop receiving events, unregister the handler
+   Klaviyo.unregisterFormLifecycleHandler()
+   ```
+</details>
+
+<details>
+   <summary>Java</summary>
+
+   ```java
+   import com.klaviyo.forms.FormLifecycleEvent;
+   import com.klaviyo.forms.KlaviyoForms;
+
+   KlaviyoForms.registerFormLifecycleHandler(event -> {
+       if (event instanceof FormLifecycleEvent.FormShown shown) {
+           // e.g. myAnalytics.track("Form Shown", ...)
+       } else if (event instanceof FormLifecycleEvent.FormDismissed dismissed) {
+           // e.g. myAnalytics.track("Form Dismissed", ...)
+       } else if (event instanceof FormLifecycleEvent.FormCtaClicked ctaClicked) {
+           // e.g. myAnalytics.track("Form CTA Clicked", ...)
+       }
+   });
+
+   // To stop receiving events, unregister the handler
+   KlaviyoForms.unregisterFormLifecycleHandler();
+   ```
+</details>
+
+Registering a lifecycle handler is optional and does not affect normal form behavior — forms are displayed and dismissed
+regardless of whether a handler is registered. Only one handler can be registered at a time; calling
+`registerFormLifecycleHandler` again replaces the previous registration.
+
 ## Geofencing
 
 [Geofencing](https://help.klaviyo.com/hc/en-us/articles/45194892526747) allows you to trigger events when users enter or exit geographic regions defined in your Klaviyo account.

docs/index.html

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

sample/build.gradle.kts

@@ -133,7 +133,7 @@ dependencies {
 
     // Other app and testing dependencies (refreshVersions syntax)
     implementation(platform(AndroidX.compose.bom))
-    implementation(AndroidX.core.ktx)
+    implementation("androidx.core:core-ktx:1.17.0")
     implementation(AndroidX.lifecycle.runtime.ktx)
     implementation(AndroidX.lifecycle.viewModelCompose)
     implementation(AndroidX.activity.compose)

sample/src/main/java/com/klaviyo/sample/SampleApplication.kt

@@ -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.registerFormLifecycleHandler
 import com.klaviyo.location.registerGeofencing
 
 class SampleApplication : Application() {
@@ -22,6 +27,27 @@ 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")
             }
+            .registerFormLifecycleHandler { 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 Lifecycle: ${event.formName} (${event.formId}) Shown"
+                        )
+                    }
+                    is FormDismissed -> {
+                        Registry.log.debug(
+                            "Form Lifecycle: ${event.formName} (${event.formId}) Dismissed"
+                        )
+                    }
+                    is FormCtaClicked -> {
+                        Registry.log.debug(
+                            "Form Lifecycle: CTA ${event.buttonLabel} -> ${event.deepLinkUrl} from ${event.formName} (${event.formId})"
+                        )
+                    }
+                }
+            }
     }
 }
 

sdk/analytics/src/main/java/com/klaviyo/analytics/Klaviyo.kt

@@ -4,6 +4,7 @@ import android.app.Application
 import android.content.Context
 import android.content.Intent
 import android.net.Uri
+import androidx.core.app.NotificationManagerCompat
 import androidx.core.net.toUri
 import com.klaviyo.analytics.linking.DeepLinkHandler
 import com.klaviyo.analytics.linking.DeepLinking
@@ -17,6 +18,7 @@ import com.klaviyo.analytics.networking.KlaviyoApiClient
 import com.klaviyo.analytics.state.KlaviyoState
 import com.klaviyo.analytics.state.State
 import com.klaviyo.analytics.state.StateSideEffects
+import com.klaviyo.core.Constants
 import com.klaviyo.core.Constants.KEY_VALUE_PAIRS
 import com.klaviyo.core.Constants.PACKAGE_PREFIX
 import com.klaviyo.core.Constants.TRACKING_PARAMETER
@@ -333,6 +335,15 @@ object Klaviyo {
 
             // Not using createEvent here to avoid nested safeApply calls
             Registry.get<State>().createEvent(event, Registry.get<State>().getAsProfile())
+        }?.safeApply {
+            // Dismiss the notification if opened via an action button.
+            // Body taps are handled by setAutoCancel(true) on the notification builder,
+            // but action button taps don't trigger auto-cancel (standard Android behavior).
+            intent?.getStringExtra(Constants.NOTIFICATION_TAG_EXTRA)?.let { tag ->
+                NotificationManagerCompat
+                    .from(Registry.config.applicationContext)
+                    .cancel(tag, Constants.NOTIFICATION_ID)
+            }
         }?.safeApply {
             // If a Klaviyo notification is deep linked, invoke the developer's deep link handler
             // if registered. If not, do nothing. The host already received the appropriate intent.

sdk/core/src/main/java/com/klaviyo/core/Constants.kt

@@ -18,4 +18,20 @@ object Constants {
      * Klaviyo push messages contain metadata to associate an event with its original transmission
      */
     const val TRACKING_PARAMETER = "_k"
+
+    /**
+     * Intent extra key for the notification tag, used to dismiss the notification
+     * when an action button is tapped and [handlePush] processes the intent.
+     *
+     * Uses [INTERNAL_PREFIX] instead of [PACKAGE_PREFIX] to avoid being swept into
+     * analytics event properties by [appendKlaviyoExtras].
+     */
+    private const val INTERNAL_PREFIX = "_klaviyo."
+    const val NOTIFICATION_TAG_EXTRA = INTERNAL_PREFIX + "notification_tag"
+
+    /**
+     * Fixed notification ID used in all notify/cancel calls.
+     * Notifications are uniquely identified by their string tag, not this ID.
+     */
+    const val NOTIFICATION_ID = 0
 }

sdk/core/src/main/res/values/strings.xml

@@ -2,7 +2,7 @@
 <resources>
     <!-- Please do not modify / override these values, they are critical for internal versioning  -->
     <string name="klaviyo_sdk_name_override">android</string>
-    <string name="klaviyo_sdk_version_override">4.3.2</string>
+    <string name="klaviyo_sdk_version_override">4.4.0</string>
     <string name="klaviyo_sdk_plugin_name_override"/>
     <string name="klaviyo_sdk_plugin_version_override"/>
 </resources>

sdk/forms-core/src/main/java/com/klaviyo/forms/FormLifecycleEvent.kt

@@ -0,0 +1,63 @@
+package com.klaviyo.forms
+
+import android.net.Uri
+
+/**
+ * Represents a lifecycle event of an in-app form, carrying contextual metadata
+ * about the form and event-specific data.
+ *
+ * Use [formId] and [formName] to identify the form associated with any event.
+ * For CTA-specific data, match on [FormCtaClicked] to access [FormCtaClicked.buttonLabel]
+ * and [FormCtaClicked.deepLinkUrl].
+ */
+sealed interface FormLifecycleEvent {
+    /**
+     * The form ID of the form associated with this event.
+     */
+    val formId: String
+
+    /**
+     * The display name of the form associated with this event.
+     */
+    val formName: String
+
+    /**
+     * Triggered when a form is shown to the user.
+     *
+     * Fired after the SDK has initiated form presentation.
+     */
+    data class FormShown(
+        override val formId: String,
+        override val formName: String
+    ) : FormLifecycleEvent
+
+    /**
+     * Triggered when a form is dismissed by the user.
+     *
+     * Fired after the SDK has initiated form dismissal. Fires for
+     * user-initiated dismissals (e.g. tapping outside, close button).
+     * Does not fire when the SDK tears down the form internally
+     * (session timeouts, aborts).
+     */
+    data class FormDismissed(
+        override val formId: String,
+        override val formName: String
+    ) : FormLifecycleEvent
+
+    /**
+     * Triggered when a user taps a call-to-action (CTA) button in a form
+     * that has a deep link URL configured.
+     *
+     * Fired after the SDK has initiated deep link navigation. Not emitted
+     * if no deep link URL is configured for the CTA.
+     *
+     * @property buttonLabel The text label of the CTA button.
+     * @property deepLinkUrl The deep link URI configured for the CTA.
+     */
+    data class FormCtaClicked(
+        override val formId: String,
+        override val formName: String,
+        val buttonLabel: String,
+        val deepLinkUrl: Uri
+    ) : FormLifecycleEvent
+}

sdk/forms-core/src/main/java/com/klaviyo/forms/FormLifecycleHandler.kt

@@ -0,0 +1,31 @@
+package com.klaviyo.forms
+
+/**
+ * Functional interface for handling form lifecycle events.
+ *
+ * Implement this interface to receive notifications when in-app form lifecycle events occur.
+ *
+ * **Threading:** The handler is always invoked on the main thread.
+ * Lifecycle callbacks fire after the SDK has already initiated the corresponding
+ * action (presentation, dismissal, or deep link navigation). Avoid performing
+ * long-running or blocking work in this handler, as it runs on the main thread.
+ *
+ * Example usage:
+ * ```
+ * Klaviyo.registerFormLifecycleHandler { event ->
+ *     when (event) {
+ *         is FormLifecycleEvent.FormShown -> Log.d("Forms", "Form shown: ${event.formId}")
+ *         is FormLifecycleEvent.FormDismissed -> Log.d("Forms", "Form dismissed: ${event.formId}")
+ *         is FormLifecycleEvent.FormCtaClicked -> Log.d("Forms", "CTA: ${event.buttonLabel}")
+ *     }
+ * }
+ * ```
+ */
+fun interface FormLifecycleHandler {
+    /**
+     * Called when a form lifecycle event occurs.
+     *
+     * @param event The lifecycle event, containing form metadata and event-specific data.
+     */
+    fun onFormLifecycleEvent(event: FormLifecycleEvent)
+}