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 tracking fields into every push. trackMetric() requires both.

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/RN) or userInfo (iOS). The rest of the payload depends on the dashboard rendering mode:

Native (OS-rendered): display content lives in FCM notification / APNs aps.alert; data (or top-level iOS keys) carries tracking + routing (deeplink_url, action_buttons, template_id, notif_id, workspace_id).
Custom (app-rendered): no notification block — title, body, image, sticky, and other display keys live in data.

Custom data example:

{
  "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\"}]",
  "template_id": "469935"
}

Use template_id to branch to a template-specific renderer. Full key reference and Native vs Custom wire format: Android · iOS · Flutter.

The Three Tracking Events

Event naming — read this first: trackMetric() used to always send a single generic internal event name, Report Delivery Event, for every metric type. 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. You still call trackMetric(event: MetricEvent.delivered) exactly as before; only the resulting event name on the backend changed. If you have older dashboards/segments filtering on "Report Delivery Event", update them to filter on "Delivered" / "Opened" / "Clicked" instead. Both old and new names are still recognized by the backend.

Moment	Event / method	When to fire
1. Delivered	`trackMetric(... delivered)` → `Delivered`	Payload arrives (`onMessage` / `willPresent` / `onMessageReceived`)
2. Opened	`trackMetric(... opened)` → `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

Not a Zixflow-defined field. If you add buttons in custom data, one convention is a JSON array of {name, deeplink}:

[
  { "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

Zixflow sends deeplink_url for body taps and per-button deeplink values inside action_buttons. Route them in your app. Tracking and navigation are separate: always report metrics even if routing fails. FCM click_action is a platform field that needs a matching <intent-filter> on the Native path. Sample apps may also read data.click_action tokens (OPEN_SALE / OPEN_DASHBOARD) for in-app routing, taking priority over deeplink_url.

Decision Flow

Fallback (no Delivery ID)

If Zixflow-Delivery-ID is missing (e.g. a push not sent by Zixflow), do not call trackMetric. Reserved names (Delivered, Opened, Push Notification Action Clicked) are only treated as delivery reports when properties include a Zixflow delivery identifier. 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)