feat(push) Action buttons support (#440)

Author: evan-masseau

sdk/push-fcm/src/main/java/com/klaviyo/pushFcm/KlaviyoNotification.kt

@@ -15,11 +15,15 @@ import androidx.core.app.ActivityCompat
 import androidx.core.app.NotificationChannelCompat
 import androidx.core.app.NotificationCompat
 import androidx.core.app.NotificationManagerCompat
+import androidx.core.net.toUri
 import com.google.firebase.messaging.RemoteMessage
 import com.klaviyo.analytics.linking.DeepLinking
 import com.klaviyo.core.Constants
 import com.klaviyo.core.Registry
 import com.klaviyo.core.utils.activityResolved
+import com.klaviyo.pushFcm.KlaviyoRemoteMessage.ActionButton
+import com.klaviyo.pushFcm.KlaviyoRemoteMessage.actionButtons
+import com.klaviyo.pushFcm.KlaviyoRemoteMessage.appendActionButtonExtras
 import com.klaviyo.pushFcm.KlaviyoRemoteMessage.appendKlaviyoExtras
 import com.klaviyo.pushFcm.KlaviyoRemoteMessage.body
 import com.klaviyo.pushFcm.KlaviyoRemoteMessage.channel_description
@@ -68,7 +72,9 @@ class KlaviyoNotification(private val message: RemoteMessage) {
         internal const val NOTIFICATION_PRIORITY = "notification_priority"
         internal const val NOTIFICATION_TAG = "notification_tag"
         internal const val KEY_VALUE_PAIRS_KEY = Constants.KEY_VALUE_PAIRS
+        internal const val ACTION_BUTTONS_KEY = "action_buttons"
         private const val DOWNLOAD_TIMEOUT_MS = 5_000
+        private const val ACTION_REQUEST_CODE_OFFSET = 1
 
         /**
          * Get an integer ID to associate with a notification or its pending intent
@@ -147,9 +153,10 @@ class KlaviyoNotification(private val message: RemoteMessage) {
      * @param context
      * @return [Notification.Builder] to display
      */
-    internal fun buildNotification(context: Context): NotificationCompat.Builder =
-        NotificationCompat.Builder(context, message.channel_id)
-            .setContentIntent(makePendingIntent(context))
+    internal fun buildNotification(context: Context): NotificationCompat.Builder {
+        val requestCodeBase = generateId()
+        return NotificationCompat.Builder(context, message.channel_id)
+            .setContentIntent(makePendingIntent(context, requestCodeBase))
             .setSmallIcon(message.getSmallIcon(context))
             .also { message.getColor(context)?.let { color -> it.setColor(color) } }
             .setContentTitle(message.title)
@@ -159,6 +166,8 @@ class KlaviyoNotification(private val message: RemoteMessage) {
             .setNumber(message.notificationCount)
             .setPriority(message.notificationPriority)
             .setAutoCancel(true)
+            .addActionButtons(context, requestCodeBase)
+    }
 
     private fun URL.applyToNotification(builder: NotificationCompat.Builder) {
         val executor = Executors.newCachedThreadPool()
@@ -208,10 +217,10 @@ class KlaviyoNotification(private val message: RemoteMessage) {
      *
      * @return [PendingIntent]
      */
-    private fun makePendingIntent(context: Context) =
+    private fun makePendingIntent(context: Context, requestCode: Int) =
         PendingIntent.getActivity(
             context,
-            generateId(),
+            requestCode,
             makeOpenedIntent(context),
             PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_ONE_SHOT
         )
@@ -224,16 +233,114 @@ class KlaviyoNotification(private val message: RemoteMessage) {
     private fun makeOpenedIntent(context: Context) = message.deepLink.let { deepLink ->
         when {
             // If deep link is present, use an ACTION_VIEW intent
-            deepLink is Uri -> DeepLinking.makeDeepLinkIntent(deepLink, context)
-                .takeIf { it.activityResolved(context) }
-                ?: DeepLinking.makeLaunchIntent(context).also {
-                    Registry.log.error("Push message contained unsupported deep link: $deepLink")
-                }
+            deepLink is Uri -> makeResolvedDeepLinkIntent(
+                context,
+                deepLink,
+                "Push message contained unsupported deep link: $deepLink"
+            )
             // Else, just launch the app
             else -> DeepLinking.makeLaunchIntent(context)
         }?.apply {
             addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP)
             appendKlaviyoExtras(message)
         }
     }
+
+    /**
+     * Parse action buttons from message data and add them to the notification
+     *
+     * Expected format (iOS-aligned):
+     * [{"id":"...", "label":"...", "action":"deep_link|open_app", "url":"..."}]
+     *
+     * Supported action types:
+     * - "deep_link": Opens app with deep link or URL
+     * - "open_app": Opens app
+     *
+     * Note: Icons are not supported on Android (iOS only).
+     */
+    private fun NotificationCompat.Builder.addActionButtons(
+        context: Context,
+        requestCodeBase: Int
+    ): NotificationCompat.Builder {
+        val actionButtons = message.actionButtons ?: return this
+
+        // Parser has already validated and limited buttons to MAX_ACTION_BUTTONS
+        actionButtons.forEachIndexed { index, button ->
+            // request codes need to be unique, add index + offset to generate unique code
+            // offset required due to zero index, so body and first button have unique codes
+            val requestCode = requestCodeBase + index + ACTION_REQUEST_CODE_OFFSET
+            val action = createButtonAction(context, index, requestCode, button) ?: return@forEachIndexed
+            addAction(action)
+
+            val actionType = when (button) {
+                is ActionButton.DeepLink -> ActionButton.DISPLAY_NAME_DEEP_LINK
+                is ActionButton.OpenApp -> ActionButton.DISPLAY_NAME_OPEN_APP
+            }
+            val destination = when (button) {
+                is ActionButton.DeepLink -> " -> ${button.url}"
+                is ActionButton.OpenApp -> ""
+            }
+            Registry.log.verbose(
+                "Added action button $index: '${button.label}' ($actionType)$destination"
+            )
+        }
+        return this
+    }
+
+    /**
+     * Create a notification action that either opens the app or navigates to a deep link
+     */
+    private fun createButtonAction(
+        context: Context,
+        index: Int,
+        requestCode: Int,
+        button: ActionButton
+    ): NotificationCompat.Action? {
+        val intent = when (button) {
+            is ActionButton.DeepLink -> {
+                val uri = button.url.toUri()
+                makeResolvedDeepLinkIntent(
+                    context,
+                    uri,
+                    "Action button $index contained unsupported deep link: $uri"
+                )
+            }
+            is ActionButton.OpenApp -> {
+                DeepLinking.makeLaunchIntent(context)
+            }
+        }?.apply {
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }?.appendKlaviyoExtras(message)
+            ?.appendActionButtonExtras(button)
+
+        if (intent == null) {
+            Registry.log.warning(
+                "Action button $index could not be created: no launch intent found for host app"
+            )
+            return null
+        }
+
+        val pendingIntent = PendingIntent.getActivity(
+            context,
+            requestCode,
+            intent,
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
+        )
+
+        return NotificationCompat.Action(
+            0, // No icon (icons not supported on Android)
+            button.label,
+            pendingIntent
+        )
+    }
+
+    private fun makeResolvedDeepLinkIntent(
+        context: Context,
+        deepLink: Uri,
+        errorMessage: String
+    ): Intent? = DeepLinking.makeDeepLinkIntent(deepLink, context)
+        .takeIf { it.activityResolved(context) }
+        ?: DeepLinking.makeLaunchIntent(context).also {
+            Registry.log.error(errorMessage)
+        }
 }

sdk/push-fcm/src/main/java/com/klaviyo/pushFcm/KlaviyoRemoteMessage.kt

@@ -21,6 +21,7 @@ import com.klaviyo.core.Registry
 import com.klaviyo.core.config.getApplicationInfoCompat
 import com.klaviyo.core.config.getManifestInt
 import java.net.URL
+import org.json.JSONArray
 import org.json.JSONObject
 
 /**
@@ -29,6 +30,11 @@ import org.json.JSONObject
  */
 object KlaviyoRemoteMessage {
 
+    /**
+     * Maximum number of action buttons supported per notification
+     */
+    private const val MAX_ACTION_BUTTONS = 3
+
     /**
      * Append requisite data from a remote message to an intent
      * for displaying a notification
@@ -43,6 +49,28 @@ object KlaviyoRemoteMessage {
         }
     }
 
+    /**
+     * Append action button tracking data to an intent for analytics
+     *
+     * This enables tracking which specific button was clicked in $opened_push events
+     *
+     * @param button The action button that was clicked
+     */
+    fun Intent.appendActionButtonExtras(button: ActionButton) = apply {
+        putExtra(PACKAGE_PREFIX + "Button ID", button.id)
+        putExtra(PACKAGE_PREFIX + "Button Label", button.label)
+
+        val actionName = when (button) {
+            is ActionButton.DeepLink -> ActionButton.DISPLAY_NAME_DEEP_LINK
+            is ActionButton.OpenApp -> ActionButton.DISPLAY_NAME_OPEN_APP
+        }
+        putExtra(PACKAGE_PREFIX + "Button Action", actionName)
+
+        if (button is ActionButton.DeepLink) {
+            putExtra(PACKAGE_PREFIX + "Button Link", button.url)
+        }
+    }
+
     /**
      * Parse channel ID or fallback on default
      */
@@ -117,6 +145,14 @@ object KlaviyoRemoteMessage {
         Registry.log.warning("Error converting string to URL", it)
     }.getOrNull()
 
+    private fun JSONObject.optNonBlankString(key: String): String? {
+        // JSONObject.optString returns the literal "null" for JSON null values.
+        if (isNull(key)) {
+            return null
+        }
+        return optString(key).takeIf { it.isNotBlank() }
+    }
+
     /**
      * Parse [Uri] to sound resource
      */
@@ -156,6 +192,138 @@ object KlaviyoRemoteMessage {
             }
         }
 
+    /**
+     * Parse action buttons from the iOS-aligned format
+     *
+     * Validates and filters buttons to ensure only valid instances are returned.
+     * Invalid buttons (missing required fields, invalid format) are skipped with warnings.
+     * Maximum of 3 buttons are supported - additional buttons beyond this limit are ignored.
+     *
+     * Expected structure:
+     * [{"id":"...", "label":"...", "action":"deep_link|open_app", "url":"..."}]
+     */
+    val RemoteMessage.actionButtons: List<ActionButton>?
+        get() = this.data[KlaviyoNotification.ACTION_BUTTONS_KEY]?.let { jsonString ->
+            Registry.log.verbose("Parsing action_buttons from: $jsonString")
+            try {
+                val jsonArray = JSONArray(jsonString)
+                val buttons = mutableListOf<ActionButton>()
+                val buttonCount = jsonArray.length()
+                Registry.log.verbose("JSON array has $buttonCount buttons")
+
+                // Parse buttons until we have MAX_ACTION_BUTTONS valid buttons
+                for (i in 0 until buttonCount) {
+                    // Stop if we've already collected the maximum number of valid buttons
+                    if (buttons.size >= MAX_ACTION_BUTTONS) {
+                        Registry.log.warning(
+                            "Reached maximum of $MAX_ACTION_BUTTONS valid action buttons, " +
+                                "remaining ${buttonCount - i} button(s) will be ignored."
+                        )
+                        break
+                    }
+
+                    val jsonObject = jsonArray.optJSONObject(i)
+                    if (jsonObject == null) {
+                        Registry.log.warning(
+                            "Skipping action button $i: invalid JSON object"
+                        )
+                        continue
+                    }
+                    val id = jsonObject.optNonBlankString("id")
+                    val label = jsonObject.optNonBlankString("label")
+
+                    // Validate required label field
+                    if (id == null || label == null) {
+                        Registry.log.warning(
+                            "Skipping action button $i: missing required field(s) (label, id)"
+                        )
+                        continue
+                    }
+
+                    val actionType = jsonObject.optString("action", ActionButton.TYPE_OPEN_APP)
+
+                    // Create appropriate sealed class instance based on action type
+                    when (actionType) {
+                        ActionButton.TYPE_DEEP_LINK -> {
+                            jsonObject.optNonBlankString("url")?.let { url ->
+                                ActionButton.DeepLink(
+                                    id = id,
+                                    label = label,
+                                    url = url
+                                )
+                            } ?: run {
+                                Registry.log.warning(
+                                    "Skipping DEEP_LINK action button $i: missing required url"
+                                )
+                                null
+                            }
+                        }
+                        ActionButton.TYPE_OPEN_APP -> {
+                            ActionButton.OpenApp(id = id, label = label)
+                        }
+                        else -> {
+                            // Skip buttons with unsupported or malformed action types
+                            Registry.log.warning(
+                                "Skipping action button $i: unsupported action type '$actionType'"
+                            )
+                            null
+                        }
+                    }?.let { button ->
+                        Registry.log.verbose("Parsed button $i: $button")
+                        buttons.add(button)
+                    }
+                }
+
+                Registry.log.verbose("Successfully parsed ${buttons.size} valid action buttons")
+                buttons.takeIf { it.isNotEmpty() }
+            } catch (e: Exception) {
+                Registry.log.error(
+                    "Klaviyo SDK failed to parse action_buttons JSON: $jsonString",
+                    e
+                )
+                null
+            }
+        }
+
+    /**
+     * Sealed class representing different types of notification action buttons
+     */
+    sealed class ActionButton {
+        abstract val id: String
+        abstract val label: String
+
+        /**
+         * Button that opens the app without navigating to a specific destination
+         */
+        data class OpenApp(
+            override val id: String,
+            override val label: String
+        ) : ActionButton()
+
+        /**
+         * Button that opens the app and navigates to a deep link destination
+         */
+        data class DeepLink(
+            override val id: String,
+            override val label: String,
+            val url: String
+        ) : ActionButton()
+
+        companion object {
+            /**
+             * Serialized type names used in remote message payload
+             */
+            const val TYPE_OPEN_APP = "open_app"
+            const val TYPE_DEEP_LINK = "deep_link"
+
+            /**
+             * Human-readable display names for analytics
+             */
+            const val DISPLAY_NAME_OPEN_APP = "Open App"
+            const val DISPLAY_NAME_DEEP_LINK = "Deep Link"
+        }
+    }
+
     /**
      * Determine the resource ID of the small icon from provided context
      *