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.

Two Ways to Handle a Zixflow Push — and Why Tracking Is Required in Both

Every push Zixflow sends can be displayed in one of two ways. You choose Native or Custom in the dashboard — and that choice decides the payload shape (see APNs Wire Format). Native mode puts display content in aps.alert; Custom mode also sends top-level display keys and mutable-content: 1 so your Notification Service Extension can enrich the banner.

	A. Native (OS/APNs-rendered)	B. Custom (app-enriched UI)
Dashboard selection	Native	Custom
Payload shape	`aps.alert` carries title/body; top-level keys are tracking + routing only	`aps.alert` + `mutable-content: 1`; top-level keys include the full display content
Who builds the visible notification	iOS itself	iOS shows a banner; your NSE can enrich it (image, badge)
When your code runs	Only on tap (`didReceive`), or in `willPresent` (foreground)	NSE on arrival (even locked/killed), plus tap handlers
Image / action buttons / sticky / large icon	Native `aps` has no image attachment or action buttons. Sticky and large icon have no iOS equivalent	Image via NSE (`image_url`). Action buttons via pre-registered `ZX_2BTN` category. Sticky / large icon still N/A
Delivery/Open tracking	Still required	Same requirement

The one thing both paths share: tracking is never automatic. Zixflow only learns about delivery/opens/clicks when your app calls trackMetric() / track().

Path A (Native, app backgrounded/killed): willPresent does not run. Track Opened from didReceive on tap. For Delivered on the lock screen, add a Notification Service Extension.
Path B (Custom): Zixflow sends mutable-content: 1. Track Delivered from the NSE the moment the push arrives, then track Opened / Push Notification Action Clicked from your tap handlers.

Minimal “OS renders it, I only track” implementation:

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo
    trackDeliveredIfPresent(userInfo)
    completionHandler([])   // [] = no custom presentation; omit entirely for the default OS look
}

// Required for pure silent/content-available pushes — the only path they reach your code at all:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    trackDeliveredIfPresent(userInfo)
    completionHandler(.newData)
}

Reference implementation: sdk-examples/ios ships a runtime “Custom handling” toggle that switches live between path A and path B on the same running app.

iOS keeps aps.alert in both modes on purpose. Unlike Android, iOS will not show anything on the lock screen from your custom keys alone — a visible push requires an aps.alert. So in Custom mode Zixflow still sends a minimal aps.alert (so the banner appears when the app is backgrounded/locked) plus mutable-content: 1, and your Notification Service Extension reads the top-level keys to enrich the banner and to track delivery.

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. They appear as top-level keys next to aps (in userInfo). The SDK’s trackMetric() method requires both.

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

The rest of the payload depends on the rendering mode chosen in the dashboard (see APNs Wire Format):

Native (OS-rendered): display content lives in aps.alert; top-level keys are tracking + routing only.
Custom (app-enriched): top-level keys also carry title/body/image/buttons, and aps sets mutable-content: 1 so your NSE can enrich the banner.

Example Custom-mode payload:

{
  "aps": {
    "alert": { "title": "Flash Sale! 70% OFF 🔥", "body": "Limited time only — grab your deal now!" },
    "mutable-content": 1,
    "sound": "notification_tone.caf",
    "category": "ZX_2BTN"
  },
  "Zixflow-Delivery-ID": "626533406292836846",
  "Zixflow-Delivery-Token": "dcFRlDhiRbehM1vg...",
  "title": "Flash Sale! 70% OFF 🔥",
  "body": "Limited time only — grab your deal now!",
  "image_url": "https://cdn.yourapp.com/banner.png",
  "large_icon_url": "https://cdn.yourapp.com/icon.png",
  "deeplink_url": "https://yourapp.com/sale",
  "badge": "5",
  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]",
  "notif_id": "626533406292836846",
  "template_id": "469935",
  "workspace_id": "68be4f797a6494676161e98b"
}

Example Native-mode payload (tracking + routing only at top level):

{
  "aps": {
    "alert": { "title": "Flash Sale! 70% OFF 🔥", "body": "Limited time only — grab your deal now!" },
    "badge": 5,
    "sound": "notification_tone.caf",
    "thread-id": "626533406292836846",
    "category": "ZX_2BTN"
  },
  "Zixflow-Delivery-ID": "626533406292836846",
  "Zixflow-Delivery-Token": "dcFRlDhiRbehM1vg...",
  "deeplink_url": "https://yourapp.com/sale",
  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]",
  "notif_id": "626533406292836846",
  "template_id": "469935",
  "workspace_id": "68be4f797a6494676161e98b"
}

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

How to handle and show push notifications sent by Zixflow

APNs (iOS) Wire Format

iOS has no notification vs data split — everything lives in one flat JSON object. Apple’s own fields live under the reserved aps key; every Zixflow-specific field is a top-level sibling key to aps (not nested inside it, and not inside aps.alert). The dashboard rendering mode decides where the display content lives.

Mode 1 — Native (OS-rendered)

aps.alert carries the title/body and aps carries the badge/sound/category; the Zixflow-specific top-level keys carry only tracking + routing — no redundant title/body. See the Native example above.

Mode 2 — Custom (app-enriched)

The full display content lives in the top-level custom keys, and aps sets mutable-content: 1 so your Notification Service Extension can enrich/replace the banner (attach the image, adjust text) before it is shown. See the Custom example above.

iOS keeps aps.alert in both modes on purpose. Unlike Android, iOS will not show anything on the lock screen from your custom keys alone — a visible push requires an aps.alert, and a pure silent (content-available-only) push is throttled when the device is locked. So in Custom mode Zixflow still sends a minimal aps.alert plus mutable-content: 1, and your NSE reads the top-level keys to enrich the banner and to track delivery. This is why iOS Custom mode isn’t fully “data-only” the way Android’s is.

This whole object — aps plus every custom key next to it — is exactly what your app receives as userInfo in willPresent, didReceive response:, or the NSE’s didReceive(_:withContentHandler:).

Sound: aps.sound does include the extension (notification_tone.caf — must be bundled; .caf, .aiff, or .wav).

Complete Key Reference

Key	APNs location	Read by	Purpose
`Zixflow-Delivery-ID`	top-level (both modes)	Your app	Unique delivery record ID — required for `trackMetric()`.
`Zixflow-Delivery-Token`	top-level (both modes)	Your app	The APNs token this delivery was sent to.
`title`	Native: `aps.alert.title` · Custom: `aps.alert.title` + top-level `title`	OS / NSE	Notification headline.
`body`	Native: `aps.alert.body` · Custom: `aps.alert.body` + top-level `body`	OS / NSE	Notification text.
`image_url`	top-level `image_url` (Custom)	Your NSE	Rich image — requires an NSE to attach.
`large_icon_url`	top-level (Custom)	N/A on iOS	No APNs equivalent — ignored.
`deeplink_url`	top-level (both modes)	Your app	Where to navigate when the notification body is tapped.
`action_buttons`	top-level (JSON string, both modes)	Your app	Array of `{name, deeplink}` — always a JSON-encoded string. Buttons still need a pre-registered category.
`sound`	`aps.sound`	OS	Custom sound. Extension required.
`badge`	`aps.badge` (int)	OS	App icon badge count.
`sticky`	N/A	N/A	No iOS equivalent.
`notif_id`	top-level	Diagnostic only	Internal send-job ID — not the same as `Zixflow-Delivery-ID`.
`template_id`	top-level (both modes)	Your app / NSE	Dashboard template ID. See Template-Based Custom Rendering.
`workspace_id`	top-level	Diagnostic only	Which workspace sent this.

Field Support Summary: Native vs. Custom-Handled

Field	Native (OS-rendered) support
Title / body / sound / badge	Fully supported via `aps`.
`image_url`	Requires Custom + NSE (`mutable-content: 1`).
`large_icon_url`	Not supported on iOS.
`sticky`	Not supported on iOS.
`action_buttons`	Not supported without a pre-registered `UNNotificationCategory` and Custom handling.
`template_id`	Not a rendering field. Your NSE/app uses it to pick a custom renderer.

Template-Based Custom Rendering (`template_id`)

Every push sent from a dashboard template includes template_id (both modes). On iOS, template-based customization happens in the Notification Service Extension — the only place the app can mutate the notification content before it’s shown, including while the device is locked. Most template fields (large_icon_url, sticky, action_buttons) have no client-side equivalent on iOS, so the example below applies the one that does — badge:

// NotificationService.swift
private let exampleTemplateId = "469935" // swap in your own template's ID

override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    self.contentHandler = contentHandler
    let content = (request.content.mutableCopy() as? UNMutableNotificationContent) ?? UNMutableNotificationContent()
    bestAttemptContent = content

    if let templateId = request.content.userInfo["template_id"] as? String, templateId == exampleTemplateId {
        applyTemplateExampleCustomization(to: content, userInfo: request.content.userInfo)
    }
    // ...generic image-attachment logic continues here
}

private func applyTemplateExampleCustomization(to content: UNMutableNotificationContent, userInfo: [AnyHashable: Any]) {
    if let badgeString = userInfo["badge"] as? String, let badgeValue = Int(badgeString) {
        content.badge = NSNumber(value: badgeValue)
    }
}

willPresent can also read userInfo["template_id"] for diagnostic logging while the app is in the foreground — but the NSE is what actually runs the customization on the lock screen.

Complete Field Mapping Reference (Custom-Handled UI)

The NSE example below attaches the official image_url field. sticky and large_icon_url have no iOS equivalent.

// NotificationService.swift — the ONLY way to get image_url customization beyond what aps.* already carries.
final class NotificationService: UNNotificationServiceExtension {
    private var contentHandler: ((UNNotificationContent) -> Void)?
    private var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.contentHandler = contentHandler
        let content = (request.content.mutableCopy() as? UNMutableNotificationContent) ?? UNMutableNotificationContent()
        bestAttemptContent = content

        // aps.badge / aps.sound / aps.category are already applied by the OS before this runs —
        // this extension's only job is attaching the image (badge/sound/buttons need no extra code).
        guard let imageURLString = request.content.userInfo["image_url"] as? String,
              let url = URL(string: imageURLString) else {
            contentHandler(content); return
        }
        URLSession.shared.downloadTask(with: url) { location, _, _ in
            defer { self.contentHandler?(content) }
            guard let location else { return }
            let tmp = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString).appendingPathExtension("jpg")
            guard (try? FileManager.default.moveItem(at: location, to: tmp)) != nil,
                  let attachment = try? UNNotificationAttachment(identifier: "image", url: tmp, options: nil) else { return }
            content.attachments = [attachment]
        }.resume()
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler, let bestAttemptContent { contentHandler(bestAttemptContent) }
    }
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void) {
    guard response.actionIdentifier == UNNotificationDefaultActionIdentifier else { completionHandler(); return }
    let userInfo = response.notification.request.content.userInfo
    let clickAction = userInfo["click_action"] as? String
    // Resolves "OPEN_SALE"/"OPEN_DASHBOARD" tokens to in-app screens, taking priority over
    // deeplink_url — our own convention, since iOS has no native click_action equivalent at all.
    if !NavigationRouter.shared.openClickAction(clickAction) {
        NavigationRouter.shared.open(deeplink: userInfo["deeplink_url"] as? String)
    }
    completionHandler()
}

The Three Tracking Events

Each interaction maps to a specific SDK call. The event name, parameters, and platform code are listed for each below.

Event naming — read this first: trackMetric() used to always send a single generic internal event name, Report Delivery Event, for every metric type (delivered/opened/clicked/converted), with the actual status only distinguishable via an internal metric property. The SDK now sends the metric name itself as the event name — Delivered, Opened, Clicked — so each lifecycle stage is directly filterable/reportable by name in analytics and Journeys, with no code change required on your side (you still call trackMetric(event: .delivered) exactly as before; only the resulting event name on the backend changed). If you have older dashboards/segments filtering on the literal string "Report Delivery Event", update them to filter on "Delivered" / "Opened" / "Clicked" instead. Both old and new names are still recognized by the backend, so nothing breaks during the transition — but new events will use the short-form names going forward.

1. Delivery Confirmed

Event name (sent to Zixflow): 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.

Tracking Delivery When the Device Is Locked

A common gap: Delivered isn’t recorded when the push arrives while the phone is locked or the app is backgrounded. willPresent (foreground) and didReceive (tap) are the only default delegate hooks — neither runs when a banner simply arrives on the lock screen. The fix: add a Notification Service Extension and have Zixflow send mutable-content: 1 (already set in Custom mode). The NSE’s didReceive(_:withContentHandler:) runs the instant the push arrives — even while the device is locked or the app is killed — which is the only client-side hook available on the lock screen. Track Delivered from there. The NSE is a separate target and typically doesn’t link the Zixflow SDK, so track by calling the Zixflow tracking endpoint directly, inside the extension’s ~30s budget:

// NotificationService.swift — runs on push arrival, even when the device is locked.
override func didReceive(_ request: UNNotificationRequest,
                         withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    self.contentHandler = contentHandler
    let content = (request.content.mutableCopy() as? UNMutableNotificationContent) ?? UNMutableNotificationContent()
    bestAttemptContent = content

    let userInfo = request.content.userInfo
    let deliveryId = userInfo["Zixflow-Delivery-ID"] as? String ?? ""
    let deliveryToken = userInfo["Zixflow-Delivery-Token"] as? String ?? ""

    // Fire Delivered on arrival — this is the only lock-screen hook iOS gives you.
    if !deliveryId.isEmpty, !deliveryToken.isEmpty,
       let url = URL(string: "https://events.zixflow.in/v1/track") {
        var req = URLRequest(url: url)
        req.httpMethod = "POST"
        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
        req.setValue("Basic \(ZIXFLOW_WRITE_KEY)", forHTTPHeaderField: "Authorization")
        req.httpBody = try? JSONSerialization.data(withJSONObject: [
            "event": "Push Notification Delivered",
            "properties": [
                "Zixflow-Delivery-ID": deliveryId,
                "Zixflow-Delivery-Token": deliveryToken,
            ],
        ])
        URLSession.shared.dataTask(with: req).resume()
    }

    // ...then attach the image and call contentHandler(content) as usual.
}

Note on credentials: the NSE calls the tracking HTTP API with a write-only key, never a service-account or admin credential. Scope the key to event ingestion only.

2. Notification Opened

Event name (sent to Zixflow): 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 is a JSON-encoded string of {name, deeplink} objects. You must parse it before use. On iOS, buttons still require a pre-registered UNNotificationCategory (ZX_2BTN with ACTION_0 / ACTION_1) — the payload cannot register categories by itself. 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

Sticky is an optional custom-data key some Android apps define. There is no iOS/APNs equivalent. Ignore it 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 may carry a deeplink_url at the top level and per-button deeplinks in action_buttons. Your app is responsible for routing these. Sample-app priority on tap:

Action button → that button’s deeplink
Body tap → deeplink_url
Neither set → default screen

click_action: FCM android.notification.click_action needs a matching <intent-filter>. A separate click_action key in custom data is optional — the sample app maps "OPEN_SALE" / "OPEN_DASHBOARD" ahead of deeplink_url. iOS has no native click_action.

// 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 (Delivered, Opened, Push Notification Action Clicked) are reserved for Zixflow’s delivery pipeline only when their properties actually carry a Zixflow delivery identifier — the backend checks for Zixflow-Delivery-ID before treating it as a delivery report. If you send a custom event named exactly Delivered, Opened, or Clicked with no delivery identifier, it is stored as a normal profile event. When a Zixflow-originated push tracking call is correctly matched, its event is not stored as a user profile event. If you want to track a non-Zixflow push for your own analytics, use a custom event name instead.

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

Two Ways to Handle a Zixflow Push — and Why Tracking Is Required in Both

The Delivery Lifecycle at a Glance

The Push Payload

How to handle and show push notifications sent by Zixflow

APNs (iOS) Wire Format

Mode 1 — Native (OS-rendered)

Mode 2 — Custom (app-enriched)

Complete Key Reference

Field Support Summary: Native vs. Custom-Handled

Template-Based Custom Rendering (`template_id`)

Complete Field Mapping Reference (Custom-Handled UI)

The Three Tracking Events

1. Delivery Confirmed

Tracking Delivery When the Device Is Locked

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

​Two Ways to Handle a Zixflow Push — and Why Tracking Is Required in Both

​The Delivery Lifecycle at a Glance

​The Push Payload

​How to handle and show push notifications sent by Zixflow

​APNs (iOS) Wire Format

​Mode 1 — Native (OS-rendered)

​Mode 2 — Custom (app-enriched)

​Complete Key Reference

​Field Support Summary: Native vs. Custom-Handled

​Template-Based Custom Rendering (template_id)

​Complete Field Mapping Reference (Custom-Handled UI)

​The Three Tracking Events

​1. Delivery Confirmed

​Tracking Delivery When the Device Is Locked

​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

Two Ways to Handle a Zixflow Push — and Why Tracking Is Required in Both

The Delivery Lifecycle at a Glance

The Push Payload

How to handle and show push notifications sent by Zixflow

APNs (iOS) Wire Format

Mode 1 — Native (OS-rendered)

Mode 2 — Custom (app-enriched)

Complete Key Reference

Field Support Summary: Native vs. Custom-Handled

Template-Based Custom Rendering (`template_id`)

Complete Field Mapping Reference (Custom-Handled UI)

The Three Tracking Events

1. Delivery Confirmed

Tracking Delivery When the Device Is Locked

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