Push Notifications

Complete guide to implementing push notifications with Zixflow using Apple Push Notifications (APNs) or Firebase Cloud Messaging (FCM).

Track your campaigns: With autoTrackPushEvents(true), the SDK tracks body opened (default action). Action-button taps are not auto-tracked — handle them in UNUserNotificationCenterDelegate. Delivered metrics typically need a Notification Service Extension. See Push Notification Tracking. Reference: sdk-examples/ios.

Prerequisites

Add push credentials (APNs or FCM) in the Zixflow dashboard
Enable Push Notifications capability in Xcode
Install the push module:
- ZixflowMessagingPushAPN for APNs
- ZixflowMessagingPushFCM for FCM

Test on a physical device — the simulator cannot receive remote push.

Apple Push Notifications (APNs)

Step 1: Enable Push Notifications in Xcode

Select your project in Xcode
Go to Target → Signing & Capabilities
Click + Capability → Push Notifications
Click + Capability → Background Modes → enable Remote notifications

Step 2: Initialize core SDK and MessagingPushAPN

Match the iOS example: plain AppDelegate + UNUserNotificationCenterDelegate for action buttons.

import UIKit
import UserNotifications
import ZixflowDataPipelines
import ZixflowMessagingPushAPN

class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let config = SDKConfigBuilder(apiKey: "YOUR_API_KEY")
            .autoTrackDeviceAttributes(true)
            .trackApplicationLifecycleEvents(true)
            .logLevel(.debug)
            .build()

        Zixflow.initialize(withConfig: config)

        MessagingPushAPN.initialize(
            withConfig: MessagingPushConfigBuilder()
                .autoFetchDeviceToken(true)
                .autoTrackPushEvents(true)
                .showPushAppInForeground(true)
                .build()
        )

        registerPushActionCategories()
        UNUserNotificationCenter.current().delegate = self

        return true
    }

    // Register ZX_2BTN — see Custom Action Buttons below
    // Implement didReceive for ACTION_0 / ACTION_1 — see Push Notification Tracking
}

With autoTrackPushEvents(true), body taps (UNNotificationDefaultActionIdentifier) are tracked as Opened. Action-button taps still need your didReceive handler.

MessagingPushConfigBuilder options

Option	Type	Default	Description
`autoFetchDeviceToken`	Bool	`true`	Automatically register the device token
`autoTrackPushEvents`	Bool	`true`	Track delivery (with NSE) and body opened
`showPushAppInForeground`	Bool	`true`	Show pushes while the app is active
`appGroupId`	String?	`nil`	App Group for NSE delivery tracking (auto-infers `group.{bundleId}.zixflow` if omitted)
`logLevel`	ZixflowLogLevel	`.error`	Logging for the push module

Step 3: Identify users

Device tokens are associated with a profile when you call identify():

Zixflow.shared.identify(
    userId: "user@example.com",
    traits: ["email": "user@example.com"]
)

Step 4: Rich push with Notification Service Extension

File → New → Target → Notification Service Extension
Add ZixflowMessagingPushAPN to the extension target
Share an App Group between the app and extension (group.{bundleId}.zixflow)

CocoaPods extension target:

target 'NotificationServiceExtension' do
  use_frameworks!
  pod 'ZixflowMessagingPushAPN', '~> 1.1'
end

NotificationService.swift:

import UserNotifications
import ZixflowMessagingPushAPN

class NotificationService: UNNotificationServiceExtension {
    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        MessagingPushAPN.initializeForExtension(
            withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_API_KEY")
                .logLevel(.debug)
                .appGroupId("group.com.yourcompany.app.zixflow")
                .build()
        )

        MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
    }

    override func serviceExtensionTimeWillExpire() {
        MessagingPush.shared.serviceExtensionTimeWillExpire()
    }
}

Set the same appGroupId when initializing push in the main app:

MessagingPushAPN.initialize(
    withConfig: MessagingPushConfigBuilder()
        .appGroupId("group.com.yourcompany.app.zixflow")
        .build()
)

Step 5: Manual device token registration (optional)

If you disable autoFetchDeviceToken, forward the APNs token via MessagingPush.shared:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    MessagingPush.shared.registerDeviceToken(apnDeviceToken: deviceToken)
}

func application(
    _ application: UIApplication,
    didFailToRegisterForRemoteNotificationsWithError error: Error
) {
    MessagingPush.shared.deleteDeviceToken()
}

Firebase Cloud Messaging (FCM)

Step 1: Firebase project

Create/select a project in the Firebase console
Add your iOS app and download GoogleService-Info.plist into the Xcode project

Step 2: Install dependencies

platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'ZixflowDataPipelines', '~> 1.1'
  pod 'ZixflowMessagingPushFCM', '~> 1.1'
  pod 'FirebaseMessaging', '~> 10.0'
end

Step 3: Initialize Firebase, Zixflow, and push

Configure Firebase first, then initialize Zixflow and the push module. Forward FCM registration tokens to Zixflow:

import UIKit
import FirebaseCore
import FirebaseMessaging
import ZixflowDataPipelines
import ZixflowMessagingPushFCM

@main
class AppDelegate: UIResponder, UIApplicationDelegate, MessagingDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        FirebaseApp.configure()

        let config = SDKConfigBuilder(apiKey: "YOUR_API_KEY")
            .logLevel(.debug)
            .deepLinkCallback { url in
                print("Deep link: \(url)")
                return true
            }
            .build()
        Zixflow.initialize(withConfig: config)

        MessagingPush.initialize(
            withConfig: MessagingPushConfigBuilder()
                .autoFetchDeviceToken(true)
                .autoTrackPushEvents(true)
                .showPushAppInForeground(true)
                .build()
        )

        Messaging.messaging().delegate = self
        return true
    }

    func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
        MessagingPush.shared.registerDeviceToken(fcmToken: fcmToken)
    }
}

Advanced: MessagingPushFCM.internalSetup(withConfig:firebaseService:) accepts a FirebaseService adapter for automatic APNs↔FCM token bridging. Most apps can use MessagingPush.initialize plus registerDeviceToken(fcmToken:) as shown above.

Step 4: FCM Notification Service Extension

import UserNotifications
import ZixflowMessagingPushFCM

class NotificationService: UNNotificationServiceExtension {
    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        MessagingPushFCM.initializeForExtension(
            withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_API_KEY")
                .logLevel(.debug)
                .appGroupId("group.com.yourcompany.app.zixflow")
                .build()
        )

        MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
    }

    override func serviceExtensionTimeWillExpire() {
        MessagingPush.shared.serviceExtensionTimeWillExpire()
    }
}

Deep links

Body / campaign deep links appear as deeplink_url (and sometimes ZIXFLOW.push.link). The iOS example opens them from UNUserNotificationCenterDelegate:

Interaction	Tracking	Deeplink
Body tap	Auto Opened when `autoTrackPushEvents(true)`	Read `deeplink_url` → `NavigationRouter` or `UIApplication.shared.open`
Action tap	Manual Opened + `Push Notification Action Clicked`	Read `action_buttons[].deeplink` → 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)
    }
}

Optional: SDKConfigBuilder.deepLinkCallback for other SDK-forwarded URLs. Full property contract and action sample: Push Notification Tracking.

Custom Action Buttons

Named action buttons in a push payload are not registered by the SDK. Your app must pre-register a notification category at launch; Zixflow campaigns that include buttons use category ZX_2BTN with action identifiers ACTION_0 and ACTION_1.

Payload format

The action_buttons field is a JSON-encoded 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": "" }
]

Register `ZX_2BTN` at launch

import UserNotifications

// In application(_:didFinishLaunchingWithOptions:)
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])

Rules:

Maximum 2 buttons per notification (iOS system limit)
Button index is 0-based (leftmost = index 0)
Pre-registered titles can be generic (Action 1, Action 2); campaign button names are tracked via action_name
deeplink may be empty — handle that case in your navigation code
The SDK does not auto-register categories — the app must call setNotificationCategories

For open + action-click tracking (including property names), see Push Notification Tracking.

Manual metrics

Body opens are covered by autoTrackPushEvents(true). For action buttons (and any custom path), call:

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

Read delivery fields from Zixflow-Delivery-ID / ZIXFLOW-Delivery-ID and the matching token keys. See Push Notification Tracking.

Delete device token

MessagingPush.shared.deleteDeviceToken()
// or
Zixflow.shared.deleteDeviceToken()

Troubleshooting

Issue	Check
No pushes	Physical device; Push capability; dashboard credentials; user `identify()` called
No rich media / delivery metrics	NSE installed; App Groups match; `mutable-content: 1` in payload
Deep links not opening	Route `deeplink_url` / action `deeplink` in `didReceive`; confirm payload fields

Enable .logLevel(.debug) while integrating.

Getting Started

Features

Advanced

Reference

Prerequisites

Apple Push Notifications (APNs)

Step 1: Enable Push Notifications in Xcode

Step 2: Initialize core SDK and MessagingPushAPN

MessagingPushConfigBuilder options

Step 3: Identify users

Step 4: Rich push with Notification Service Extension

Step 5: Manual device token registration (optional)

Firebase Cloud Messaging (FCM)

Step 1: Firebase project

Step 2: Install dependencies

Step 3: Initialize Firebase, Zixflow, and push

Step 4: FCM Notification Service Extension

Deep links

Custom Action Buttons

Payload format

Register `ZX_2BTN` at launch

Manual metrics

Delete device token

Troubleshooting

​Prerequisites

​Apple Push Notifications (APNs)

​Step 1: Enable Push Notifications in Xcode

​Step 2: Initialize core SDK and MessagingPushAPN

MessagingPushConfigBuilder options

​Step 3: Identify users

​Step 4: Rich push with Notification Service Extension

​Step 5: Manual device token registration (optional)

​Firebase Cloud Messaging (FCM)

​Step 1: Firebase project

​Step 2: Install dependencies

​Step 3: Initialize Firebase, Zixflow, and push

​Step 4: FCM Notification Service Extension

​Deep links

​Custom Action Buttons

​Payload format

​Register ZX_2BTN at launch

​Manual metrics

​Delete device token

​Troubleshooting

Prerequisites

Apple Push Notifications (APNs)

Step 1: Enable Push Notifications in Xcode

Step 2: Initialize core SDK and MessagingPushAPN

Step 3: Identify users

Step 4: Rich push with Notification Service Extension

Step 5: Manual device token registration (optional)

Firebase Cloud Messaging (FCM)

Step 1: Firebase project

Step 2: Install dependencies

Step 3: Initialize Firebase, Zixflow, and push

Step 4: FCM Notification Service Extension

Deep links

Custom Action Buttons

Payload format

Register `ZX_2BTN` at launch

Manual metrics

Delete device token

Troubleshooting