Push Notification Tracking

Last Updated: July 2, 2026
Audience: Client developers integrating Zixflow SDK (React Native)
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 src/pushHandlers.ts.

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 can be Native or Custom in the dashboard — that choice decides the payload shape (see The Push Payload).

Native: display content lives in FCM notification / APNs aps.alert; data has tracking + routing keys (Zixflow-Delivery-ID, Zixflow-Delivery-Token, deeplink_url, action_buttons, template_id).
Custom: no notification block — the full content is in data.* so your app renders with @notifee/react-native.

	A. Native (OS-rendered)	B. Custom (app-built UI)
Dashboard	Native	Custom
Payload	`notification.*` / `aps.alert` carry title/body/image; `data` = tracking + routing	No native block — `data` is the complete payload
Who shows the banner	Android/iOS	Your app (notifee)
Image / color	Native image + color work with zero app code (verify RN Firebase fallback — some drop `notification.image`)	Fully controllable
Large icon / sticky / action buttons	Not supported on the Native path	Fully controllable (sticky is Android-only)
Tracking	Still required	Same

The one thing both paths share: tracking is never automatic.

Path A (Native, app backgrounded/killed): messaging().onMessage is not invoked for a notification-block push while backgrounded. Track Opened from onNotificationOpenedApp / getInitialNotification. For Delivered on this path, rely on Zixflow’s server-side delivery receipt, or see Tracking Delivery When the Device Is Locked.
Path B (Custom): your code runs the moment the push arrives. Track Delivered immediately, then track Opened / Push Notification Action Clicked from notifee tap handlers.

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

messaging().onMessage(async (message) => {
  const deliveryId = message.data?.['Zixflow-Delivery-ID'] ?? '';
  const deliveryToken = message.data?.['Zixflow-Delivery-Token'] ?? cachedToken ?? '';
  if (deliveryId && deliveryToken) {
    await Zixflow.trackMetric({ deliveryID: deliveryId, deviceToken: deliveryToken, event: MetricEvent.delivered });
  }
  // No notifee.displayNotification() call — see comparison table above.
});

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

A note on @react-native-firebase/messaging and Path A: once the FCM client library is present, it typically installs its own FirebaseMessagingService. Verify the library’s fallback renderer before assuming Path A gives full fidelity for free (some drop notification.image).

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 data payload. trackMetric() requires both.

Field	Example value	Purpose
`Zixflow-Delivery-ID`	`"626533406292836846"`	Unique ID for this delivery
`Zixflow-Delivery-Token`	`"dcFRlDhiRbehM1vg-Lx_yn:..."`	The FCM/APNs token this send used

The rest of the payload depends on the rendering mode chosen in the dashboard:

Native (OS-rendered): display content lives in notification / aps.alert; data carries tracking + routing keys only.
Custom (app-rendered): there is no notification block — the full content is in data.

Example data payload in Custom mode:

{
  "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",
  "large_icon_url": "https://cdn.yourapp.com/icon.png",
  "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 data payload in Native mode (tracking + routing only):

{
  "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 JSON.parse before use.

Prefer message.notification?.title ?? data.title so a single renderer covers Native (foreground) and Custom.

Complete Key Reference

Key	Where to read it	Purpose
`Zixflow-Delivery-ID` / `Zixflow-Delivery-Token`	`message.data` (both modes)	Required for `trackMetric()`.
`title` / `body`	Native: `message.notification` · Custom: `data.title` / `data.body` (`message` is an alias of `body`)	Notification text.
`image_url`	Native: `notification.image` · Custom: `data.image_url`	Big-picture image.
`large_icon_url`	`data.large_icon_url` (Custom)	Small avatar — Custom path only.
`deeplink_url`	`data.deeplink_url` (both modes)	Body-tap navigation.
`action_buttons`	`data.action_buttons` (JSON string, both modes)	Up to 2 `{name, deeplink}` buttons. Custom path only to render.
`sound` / `badge` / `sticky` / `icon` / `color`	Native: platform blocks · Custom: matching `data.*` keys	Sticky is Android-only.
`notif_id`	`data.notif_id`	Diagnostic send-job ID.
`template_id`	`data.template_id` (both modes)	Dashboard template ID — see Template-Based Custom Rendering.
`workspace_id`	`data.workspace_id`	Diagnostic workspace ID.

Demo-only sample-app conventions (not official schema): data.priority, data.analytics_label, data.ttl_seconds.

Field Support Summary: Native (OS-Rendered) vs. Custom-Handled

Field	Native (OS-rendered) support
`image_url` / `notification.image`	Fully supported on stock FCM. Some RN Firebase fallbacks drop the image.
`color`	Fully supported on Android.
`sticky`	Not supported on Native. Custom path only. Android-only.
`large_icon_url`	Not supported on Native.
`action_buttons`	Not supported on Native — always requires Custom handling (notifee).
`template_id`	Not a rendering field. Your app uses it to pick a custom renderer.

Template-Based Custom Rendering (`template_id`)

Every push sent from a dashboard template includes data.template_id. Map known IDs to a dedicated renderer and fall back to the generic field-driven builder.

// pushHandlers.ts
const EXAMPLE_TEMPLATE_ID = '469935'; // swap in your own template's ID

async function showNotification(message: FirebaseMessagingTypes.RemoteMessage) {
  const data = sanitizeNotificationData(message.data ?? {});
  const title = message.notification?.title ?? getStringField(data, 'title') ?? 'Notification';
  const body = message.notification?.body ?? getStringField(data, 'body') ?? '';

  if (getStringField(data, 'template_id') === EXAMPLE_TEMPLATE_ID) {
    await showTemplateExampleNotification(data, title, body);
    return;
  }
  // ...generic field-driven notification building continues here
}

async function showTemplateExampleNotification(data: NotificationData, title: string, body: string) {
  const soundName = getStringField(data, 'sound');
  const imageUrl = getStringField(data, 'image_url');
  const largeIconUrl = getStringField(data, 'large_icon_url');
  await notifee.displayNotification({
    title, body, data,
    android: {
      channelId: 'zixflow_template_example',
      smallIcon: 'ic_notification',
      pressAction: { id: 'default' },
      actions: buildNotifeeActions(data),
      ongoing: getStringField(data, 'sticky') === 'true',
      ...(largeIconUrl ? { largeIcon: largeIconUrl } : {}),
      ...(imageUrl ? { style: { type: AndroidStyle.BIGPICTURE, picture: imageUrl } } : {}),
      ...(soundName ? { sound: soundName } : {}),
    },
    ios: { categoryId: 'ZX_2BTN' },
  });
}

Complete Field Mapping Reference (Custom-Handled UI)

One consolidated builder covering every official field from the Complete Key Reference. Combine with the tracking calls from The Three Tracking Events. Matches sdk-examples/react-native.

async function showZixflowNotification(data: Record<string, string>) {
  const title = data.title ?? 'Notification';
  const body = data.body ?? data.message ?? '';
  const badgeCount = data.badge ? Number.parseInt(data.badge, 10) : undefined;
  const soundName = data.sound && data.sound !== 'default' && data.sound !== 'none' ? data.sound : undefined;
  const sticky = data.sticky === 'true' || data.sticky === 'until_click' || data.sticky === 'ongoing';
  const buttons = parseActionButtons(data.action_buttons);

  const priority = data.priority;
  const channelId = priority === 'normal' ? 'zixflow_normal' : 'zixflow_default';

  if (badgeCount != null) await notifee.setBadgeCount(badgeCount);

  await notifee.displayNotification({
    title,
    body,
    data,
    android: {
      channelId,
      smallIcon: 'ic_notification',
      color: '#FA2438',
      importance: priority === 'normal' ? AndroidImportance.DEFAULT : AndroidImportance.HIGH,
      pressAction: { id: 'default' },
      autoCancel: true,
      ongoing: sticky,
      actions: buttons.slice(0, 2).map((b, i) => ({ title: b.name || `Action ${i + 1}`, pressAction: { id: `action_${i}` } })),
      ...(isValidImageUrl(data.large_icon_url) ? { largeIcon: data.large_icon_url } : {}),
      ...(isValidImageUrl(data.image_url) ? { style: { type: AndroidStyle.BIGPICTURE, picture: data.image_url } } : {}),
      ...(soundName ? { sound: soundName } : {}),
    },
    ios: {
      categoryId: 'ZX_2BTN',
      ...(soundName ? { sound: `${soundName}.caf` } : {}),
      ...(badgeCount != null ? { badgeCount } : {}),
    },
  });

  const ttlSeconds = Number.parseInt(data.ttl_seconds ?? '', 10);
  if (Number.isFinite(ttlSeconds) && ttlSeconds > 0) {
    setTimeout(() => notifee.cancelNotification(String(notificationId)), ttlSeconds * 1000);
  }
}

function resolveClickAction(clickAction?: string): boolean {
  switch (clickAction) {
    case 'OPEN_SALE': navigate('sale'); return true;
    case 'OPEN_DASHBOARD': navigate('dashboard'); return true;
    default: return false;
  }
}

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: MetricEvent.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 onMessage handler.
SDK method: Zixflow.trackMetric({ deliveryID, deviceToken, event: MetricEvent.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 FCM/APNs token)
`event`	✅	`MetricEvent.delivered`

import messaging from '@react-native-firebase/messaging';
import { Zixflow, MetricEvent } from 'zixflow-reactnative';

messaging().onMessage(async remoteMessage => {
  const deliveryId    = remoteMessage.data?.['Zixflow-Delivery-ID'] ?? '';
  const deliveryToken = remoteMessage.data?.['Zixflow-Delivery-Token'] ?? cachedToken ?? '';

  if (deliveryId && deliveryToken) {
    await Zixflow.trackMetric({
      deliveryID:  deliveryId,
      deviceToken: deliveryToken,
      event:       MetricEvent.delivered,
    });
  }
});

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. This is expected default OS behaviour.

Platform	How to reliably track `Delivered` while locked
Android (Custom mode)	Zixflow sends Custom-mode pushes as high-priority data messages (`android.priority: "high"`). Track `Delivered` in `messaging().onMessage` / `setBackgroundMessageHandler`.
Android (Native mode)	The OS renders it and no app code runs on arrival. Use Zixflow’s server-side delivery receipt, and track `Opened` on tap. Switch the campaign to Custom mode if you need client-side `Delivered`.
iOS (either mode)	Add a Notification Service Extension with `mutable-content: 1`. Track `Delivered` from the NSE — see iOS Push Notification Tracking.

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.trackMetric({ deliveryID, deviceToken, event: MetricEvent.opened })
What happens: Zixflow updates the campaign delivery record to opened. 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
`event`	✅	`MetricEvent.opened`

import messaging from '@react-native-firebase/messaging';
import { Zixflow, MetricEvent } from 'zixflow-reactnative';

// Background / quit tap
messaging().onNotificationOpenedApp(async remoteMessage => {
  const deliveryId    = remoteMessage.data?.['Zixflow-Delivery-ID'] ?? '';
  const deliveryToken = remoteMessage.data?.['Zixflow-Delivery-Token'] ?? cachedToken ?? '';

  if (deliveryId && deliveryToken) {
    await Zixflow.trackMetric({ deliveryID: deliveryId, deviceToken: deliveryToken, event: MetricEvent.opened });
  }
});

// Terminated tap
const initial = await messaging().getInitialNotification();
if (initial) {
  const deliveryId    = initial.data?.['Zixflow-Delivery-ID'] ?? '';
  const deliveryToken = initial.data?.['Zixflow-Delivery-Token'] ?? cachedToken ?? '';

  if (deliveryId && deliveryToken) {
    await Zixflow.trackMetric({ deliveryID: deliveryId, deviceToken: deliveryToken, event: MetricEvent.opened });
  }
}

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.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"`

import { Zixflow, MetricEvent } from 'zixflow-reactnative';

async function handleActionPress(data: Record<string, string>, actionId: string) {
  const deliveryId  = data['Zixflow-Delivery-ID'] ?? '';
  const token       = data['Zixflow-Delivery-Token'] ?? '';
  const actionIndex = parseInt(actionId.replace(/\D/g, ''), 10);
  const buttons     = parseButtons(data['action_buttons']);
  const actionName  = buttons[actionIndex]?.name ?? `Action ${actionIndex + 1}`;
  const actionDeep  = buttons[actionIndex]?.deeplink ?? '';

  // Always fire opened first
  await Zixflow.trackMetric({ deliveryID: deliveryId, deviceToken: token, event: MetricEvent.opened });

  // Then fire action clicked
  await Zixflow.track({
    name: 'Push Notification Action Clicked',
    properties: {
      'Zixflow-Delivery-ID':    deliveryId,
      'Zixflow-Delivery-Token': token,
      'action_index':           actionIndex,
      'action_name':            actionName,
      'action_deeplink':        actionDeep,
    },
  });
}

Action Buttons Format

The action_buttons field is a JSON-encoded string of {name, deeplink} objects. Parse it before use. Buttons never render on the Native path — attach them when you display with notifee. 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
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 — use categoryId: 'ZX_2BTN'

Parsing `action_buttons`

interface ActionButton {
  name: string;
  deeplink: string;
}

function parseActionButtons(raw: string | undefined): ActionButton[] {
  if (!raw) return [];
  try {
    const decoded = JSON.parse(raw);
    return (Array.isArray(decoded) ? decoded : []).slice(0, 2);
  } catch {
    return [];
  }
}

Building the Buttons on the Notification (notifee)

// pushHandlers.ts pattern
function buildNotifeeActions(data: Record<string, string | undefined>) {
  const buttons = parseActionButtons(data.action_buttons);
  return buttons.slice(0, 2).map((button, index) => ({
    title: button.name || `Action ${index + 1}`,
    pressAction: { id: `action_${index}` },
  }));
}

await notifee.displayNotification({
  title,
  body,
  data,
  android: {
    channelId: ANDROID_CHANNEL_ID,
    pressAction: { id: 'default' },
    actions: buildNotifeeActions(data),   // ← dynamic buttons attached here
  },
  ios: {
    categoryId: 'ZX_2BTN',   // ← same pre-registered category as native iOS
  },
});

notifee.onForegroundEvent / notifee.onBackgroundEvent’s detail.pressAction.id (e.g. "action_0") is parsed back into an index for tracking.

Handling the Tap (End-to-End)

Platform	Callback	Identifier format	Resolve to index
React Native	`notifee.onForegroundEvent` / `onBackgroundEvent`	`detail.pressAction.id` = `"action_0"` / `"action_1"`	`parseInt(id.replace(/\D/g, ''), 10)`

Important on Android (React Native): pressing an action button does not automatically dismiss the notification — see Sticky Notifications below.

New Notification Layouts

Not Zixflow-defined. Add keys such as style / progress / timer yourself if you want them. Sample-app convention below. Android-only.

`style` — notification layout

`style` value	Layout	Notes
absent	Basic text	Default.
`"big_picture"`	Large expandable image	Uses `image_url`; implicit default whenever `image_url` is present.
`"big_text"`	Forced multi-line expandable text	For long copy with no image.
`"media"`	Media-player style	Combine with `progress` / `max_progress` to show a playback bar.

`progress` — determinate / playback bar

Field	Type	Meaning
`progress`	int (string)	Current value (e.g. `"35"`).
`max_progress`	int (string)	Max value (e.g. `"100"`). Defaults to `100`.
`progress_indeterminate`	`"true"` / `"false"`	Animated indeterminate bar.

`timer` — live countdown chronometer

Field	Type	Meaning
`timer`	`"true"`	Enables the chronometer.
`timer_end_ms`	int (string)	Absolute epoch-millis to count down to.
`timer_duration_ms`	int (string)	Alternative to `timer_end_ms` — counts down `now + duration`.

Example payloads

{
  "style": "media",
  "title": "Keep Watching",
  "body": "Watch 5 eps FREE of this super hit!",
  "large_icon_url": "https://cdn.yourapp.com/poster.png",
  "progress": "35",
  "max_progress": "100",
  "action_buttons": "[{\"name\":\"Play\",\"deeplink\":\"https://yourapp.com/watch\"},{\"name\":\"Later\",\"deeplink\":\"\"}]"
}

{
  "title": "Check-in Reminder",
  "body": "Continue to Claim Free Coins",
  "timer": "true",
  "timer_duration_ms": "3600000",
  "sticky": "until_swipe",
  "action_buttons": "[{\"name\":\"Get Now\",\"deeplink\":\"https://yourapp.com/claim\"}]"
}

Sticky Notifications

data.sticky is an official Custom-mode field. Apply notifee ongoing (or native FLAG_NO_CLEAR) in your builder — Native OS rendering does not honor sticky. Sample-app convention: sticky accepts three values:

`sticky` value	Behaviour	Android flags
absent / `"false"`	Normal — swipe or “Clear all” both dismiss it.	none
`"until_click"` (aliases `"true"`, `"ongoing"`)	Survives swipe and “Clear all”. Only removed on body tap.	`ongoing = true`
`"until_swipe"` (alias `"no_clear"`)	Swipe still dismisses it; “Clear all” will not.	`FLAG_NO_CLEAR`

This is Android-only and only works on the Custom (app-rendered) path. Notifee has no dedicated prop for FLAG_NO_CLEAR — use ongoing for "until_click" and accept the “Clear all” limitation for "until_swipe", or drop to native NotificationCompat for that mode.

const sticky = data.sticky === 'true';

await notifee.displayNotification({
  title,
  body,
  data,
  android: {
    channelId: ANDROID_CHANNEL_ID,
    autoCancel: true,   // always true — body tap always dismisses
    ongoing: sticky,     // true = survives swipe + "Clear all"
  },
});

// In your notifee event handler, after tracking the action click:
if (type === EventType.ACTION_PRESS && detail.pressAction) {
  // Required regardless of `sticky` — action buttons never auto-dismiss on Android.
  if (detail.notification?.id) {
    notifee.cancelNotification(detail.notification.id);
  }
}

Same reasoning as Flutter: React Native’s Zixflow SDK is a thin JS wrapper with no native background message interception, so @react-native-firebase/messaging + notifee is what actually displays the notification in your app code — sticky must be read and applied there.

Deep Link Handling

Every Zixflow push may carry a deeplink_url 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.

// navigation.ts
export function resolveInAppRoute(deeplink?: string): boolean {
  if (!deeplink) return false;
  let url: URL;
  try { url = new URL(deeplink); } catch { return false; }
  if (url.protocol !== 'zixflowdemo:') return false;

  switch (url.hostname) {
    case 'sale':      navigate('Sale');      return true;
    case 'dashboard': navigate('Dashboard'); return true;
    default:          return false;
  }
}

// pushHandlers.ts
import { Linking } from 'react-native';
import { resolveInAppRoute } from './navigation';

function handleDeeplink(url?: string) {
  if (!url) return;
  if (resolveInAppRoute(url)) return;   // handled by one of our own screens
  Linking.openURL(url).catch(() => {}); // fall back to external browser/app
}

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

const config = {
  apiKey: 'YOUR_API_KEY',
  logLevel: ZixflowLogLevel.Debug,
};
await Zixflow.initialize(config);

Dashboard → Messaging → Push Notifications: Sent / Delivered / Opened / Clicked.

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

Complete Key Reference

Field Support Summary: Native (OS-Rendered) 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

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification (notifee)

Handling the Tap (End-to-End)

New Notification Layouts

`style` — notification layout

`progress` — determinate / playback bar

`timer` — live countdown chronometer

Example payloads

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

​Complete Key Reference

​Field Support Summary: Native (OS-Rendered) 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

​Action Buttons Format

​Parsing action_buttons

​Building the Buttons on the Notification (notifee)

​Handling the Tap (End-to-End)

​New Notification Layouts

​style — notification layout

​progress — determinate / playback bar

​timer — live countdown chronometer

​Example payloads

​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

Complete Key Reference

Field Support Summary: Native (OS-Rendered) 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

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification (notifee)

Handling the Tap (End-to-End)

New Notification Layouts

`style` — notification layout

`progress` — determinate / playback bar

`timer` — live countdown chronometer

Example payloads

Sticky Notifications

Deep Link Handling

Decision Flowchart

Fallback Behaviour (No Zixflow-Delivery-ID)

Testing