Push Notification Tracking

Overview

Zixflow tracks three push lifecycle events:

Delivery Confirmed — notification arrives on the device
Notification Opened — user taps the notification body
Action Button Clicked — user taps a named action button

Event	Default `ModuleMessagingPushFCM`	Custom dual-path (example)
Delivered	Automatic when the SDK handles the message	Call `trackMetric(Delivered)` when the SDK helper returns `false`
Opened (body)	Automatic	Track from Activity intent extras
Action clicked	Never automatic	Receiver: Opened + `Push Notification Action Clicked` + cancel notification

How Push Tracking Works

Field	Purpose
`Zixflow-Delivery-ID` (also `ZIXFLOW-Delivery-ID`)	Unique delivery ID
`Zixflow-Delivery-Token` (also `ZIXFLOW-Delivery-Token`)	FCM token for this send

{
  "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",
  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]"
}

Tracking Events

1. Delivery Confirmed

SDK method: trackMetric(TrackMetric.Push(metric = Metric.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:

val deliveryId = data["Zixflow-Delivery-ID"] ?: data["ZIXFLOW-Delivery-ID"] ?: ""
val deliveryToken = data["Zixflow-Delivery-Token"]
    ?: data["ZIXFLOW-Delivery-Token"]
    ?: Zixflow.instance().registeredDeviceToken
    ?: ""

if (deliveryId.isNotEmpty() && deliveryToken.isNotEmpty()) {
    Zixflow.instance().trackMetric(
        TrackMetric.Push(
            metric = Metric.Delivered,
            deliveryId = deliveryId,
            deviceToken = deliveryToken
        )
    )
}

2. Notification Opened

When: User taps the notification body (default content intent). Action buttons are a separate event (still fire Opened first in the receiver). SDK method: trackMetric(TrackMetric.Push(metric = Metric.Opened, ...)) Default module: body opens are automatic. Custom display path — put delivery extras on the content PendingIntent and handle in the Activity:

// In onCreate / onNewIntent
val deliveryId = intent.getStringExtra("Zixflow-Delivery-ID")
val deliveryToken = intent.getStringExtra("Zixflow-Delivery-Token")

if (!deliveryId.isNullOrEmpty() && !deliveryToken.isNullOrEmpty()) {
    Zixflow.instance().trackMetric(
        TrackMetric.Push(
            metric = Metric.Opened,
            deliveryId = deliveryId,
            deviceToken = deliveryToken
        )
    )
}

See MainActivity.handlePushOpenIntent.

3. Action Button Clicked

Never automatic. In your BroadcastReceiver:

// Always fire opened first
Zixflow.instance().trackMetric(
    TrackMetric.Push(
        metric = Metric.Opened,
        deliveryId = deliveryId,
        deviceToken = deliveryToken
    )
)

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 actionDeeplink
    )
)

// Action presses do not auto-dismiss — cancel explicitly
val notificationId = intent.getIntExtra("notification_id", -1)
if (notificationId != -1) {
    NotificationManagerCompat.from(context).cancel(notificationId)
}

Pass the same notification_id into each action PendingIntent that you use with notify(). Use intent action …PUSH_NOTIFICATION_ACTION (match your manifest filter). Reference: NotificationActionReceiver.kt. Required properties: Zixflow-Delivery-ID, action_index, action_name. Recommended: Zixflow-Delivery-Token, action_deeplink. After tracking, open the button deeplink (see Deeplink opening below).

Deeplink opening (example pattern)

The Android example routes body and action deeplinks through one helper (DeeplinkRouter.kt):

Source	Payload field	Handler
Body tap	`deeplink_url` on content `PendingIntent`	`MainActivity` → `DeeplinkRouter.open`
Action tap	`action_buttons[].deeplink` on action intent	`NotificationActionReceiver` → `DeeplinkRouter.open`

object DeeplinkRouter {
    private const val SCHEME = "zixflowdemo" // your app scheme

    fun open(context: Context, deeplink: String?) {
        if (deeplink.isNullOrEmpty()) return
        val uri = Uri.parse(deeplink)

        val inAppIntent = if (uri.scheme == SCHEME) {
            when (uri.host) {
                "sale" -> Intent(context, SaleActivity::class.java)
                "dashboard" -> Intent(context, DashboardActivity::class.java)
                else -> null
            }
        } else {
            null
        }

        val intent = (inAppIntent ?: Intent(Intent.ACTION_VIEW, uri)).apply {
            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        }
        context.startActivity(intent)
    }
}

Body open + deeplink (custom display path — put extras on the content intent, then):

private fun handlePushOpenIntent(intent: Intent) {
    val deliveryId = intent.getStringExtra("delivery_id")
    val deliveryToken = intent.getStringExtra("delivery_token")
    val deeplink = intent.getStringExtra("deeplink")

    if (!deliveryId.isNullOrEmpty() && !deliveryToken.isNullOrEmpty()) {
        Zixflow.instance().trackMetric(
            TrackMetric.Push(
                metric = Metric.Opened,
                deliveryId = deliveryId,
                deviceToken = deliveryToken
            )
        )
    }

    if (!deeplink.isNullOrEmpty()) {
        DeeplinkRouter.open(this, deeplink)
    }
}

Action open + deeplink (after tracking Opened + Action Clicked + cancel):

if (actionDeeplink.isNotEmpty()) {
    DeeplinkRouter.open(context, actionDeeplink)
}

Declare matching intent filters / activities for your custom scheme if you use in-app hosts. External https:// URLs use ACTION_VIEW.

Action Buttons Format

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

Maximum 2 buttons; index is 0-based; empty deeplink is allowed.

Custom FirebaseMessagingService (dual-path)

See Push Notifications — Custom FirebaseMessagingService for:

tools:node="remove" on ZixflowFirebaseMessagingService
3-arg onMessageReceived(context, message, handleNotificationTrigger)
Fallback Delivered + manual display when false

Tracking Decision Flowchart

Notification received?
├── SDK handled (default or 3-arg helper true)
│   └── Delivered (+ body Opened later) automatic
│
└── Custom fallback (helper returned false)
    └── trackMetric(Delivered) + display yourself

User interacted?
├── Body tap
│   ├── trackMetric(Opened)  [auto with default module; Activity extras on custom path]
│   └── DeeplinkRouter.open(deeplink_url)
│
└── Action button
    ├── trackMetric(Opened)  [manual — always]
    ├── track("Push Notification Action Clicked")
    ├── cancel(notification_id)
    └── DeeplinkRouter.open(action_deeplink)

Fallback for Non-Zixflow Push

If there is no delivery ID, skip Zixflow push metrics. Do not use reserved event names for external pushes.

Testing

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

Getting Started

Features

Advanced

Reference

Push Notification Tracking

Overview

How Push Tracking Works

Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Deeplink opening (example pattern)

Action Buttons Format

Custom FirebaseMessagingService (dual-path)

Tracking Decision Flowchart

Fallback for Non-Zixflow Push

Testing

​Overview

​How Push Tracking Works

​Tracking Events

​1. Delivery Confirmed

​2. Notification Opened

​3. Action Button Clicked

​Deeplink opening (example pattern)

​Action Buttons Format

​Custom FirebaseMessagingService (dual-path)

​Tracking Decision Flowchart

​Fallback for Non-Zixflow Push

​Testing

Overview

How Push Tracking Works

Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Deeplink opening (example pattern)

Action Buttons Format

Custom FirebaseMessagingService (dual-path)

Tracking Decision Flowchart

Fallback for Non-Zixflow Push

Testing