Push Notification Tracking

Last Updated: July 2, 2026
Audience: Client developers integrating Zixflow SDK (Android)
Purpose: Track push notification lifecycle events — delivery, open, and action clicks — so Zixflow can measure campaign performance accurately. See also: Push Notifications and the reference implementation in sdk-examples/android.

Why Push Tracking Matters

When Zixflow sends a push notification to a user’s device, it records that the notification was sent. But it cannot know on its own:

Did the notification actually arrive on the device?
Did the user open it (tap the banner)?
Did the user tap an action button (“Shop Now”, “Remind Me”)?

Your app reports these three moments back to Zixflow using the SDK. This powers the delivery analytics you see in campaign dashboards — open rates, click rates, and conversion funnels after a push.

The Delivery Lifecycle at a Glance

Zixflow Campaign ──sends──▶ Zixflow (via FCM/APNs) ──delivers──▶ Device OS
                                                                │
                                                     ┌──────────┴──────────┐
                                                     │                     │
                                               App foreground        App background
                                               onMessage()           onMessageOpenedApp()
                                                     │                     │
                                            Your app calls:          Your app calls:
                                         trackMetric(delivered)   trackMetric(opened)
                                                     │
                                          User taps action button
                                                     │
                                             Your app calls:
                                        track("Push Notification
                                           Action Clicked")

Each of these SDK calls results in a delivery report event flowing to the Zixflow backend, updating the campaign’s live metrics.

The Push Payload

Zixflow injects two special fields into every push notification’s data payload. Your app uses these to associate the tracking event with the correct campaign delivery.

Field	Example value	Purpose
`Zixflow-Delivery-ID`	`"626533406292836846"`	Unique ID for this delivery (matches campaign record)
`Zixflow-Delivery-Token`	`"dcFRlDhiRbehM1vg-Lx_yn:..."`	The FCM/APNs token the notification was sent to

These appear inside message.data (Flutter/Android) or userInfo (iOS native). The SDK’s trackMetric() method requires both to route the event correctly. Example raw data payload received by the app:

{
  "Zixflow-Delivery-ID": "626533406292836846",
  "Zixflow-Delivery-Token": "dcFRlDhiRbehM1vg...",
  "title": "Flash Sale! 70% OFF 🔥",
  "body": "Limited time only — grab your deal now!",
  "deeplink_url": "https://yourapp.com/sale",
  "image_url": "https://cdn.yourapp.com/banner.png",
  "large_icon_url": "https://cdn.yourapp.com/icon.png",
  "badge": "5",
  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]",
  "notif_id": "626533406292836846"
}

Important: action_buttons is a JSON string (not a nested object). Parse it with json.decode() / JSONSerialization before use.

The Three Tracking Events

1. Delivery Confirmed

Event name (sent to Zixflow): Push Notification Delivered
When to fire: The moment the push data payload arrives on the device — inside your onMessage / onMessageReceived / willPresent handler.
SDK method: Zixflow.instance.trackMetric(deliveryID:, deviceToken:, event: MetricEvent.delivered)
What happens: Zixflow updates the campaign delivery record to delivered. No profile event is stored. Parameters:

Parameter	Required	Description
`deliveryID`	✅	Value of `Zixflow-Delivery-ID` from the push payload
`deviceToken`	✅	Value of `Zixflow-Delivery-Token` from the push payload (or your cached FCM/APNs token)
`event`	✅	`MetricEvent.DELIVERED`

// In FirebaseMessagingService.onMessageReceived()
override fun onMessageReceived(message: RemoteMessage) {
    val deliveryId    = message.data["Zixflow-Delivery-ID"] ?: ""
    val deliveryToken = message.data["Zixflow-Delivery-Token"] ?: cachedToken ?: ""

    if (deliveryId.isNotEmpty() && deliveryToken.isNotEmpty()) {
        Zixflow.instance.trackMetric(
            deliveryID  = deliveryId,
            deviceToken = deliveryToken,
            event       = MetricEvent.DELIVERED
        )
    }
}

When using the default SDK FCM service, delivery is tracked automatically for recognized pushes. When using a custom service (example dual-path), track after the SDK helper returns false.

2. Notification Opened

Event name (sent to Zixflow): Push Notification Opened
When to fire: When the user taps the notification banner. Fire for both body taps and action button taps.
SDK method: Zixflow.instance.trackMetric(deliveryID:, deviceToken:, event: MetricEvent.opened)
What happens: Zixflow updates the campaign delivery record to opened. No profile event is stored. Parameters:

Parameter	Required	Description
`deliveryID`	✅	Value of `Zixflow-Delivery-ID` from the push payload
`deviceToken`	✅	Value of `Zixflow-Delivery-Token` from the push payload
`event`	✅	`MetricEvent.OPENED`

// In your launcher Activity.onCreate() — handle the tap intent
intent.extras?.let { extras ->
    val deliveryId    = extras.getString("Zixflow-Delivery-ID", "")
    val deliveryToken = extras.getString("Zixflow-Delivery-Token") ?: cachedToken ?: ""

    if (deliveryId.isNotEmpty() && deliveryToken.isNotEmpty()) {
        Zixflow.instance.trackMetric(
            deliveryID  = deliveryId,
            deviceToken = deliveryToken,
            event       = MetricEvent.OPENED
        )
    }
}

Default module: body opens are automatic. Custom display path — put delivery extras on the content PendingIntent and handle in the Activity.

3. Action Button Clicked

Event name (sent to Zixflow): Push Notification Action Clicked
When to fire: When the user taps a named action button (“Shop Now”, “Try It Free”, etc.). Always fire trackMetric(opened) first, then fire this event.
SDK method: Zixflow.instance.track(name: "Push Notification Action Clicked", properties: {...})
What happens: Zixflow records a clicked delivery report and captures which button was tapped for campaign analytics.

This is a named track() call — not trackMetric(). There is no MetricEvent enum for clicks.

Properties:

Property	Type	Required	Description
`Zixflow-Delivery-ID`	string	✅	Links this event to the campaign delivery record
`action_index`	integer	✅	0-based index of the button tapped (`0` = first button)
`action_name`	string	✅	Human-readable button label (e.g. `"Shop Now"`)
`Zixflow-Delivery-Token`	string	Recommended	Token push was sent to
`action_deeplink`	string	Recommended	URL the button navigates to
`title`	string	Optional	Notification title
`action_id`	string	Optional	OS-level action identifier (e.g. `"ACTION_0"`)
`source`	string	Optional	`"local_notification"` or `"web_push"`

// In your NotificationActionReceiver
val deliveryId    = intent.getStringExtra("Zixflow-Delivery-ID") ?: ""
val deliveryToken = intent.getStringExtra("Zixflow-Delivery-Token") ?: cachedToken ?: ""
val actionIndex   = intent.getIntExtra("action_index", -1)
val actionName    = intent.getStringExtra("action_name") ?: "Action ${actionIndex + 1}"
val actionDeep    = intent.getStringExtra("action_deeplink") ?: ""

// Always fire opened first
Zixflow.instance.trackMetric(deliveryID = deliveryId, deviceToken = deliveryToken, event = MetricEvent.OPENED)

// Then fire action clicked
Zixflow.instance.track(
    name       = "Push Notification Action Clicked",
    properties = mapOf(
        "Zixflow-Delivery-ID"    to deliveryId,
        "Zixflow-Delivery-Token" to deliveryToken,
        "action_index"           to actionIndex,
        "action_name"            to actionName,
        "action_deeplink"        to actionDeep
    )
)

Never automatic. Pass the same notification_id into each action PendingIntent that you use with notify(). Reference: NotificationActionReceiver.kt.

Platform-Specific Integration

Token Registration

import com.zixflow.Zixflow

// In your FirebaseMessagingService.onNewToken()
override fun onNewToken(token: String) {
    super.onNewToken(token)
    Zixflow.instance.registerDeviceToken(token)
}

// On app start (in case token already exists)
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    Zixflow.instance.registerDeviceToken(token)
}

Track Delivery (Foreground — via onMessageReceived)

override fun onMessageReceived(message: RemoteMessage) {
    val data           = message.data
    val deliveryId     = data["Zixflow-Delivery-ID"] ?: ""
    val deliveryToken  = data["Zixflow-Delivery-Token"] ?: currentToken ?: ""

    if (deliveryId.isNotEmpty() && deliveryToken.isNotEmpty()) {
        Zixflow.instance.trackMetric(
            deliveryID  = deliveryId,
            deviceToken = deliveryToken,
            event       = MetricEvent.DELIVERED
        )
    } else {
        Zixflow.instance.track(
            name       = "Push Notification Delivered",
            properties = mapOf(
                "notification_id" to (data["notif_id"] ?: ""),
                "title"           to (data["title"] ?: ""),
                "body"            to (data["body"] ?: "")
            )
        )
    }
    showLocalNotification(message)
}

Track Open (Notification Tap)

// In your launcher Activity.onCreate() or wherever you handle the intent
intent.extras?.let { extras ->
    val deliveryId    = extras.getString("Zixflow-Delivery-ID", "")
    val deliveryToken = extras.getString("Zixflow-Delivery-Token", "") ?: currentToken ?: ""
    val deeplink      = extras.getString("deeplink_url", "")

    if (deliveryId.isNotEmpty() && deliveryToken.isNotEmpty()) {
        Zixflow.instance.trackMetric(
            deliveryID  = deliveryId,
            deviceToken = deliveryToken,
            event       = MetricEvent.OPENED
        )
    }

    if (deeplink.isNotEmpty()) navigateTo(deeplink)
}

Track Action Button Click

// In your NotificationActionReceiver
val deliveryId   = intent.getStringExtra("Zixflow-Delivery-ID") ?: ""
val actionIndex  = intent.getIntExtra("action_index", -1)
val actionName   = intent.getStringExtra("action_name") ?: "Action ${actionIndex + 1}"
val actionDeep   = intent.getStringExtra("action_deeplink") ?: ""

Zixflow.instance.trackMetric(                    // also fire opened
    deliveryID = deliveryId, deviceToken = token, event = MetricEvent.OPENED
)
Zixflow.instance.track(
    name       = "Push Notification Action Clicked",
    properties = mapOf(
        "Zixflow-Delivery-ID"    to deliveryId,
        "Zixflow-Delivery-Token" to token,
        "notification_id"        to deliveryId,
        "action_index"           to actionIndex,
        "action_name"            to actionName,
        "action_deeplink"        to actionDeep,
        "source"                 to "local_notification"
    )
)

Action Buttons Format

The action_buttons field in the push payload is a JSON-encoded string containing an array of button objects. You must parse it before use. Payload value (raw string):

"[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]"

Parsed structure:

[
  { "name": "Shop Now",  "deeplink": "https://yourapp.com/sale" },
  { "name": "Remind Me", "deeplink": "" }
]

Rules:

Maximum 2 buttons per notification
deeplink may be an empty string — handle gracefully, don’t navigate to a blank URL
Button index is 0-based

Parsing `action_buttons`

data class ActionButton(val name: String, val deeplink: String)

fun parseActionButtons(buttonsJson: String?): List<ActionButton> {
    if (buttonsJson.isNullOrEmpty()) return emptyList()
    return try {
        val jsonArray = JSONArray(buttonsJson)
        val count = minOf(jsonArray.length(), 2)
        List(count) { index ->
            val button = jsonArray.getJSONObject(index)
            ActionButton(
                name = button.getString("name"),
                deeplink = button.optString("deeplink", "")
            )
        }
    } catch (_: Exception) {
        emptyList()
    }
}

Building the Buttons on the Notification (Foreground Path)

// CustomFirebaseMessagingService.kt pattern — data-payload path (foreground / manual display)
val buttonsJson = JSONArray(data["action_buttons"] ?: "[]")
for (i in 0 until minOf(buttonsJson.length(), 2)) {
  val btn = buttonsJson.getJSONObject(i)
  val actionIntent = Intent(this, NotificationActionReceiver::class.java).apply {
    putExtra("Zixflow-Delivery-ID", deliveryId)
    putExtra("Zixflow-Delivery-Token", deliveryToken)
    putExtra("action_index", i)
    putExtra("action_name", btn.optString("name"))
    putExtra("action_deeplink", btn.optString("deeplink"))
    // Needed so the receiver can dismiss this exact notification on press —
    // see "Sticky Notifications" below for why this matters even for non-sticky pushes.
    putExtra("notification_id", notificationId)
  }
  val pendingIntent = PendingIntent.getBroadcast(
    this, i, actionIntent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
  )
  builder.addAction(
    NotificationCompat.Action.Builder(0, btn.optString("name"), pendingIntent).build()
  )
}

NotificationActionReceiver is the BroadcastReceiver that fires the trackMetric(opened) + track("Push Notification Action Clicked") calls shown earlier — it reads back the extras you attached above.

Handling the Tap (End-to-End)

Platform	Callback	Identifier format	Resolve to index
Android (Kotlin)	`NotificationActionReceiver.onReceive`	Read back the `action_index` extra you attached yourself	Already an `Int` — no parsing needed

Important on Android (Kotlin): pressing an action button does not automatically dismiss the notification the way tapping the notification body does — see Sticky Notifications below.

Sticky Notifications

Field: sticky (boolean, sent in the data.* payload as the string "true" / "false") “Sticky” means the notification survives passive dismissal — the user swiping it away, or hitting “Clear all”. This is Android-only.

This requires two separate Android notification flags, not one — and a third piece of manual cleanup for action buttons.

setAutoCancel(true) must always be on, regardless of sticky

setOngoing(true), driven by sticky, is what actually blocks swipe and “Clear all”

Action buttons need an explicit cancel call in your action handler

Mechanism	Controls	Value
`autoCancel` (`setAutoCancel`)	Dismissal on body tap	Always `true`
`ongoing` (`setOngoing`)	Dismissal by swipe and “Clear all”	`sticky`
Explicit cancel call in your action-button handler	Dismissal on action button press	Always called

Android (Kotlin) — Native SDK / Manual Notification Builder

// Read the flag from the data payload (defaults to false if absent/invalid)
val sticky = data["sticky"]?.toBooleanStrictOrNull() ?: false
// Same ID passed to `notificationManager.notify()` — needed so the action-button
// receiver can explicitly cancel this exact notification (see below).
val notificationId = System.currentTimeMillis().toInt()

val notificationBuilder = NotificationCompat.Builder(context, channelId)
    .setContentTitle(title)
    .setContentText(body)
    .setAutoCancel(true)      // always true — body tap always dismisses
    .setOngoing(sticky)       // true = survives swipe + "Clear all"
    // ...other builder calls (icon, image, sound, etc.)

// Action buttons must carry the notification ID so the receiver can cancel it:
PushActionButtons.attachFromRawData(
    deliveryId = deliveryId,
    deliveryToken = deliveryToken,
    actionButtonsJson = data["action_buttons"],
    notificationId = notificationId,   // ← threaded through to the receiver
    builder = notificationBuilder,
    context = context
)

notificationManager.notify(notificationId, notificationBuilder.build())

// NotificationActionReceiver.kt — runs when an action button is pressed
val notificationId = intent.getIntExtra(PushActionButtons.EXTRA_NOTIFICATION_ID, -1)
if (notificationId != -1) {
    // Required regardless of `sticky` — action buttons never auto-dismiss on Android.
    NotificationManagerCompat.from(context).cancel(notificationId)
}

This is implemented in the Zixflow Android SDK itself (ZixflowPushNotificationHandler.kt, used automatically for background/foreground data-payload display) and in the sample app’s custom fallback handler — client apps using the standard Zixflow Android SDK get all of this for free, with zero additional code required, as long as the campaign payload includes sticky in its data block.

Deep Link Handling

Every Zixflow push notification may carry a deeplink_url at the top level and per-button deeplinks in action_buttons. Your app is responsible for routing these to the right in-app screen. Priority order for navigation on tap:

If an action button was tapped → use action_buttons[index].deeplink
If body was tapped → use deeplink_url
If neither is set → open app to default screen

If you’re using the standard Zixflow Android SDK (ZixflowPushNotificationHandler.kt), deep link resolution is handled automatically — you don’t need to write any routing code. This lives in PushMessageProcessorImpl.handleNotificationDeepLink() and runs in this order:

Host-app override — if you registered a notificationCallback in moduleConfig and its onNotificationClicked(context, payload) returns non-null, the SDK stops there and your callback owns navigation entirely.
Try your own app first — builds Intent(ACTION_VIEW, uri).setPackage(context.packageName) and checks resolveActivity().
Fall back externally — if no Activity in your app claims the URI, queryIntentActivities() looks for any other installed app.
Default launcher fallback — if nothing matches at all, your app’s normal launcher Activity opens.

To make your own screens resolvable, add matching intent filters:

<!-- AndroidManifest.xml -->
<activity android:name=".SaleActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="zixflowdemo" android:host="sale" />
    </intent-filter>
</activity>

Or, to fully own routing yourself, implement NotificationCallback.onNotificationClicked():

Zixflow.instance.configure(
    moduleConfig = ZixflowModuleConfig(
        // ...
        notificationCallback = object : NotificationCallback {
            override fun onNotificationClicked(
                context: Context,
                payload: ZixflowParsedPushPayload
            ): Boolean {
                val handled = DeeplinkRouter.open(context, payload.deepLink)
                return handled   // non-null return short-circuits the SDK's own resolution
            }
        }
    )
)

If you’re not using the SDK’s built-in display path (e.g. a custom FirebaseMessagingService fallback), you resolve the URI yourself:

object DeeplinkRouter {
    fun open(context: Context, deeplink: String?): Boolean {
        val uri = deeplink?.takeIf { it.isNotBlank() }?.let(Uri::parse) ?: return false

        if (uri.scheme == "zixflowdemo") {
            val intent = when (uri.host) {
                "sale"      -> Intent(context, SaleActivity::class.java)
                "dashboard" -> Intent(context, DashboardActivity::class.java)
                else        -> null
            }
            if (intent != null) {
                intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK
                context.startActivity(intent)
                return true
            }
        }

        // Not one of our screens — open externally
        return try {
            context.startActivity(Intent(Intent.ACTION_VIEW, uri).apply {
                flags = Intent.FLAG_ACTIVITY_NEW_TASK
            })
            true
        } catch (_: ActivityNotFoundException) {
            false
        }
    }
}

Decision Flowchart

Notification received?
├── YES → trackMetric(delivered)        [always, as soon as data payload arrives]
│
User interacted?
├── Tapped notification body
│   └── trackMetric(opened)             [SDK call with deliveryID + deviceToken]
│       └── Navigate to deeplink_url
│
└── Tapped action button
    ├── trackMetric(opened)             [still track opened]
    └── track("Push Notification Action Clicked")  [with action_index + action_name]
        └── Navigate to button's deeplink

Fallback Behaviour (No Zixflow-Delivery-ID)

If the push notification was sent by a non-Zixflow source, Zixflow-Delivery-ID and Zixflow-Delivery-Token will be absent from the payload. In this case, skip trackMetric(). Push notification event names (Push Notification Delivered, Push Notification Opened, Push Notification Action Clicked) are reserved for Zixflow’s delivery pipeline — they are not stored as user profile events. If you want to track a non-Zixflow push for your own analytics, use a custom event name instead.

Testing

Enable ZixflowLogLevel.DEBUG. In the dashboard → Messaging → Push Notifications, check Delivered, Opened, and Clicked.

Getting Started

Features

Advanced

Reference

Push Notification Tracking

Why Push Tracking Matters

The Delivery Lifecycle at a Glance

The Push Payload

The Three Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Platform-Specific Integration

Token Registration

Track Delivery (Foreground — via onMessageReceived)

Track Open (Notification Tap)

Track Action Button Click

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification (Foreground Path)

Handling the Tap (End-to-End)

Sticky Notifications

Android (Kotlin) — Native SDK / Manual Notification Builder

Deep Link Handling

Decision Flowchart

Fallback Behaviour (No Zixflow-Delivery-ID)

Testing

​Why Push Tracking Matters

​The Delivery Lifecycle at a Glance

​The Push Payload

​The Three Tracking Events

​1. Delivery Confirmed

​2. Notification Opened

​3. Action Button Clicked

​Platform-Specific Integration

​Token Registration

​Track Delivery (Foreground — via onMessageReceived)

​Track Open (Notification Tap)

​Track Action Button Click

​Action Buttons Format

​Parsing action_buttons

​Building the Buttons on the Notification (Foreground Path)

​Handling the Tap (End-to-End)

​Sticky Notifications

​Android (Kotlin) — Native SDK / Manual Notification Builder

​Deep Link Handling

​Decision Flowchart

​Fallback Behaviour (No Zixflow-Delivery-ID)

​Testing

Why Push Tracking Matters

The Delivery Lifecycle at a Glance

The Push Payload

The Three Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Platform-Specific Integration

Token Registration

Track Delivery (Foreground — via onMessageReceived)

Track Open (Notification Tap)

Track Action Button Click

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification (Foreground Path)

Handling the Tap (End-to-End)

Sticky Notifications

Android (Kotlin) — Native SDK / Manual Notification Builder

Deep Link Handling

Decision Flowchart

Fallback Behaviour (No Zixflow-Delivery-ID)

Testing