Push Notification Tracking

Last Updated: July 2, 2026
Audience: Client developers integrating Zixflow SDK (iOS)
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/ios.

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 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 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 willPresent handler.
SDK method: Zixflow.instance.trackMetric(deliveryID:, deviceToken:, event: .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 APNs token)
`event`	✅	`.delivered`

// UNUserNotificationCenterDelegate.userNotificationCenter(_:willPresent:withCompletionHandler:)
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
    let userInfo      = notification.request.content.userInfo
    let deliveryId    = userInfo["Zixflow-Delivery-ID"] as? String ?? ""
    let deliveryToken = userInfo["Zixflow-Delivery-Token"] as? String ?? cachedApnsToken ?? ""

    if !deliveryId.isEmpty && !deliveryToken.isEmpty {
        Zixflow.instance.trackMetric(
            deliveryID:  deliveryId,
            deviceToken: deliveryToken,
            event:       .delivered
        )
    }
    completionHandler([.banner, .sound, .badge])
}

Delivered is reliable when you add a Notification Service Extension + App Groups. See Push Notifications.

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: .opened)
What happens: Zixflow updates the campaign delivery record to opened. No profile event is stored. With autoTrackPushEvents(true), body taps are tracked automatically. You do not need a wrapper for that path. 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`	✅	`.opened`

// UNUserNotificationCenterDelegate.userNotificationCenter(_:didReceive:withCompletionHandler:)
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo      = response.notification.request.content.userInfo
    let deliveryId    = userInfo["Zixflow-Delivery-ID"] as? String ?? ""
    let deliveryToken = userInfo["Zixflow-Delivery-Token"] as? String ?? cachedApnsToken ?? ""

    if !deliveryId.isEmpty && !deliveryToken.isEmpty {
        Zixflow.instance.trackMetric(
            deliveryID:  deliveryId,
            deviceToken: deliveryToken,
            event:       .opened
        )
    }
    completionHandler()
}

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 userNotificationCenter(_:didReceive:withCompletionHandler:), after trackMetric(opened)
if response.actionIdentifier != UNNotificationDefaultActionIdentifier &&
   response.actionIdentifier != UNNotificationDismissActionIdentifier {

    let actionIndex = Int(response.actionIdentifier.replacingOccurrences(of: "ACTION_", with: "")) ?? -1
    let buttons     = parseActionButtons(userInfo["action_buttons"])
    let actionName  = (actionIndex >= 0 && actionIndex < buttons.count)
        ? buttons[actionIndex]["name"] as? String ?? "Action \(actionIndex + 1)"
        : "Action \(actionIndex + 1)"
    let actionDeep  = (actionIndex >= 0 && actionIndex < buttons.count)
        ? buttons[actionIndex]["deeplink"] as? String ?? ""
        : ""

    Zixflow.instance.track(
        name: "Push Notification Action Clicked",
        properties: [
            "Zixflow-Delivery-ID":    deliveryId,
            "Zixflow-Delivery-Token": deliveryTok,
            "action_index":           actionIndex,
            "action_name":            actionName,
            "action_deeplink":        actionDeep
        ]
    )
}

Platform-Specific Integration

Token Registration

import ZixflowAnalytics

// In AppDelegate.application(_:didRegisterForRemoteNotificationsWithDeviceToken:)
func application(_ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let tokenString = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
    Zixflow.instance.registerDeviceToken(deviceToken: tokenString)
}

Track Delivery (Foreground — UNUserNotificationCenterDelegate)

// userNotificationCenter(_:willPresent:withCompletionHandler:)
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
    let userInfo    = notification.request.content.userInfo
    let deliveryId  = userInfo["Zixflow-Delivery-ID"] as? String ?? ""
    let deliveryTok = userInfo["Zixflow-Delivery-Token"] as? String ?? apnsToken ?? ""

    if !deliveryId.isEmpty && !deliveryTok.isEmpty {
        Zixflow.instance.trackMetric(
            deliveryID:  deliveryId,
            deviceToken: deliveryTok,
            event:       .delivered
        )
    }

    // Show the notification even while in foreground
    completionHandler([.banner, .sound, .badge])
}

Track Open (Background / Terminated Tap)

// userNotificationCenter(_:didReceive:withCompletionHandler:)
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo    = response.notification.request.content.userInfo
    let deliveryId  = userInfo["Zixflow-Delivery-ID"] as? String ?? ""
    let deliveryTok = userInfo["Zixflow-Delivery-Token"] as? String ?? apnsToken ?? ""

    if !deliveryId.isEmpty && !deliveryTok.isEmpty {
        Zixflow.instance.trackMetric(
            deliveryID:  deliveryId,
            deviceToken: deliveryTok,
            event:       .opened
        )
    }

    // Handle action buttons
    if response.actionIdentifier != UNNotificationDefaultActionIdentifier &&
       response.actionIdentifier != UNNotificationDismissActionIdentifier {
        let actionIndex = Int(response.actionIdentifier
            .replacingOccurrences(of: "ACTION_", with: "")) ?? -1
        let buttons = parseActionButtons(userInfo["action_buttons"])
        let actionName = (actionIndex >= 0 && actionIndex < buttons.count)
            ? buttons[actionIndex]["name"] as? String ?? "Action \(actionIndex + 1)"
            : "Action \(actionIndex + 1)"
        let deeplink = (actionIndex >= 0 && actionIndex < buttons.count)
            ? buttons[actionIndex]["deeplink"] as? String ?? ""
            : ""

        Zixflow.instance.track(
            name: "Push Notification Action Clicked",
            properties: [
                "Zixflow-Delivery-ID":    deliveryId,
                "Zixflow-Delivery-Token": deliveryTok,
                "notification_id":        deliveryId,
                "action_index":           actionIndex,
                "action_name":            actionName,
                "action_deeplink":        deeplink,
                "source":                 "local_notification"
            ]
        )
    }

    // Handle deeplink navigation
    let deeplink = userInfo["deeplink_url"] as? String ?? ""
    if !deeplink.isEmpty { navigateTo(deeplink) }

    completionHandler()
}

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 (iOS system limit)
deeplink may be an empty string — handle gracefully, don’t navigate to a blank URL
Button index is 0-based
On iOS, button labels are pre-registered at app init due to OS constraints. Use generic labels (“Action 1”, “Action 2”) and rely on the action_name in the tracking event for analytics.

iOS pre-registration example (required):

// Must be done at app launch in AppDelegate / UNUserNotificationCenter setup
let actions = [
    UNNotificationAction(identifier: "ACTION_0", title: "Action 1", options: .foreground),
    UNNotificationAction(identifier: "ACTION_1", title: "Action 2", options: .foreground),
]
let category = UNNotificationCategory(identifier: "ZX_2BTN", actions: actions,
                                       intentIdentifiers: [], options: [])
UNUserNotificationCenter.current().setNotificationCategories([category])

Parsing `action_buttons`

struct ActionButton {
    let name: String
    let deeplink: String
}

func parseActionButtons(_ raw: Any?) -> [ActionButton] {
    guard let jsonString = raw as? String,
          let data = jsonString.data(using: .utf8),
          let array = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]]
    else { return [] }

    return array.prefix(2).map { dict in
        ActionButton(
            name: dict["name"] as? String ?? "",
            deeplink: dict["deeplink"] as? String ?? ""
        )
    }
}

Building the Buttons on the Notification

Unlike Android/Flutter/RN, iOS does not let you attach dynamic buttons to an individual notification. Instead, the two generic actions (ACTION_0 / ACTION_1) are registered once at app launch, and every notification that should show buttons just needs its categoryIdentifier set to match:

// When building the notification content (e.g. in a Notification Service Extension,
// or when constructing a UNMutableNotificationContent for a local notification):
let content = UNMutableNotificationContent()
content.title = title
content.body = body
content.categoryIdentifier = "ZX_2BTN"   // ← tells iOS to show the ACTION_0/ACTION_1 buttons

The actual button labels shown to the user come from the title: passed to UNNotificationAction(identifier:title:options:) at registration time — generic (“Action 1”, “Action 2”) because iOS has no per-push dynamic label API. The real, campaign-specific label (action_name) and action_deeplink only exist in the payload’s action_buttons and are resolved at tap time in your didReceive response: handler.

Handling the Tap (End-to-End)

Platform	Callback	Identifier format	Resolve to index
iOS (Swift)	`didReceive response:`	`response.actionIdentifier` = `"ACTION_0"` / `"ACTION_1"`	`Int(actionIdentifier.replacingOccurrences(of: "ACTION_", with: ""))`

Sticky Notifications

Field: sticky (boolean, sent in the data.* payload as the string "true" / "false") This is Android-only — there is no iOS/APNs equivalent. Notifications on iOS can always be swiped away by the user; there is no API to prevent this. The sticky field can be safely ignored on iOS.

// No sticky/autoCancel/ongoing equivalent exists in UNNotificationRequest / UNMutableNotificationContent.
// Notifications on iOS can always be swiped away by the user; there is no API to prevent this.
// The `sticky` field can be safely ignored on iOS.

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

// NavigationRouter.swift
final class NavigationRouter: ObservableObject {
    static let shared = NavigationRouter()

    enum Screen: Identifiable { case sale, dashboard; var id: Self { self } }
    @Published var activeScreen: Screen?

    @discardableResult
    func open(deeplink: String?) -> Bool {
        guard let deeplink, !deeplink.isEmpty,
              let url = URL(string: deeplink),
              url.scheme == "zixflowdemo" else { return false }

        switch url.host {
        case "sale":      activeScreen = .sale
        case "dashboard": activeScreen = .dashboard
        default:          return false
        }
        return true
    }
}

// AppDelegate.swift — didReceive response:
let deeplink = userInfo["deeplink_url"] as? String ?? ""
if !NavigationRouter.shared.open(deeplink: deeplink),
   !deeplink.isEmpty, let url = URL(string: deeplink) {
    UIApplication.shared.open(url)   // not one of our screens — open externally
}

// ZixflowSdkExampleApp.swift — present whichever screen the router activated
@StateObject private var router = NavigationRouter.shared

var body: some Scene {
    WindowGroup {
        ContentView()
            .sheet(item: $router.activeScreen) { screen in
                switch screen {
                case .sale:      SaleView()
                case .dashboard: DashboardView()
                }
            }
    }
}

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 are reserved for Zixflow’s delivery pipeline — they are not stored as user profile events.

Testing

Enable .logLevel(.debug). Dashboard → Messaging → Push Notifications: Delivered, Opened, Clicked. Use a physical device.

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 — UNUserNotificationCenterDelegate)

Track Open (Background / Terminated Tap)

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification

Handling the Tap (End-to-End)

Sticky Notifications

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 — UNUserNotificationCenterDelegate)

​Track Open (Background / Terminated Tap)

​Action Buttons Format

​Parsing action_buttons

​Building the Buttons on the Notification

​Handling the Tap (End-to-End)

​Sticky Notifications

​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 — UNUserNotificationCenterDelegate)

Track Open (Background / Terminated Tap)

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification

Handling the Tap (End-to-End)

Sticky Notifications

Deep Link Handling

Decision Flowchart

Fallback Behaviour (No Zixflow-Delivery-ID)

Testing