Push Notification Tracking

Zixflow tracks push notification delivery and engagement so you can measure campaign performance.

Lifecycle events

Metric	When
Delivered (`.delivered`)	Notification arrives — typically via Notification Service Extension
Opened (`.opened`)	User taps the notification body (`UNNotificationDefaultActionIdentifier`)
Action Button Clicked	User taps `ACTION_0` / `ACTION_1` — track Opened manually, then `Push Notification Action Clicked`
Converted (`.converted`)	Optional post-open conversion via `trackMetric`

With autoTrackPushEvents(true) (as in the iOS example):

Body opens are auto-tracked
Action-button taps are not treated as opens — the SDK only auto-opens on the default action
Delivered is reliable when you add an NSE + App Groups; the example focuses on action buttons and does not ship an NSE

Payload fields

Field	Purpose
`Zixflow-Delivery-ID` / `ZIXFLOW-Delivery-ID`	Unique delivery ID
`Zixflow-Delivery-Token` / `ZIXFLOW-Delivery-Token`	Device token for this send
`action_buttons`	JSON string of button `{ name, deeplink }`
`ZIXFLOW.push.link` / `deeplink_url`	Optional body deep link
`ZIXFLOW.push.image` / `image_url`	Optional rich image

Accept both delivery-key casings when reading userInfo.

Delivery tracking (Notification Service Extension)

The example app does not include an NSE. For rich push and reliable delivered metrics:

MessagingPushAPN.initializeForExtension(
    withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_API_KEY")
        .appGroupId("group.com.yourcompany.app.zixflow")
        .build()
)
MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)

Share an App Group between the main app and extension; pass the same .appGroupId(...).

Open tracking (body)

With autoTrackPushEvents(true), body taps are tracked automatically. You do not need a wrapper for that path. If you disable auto-track, call:

MessagingPush.shared.trackMetric(
    deliveryID: deliveryId,
    event: .opened,
    deviceToken: deliveryToken
)

Action Button Clicked

Handle only ACTION_0 / ACTION_1 in didReceive (match the example):

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let actionId = response.actionIdentifier
    guard actionId == "ACTION_0" || actionId == "ACTION_1" else {
        completionHandler()
        return
    }

    let userInfo = response.notification.request.content.userInfo
    let deliveryId = deliveryValue(from: userInfo, keys: ["ZIXFLOW-Delivery-ID", "Zixflow-Delivery-ID"])
    let deliveryToken = deliveryValue(from: userInfo, keys: ["ZIXFLOW-Delivery-Token", "Zixflow-Delivery-Token"])

    if !deliveryId.isEmpty && !deliveryToken.isEmpty {
        MessagingPush.shared.trackMetric(
            deliveryID: deliveryId,
            event: .opened,
            deviceToken: deliveryToken
        )
    }

    let actionIndex = Int(actionId.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.shared.track(
        name: "Push Notification Action Clicked",
        properties: [
            "Zixflow-Delivery-ID": deliveryId,
            "Zixflow-Delivery-Token": deliveryToken,
            "action_index": actionIndex,
            "action_name": actionName,
            "action_deeplink": deeplink,
        ]
    )

    if !deeplink.isEmpty, let url = URL(string: deeplink) {
        UIApplication.shared.open(url)
    }

    completionHandler()
}

Register ZX_2BTN at launch — see Push Notifications. Required properties: Zixflow-Delivery-ID, action_index, action_name. Recommended: Zixflow-Delivery-Token, action_deeplink.

Deeplink opening (example pattern)

The iOS example does not rely on deepLinkCallback for campaign taps. It reads deeplink_url / button deeplink in UNUserNotificationCenterDelegate and routes through NavigationRouter:

Source	Field	Tracking	Navigation
Body tap (`UNNotificationDefaultActionIdentifier`)	`deeplink_url`	SDK auto Opened (`autoTrackPushEvents(true)`)	`NavigationRouter` → else `UIApplication.shared.open`
Action tap (`ACTION_0` / `ACTION_1`)	`action_buttons[].deeplink`	Manual Opened + `Push Notification Action Clicked`	Same router

// Body tap — Opened is auto-tracked; only route the deeplink
if actionId == UNNotificationDefaultActionIdentifier {
    let deeplink = userInfo["deeplink_url"] as? String ?? ""
    if !NavigationRouter.shared.open(deeplink: deeplink),
       !deeplink.isEmpty, let url = URL(string: deeplink) {
        UIApplication.shared.open(url)
    }
}

final class NavigationRouter: ObservableObject {
    static let shared = NavigationRouter()
    @Published var activeScreen: Screen? // .sale / .dashboard

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

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

After action tracking, use the same pattern with the button deeplink (empty string is allowed — skip open). You can still set SDKConfigBuilder.deepLinkCallback for other SDK-forwarded links; the example’s push interaction path uses the router above.

App Groups checklist (for NSE / delivered)

Enable App Groups on the main app and Notification Service Extension
Use the same group ID
Pass it via .appGroupId(...) in main-app and extension push config

Non-Zixflow pushes

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

Testing

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

Getting Started

Features

Advanced

Reference

Push Notification Tracking

Lifecycle events

Payload fields

Delivery tracking (Notification Service Extension)

Open tracking (body)

Action Button Clicked

Deeplink opening (example pattern)

App Groups checklist (for NSE / delivered)

Non-Zixflow pushes

Testing

​Lifecycle events

​Payload fields

​Delivery tracking (Notification Service Extension)

​Open tracking (body)

​Action Button Clicked

​Deeplink opening (example pattern)

​App Groups checklist (for NSE / delivered)

​Non-Zixflow pushes

​Testing

Lifecycle events

Payload fields

Delivery tracking (Notification Service Extension)

Open tracking (body)

Action Button Clicked

Deeplink opening (example pattern)

App Groups checklist (for NSE / delivered)

Non-Zixflow pushes

Testing