Push Notification Tracking

Audience: Client developers integrating a Zixflow SDK
Purpose: How to report push delivery, opens, and action clicks so campaign analytics stay accurate. For step-by-step platform code, use the SDK guides:

Why Push Tracking Matters

When Zixflow sends a push, it records the send. Your app must report what happens on the device:

Did it arrive?
Did the user open it?
Did they tap an action button?

Those callbacks power open rates, click rates, and post-push conversion funnels.

Delivery Lifecycle

The Push Payload

Zixflow injects two fields into every push data payload. Use them to associate metrics with the correct delivery.

Field	Example	Purpose
`Zixflow-Delivery-ID`	`"626533406292836846"`	Unique delivery ID
`Zixflow-Delivery-Token`	`"dcFRlDhiRbehM1vg-Lx_yn:..."`	Token the push was sent to

They appear in message.data (Flutter/Android) or userInfo (iOS). trackMetric() requires both. Example payload:

{
  "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\":\"\"}]",
  "notif_id": "626533406292836846"
}

Important: action_buttons is a JSON string, not a nested object. Parse it before use.

The Three Tracking Events

Moment	Event / method	When to fire
1. Delivered	`trackMetric(... delivered)` → `Push Notification Delivered`	Payload arrives (`onMessage` / `willPresent` / `onMessageReceived`)
2. Opened	`trackMetric(... opened)` → `Push Notification Opened`	User taps the notification (body or action). Fire for both.
3. Action clicked	`track('Push Notification Action Clicked', …)`	User taps a specific action button (after opened)

Delivered / Opened parameters

Parameter	Required	Description
`deliveryID`	Yes	`Zixflow-Delivery-ID`
`deviceToken`	Yes	`Zixflow-Delivery-Token` (or cached FCM/APNs token)
`event`	Yes	`MetricEvent.delivered` or `MetricEvent.opened`

Action Clicked properties

Property	Required	Description
`Zixflow-Delivery-ID`	Yes	Links to the delivery
`action_index`	Yes	0-based button index
`action_name`	Yes	Button label (e.g. `"Shop Now"`)
`Zixflow-Delivery-Token`	Recommended	Token used for the send
`action_deeplink`	Recommended	URL for that button

Action clicks use track(), not trackMetric(). Always fire opened first, then the action event.

Minimal Flutter example

// Delivered
Zixflow.instance.trackMetric(
  deliveryID: deliveryId,
  deviceToken: deliveryToken,
  event: MetricEvent.delivered,
);

// Opened
Zixflow.instance.trackMetric(
  deliveryID: deliveryId,
  deviceToken: deliveryToken,
  event: MetricEvent.opened,
);

// Action clicked
Zixflow.instance.track(
  name: 'Push Notification Action Clicked',
  properties: {
    'Zixflow-Delivery-ID': deliveryId,
    'Zixflow-Delivery-Token': deliveryToken,
    'action_index': 0,
    'action_name': 'Shop Now',
    'action_deeplink': 'https://yourapp.com/sale',
  },
);

Full handlers for every platform (foreground, background, terminated, service worker) are in the SDK links at the top of this page.

Action Buttons Format

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

name — button label
deeplink — optional URL; empty string means no navigation

Deep Links

When the user opens a push, navigate using deeplink_url from the payload (or the action’s deeplink). Tracking and navigation are separate: always report metrics even if routing fails.

Decision Flow

Fallback (no Delivery ID)

If Zixflow-Delivery-ID is missing (e.g. a push not sent by Zixflow), do not call trackMetric. You may still show the notification and handle deep links locally.

​Why Push Tracking Matters

​Delivery Lifecycle

​The Push Payload

​The Three Tracking Events

​Delivered / Opened parameters

​Action Clicked properties

​Minimal Flutter example

​Action Buttons Format

​Deep Links

​Decision Flow

​Fallback (no Delivery ID)