Push Notification Tracking

Overview

Zixflow tracks push engagement so you can measure campaign performance:

Delivered — notification arrived on the device
Opened — user tapped the notification body (or an action — track opened first)
Action button clicked — user tapped a named action button
Converted (optional) — MetricEvent.Converted after a post-open goal

Integration used by the example app

The React Native example uses @react-native-firebase/messaging + @notifee/react-native for receive/display. You track opened and action clicked in JavaScript. Delivered may still be recorded by the parallel native Zixflow FCM path when present; if you fully own display yourself and need delivered metrics, call trackMetric(Delivered) or forward via Zixflow.pushMessaging.onMessageReceived.

Event	Who tracks (Firebase + notifee path)
Delivered	Native Zixflow FCM service if still installed; otherwise call `trackMetric(Delivered)` or `onMessageReceived`
Opened (body)	Your JS: `messaging().onNotificationOpenedApp` / `getInitialNotification` / notifee `EventType.PRESS` → `trackMetric(Opened)`
Action button	notifee `EventType.ACTION_PRESS` → `trackMetric(Opened)` + `track('Push Notification Action Clicked')`
Converted	Call `trackMetric({ event: MetricEvent.Converted })` when the user completes your goal

Payload fields:

Field	Purpose
`Zixflow-Delivery-ID` (also `ZIXFLOW-Delivery-ID`)	Links to the campaign delivery
`Zixflow-Delivery-Token` (also `ZIXFLOW-Delivery-Token`)	Device token the push was sent to

{
  "Zixflow-Delivery-ID": "626533406292836846",
  "Zixflow-Delivery-Token": "dcFRlDhiRbehM1vg...",
  "title": "Flash Sale",
  "body": "Limited time only",
  "deeplink_url": "https://yourapp.com/sale",
  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]"
}

Opened

Wire both FCM system opens and notifee local taps (as in pushHandlers.ts):

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

function trackOpened(data: Record<string, string | undefined>, cachedToken = '') {
  const deliveryId = data['Zixflow-Delivery-ID'] ?? data['ZIXFLOW-Delivery-ID'] ?? '';
  const deliveryToken =
    data['Zixflow-Delivery-Token'] ??
    data['ZIXFLOW-Delivery-Token'] ??
    cachedToken ??
    '';

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

// System FCM notification (background / killed)
messaging().onNotificationOpenedApp((message) => {
  trackOpened((message.data ?? {}) as Record<string, string>);
  handleDeeplink(message.data?.deeplink_url as string | undefined);
});

const initial = await messaging().getInitialNotification();
if (initial) {
  trackOpened((initial.data ?? {}) as Record<string, string>);
  handleDeeplink(initial.data?.deeplink_url as string | undefined);
}

Action button tracking

Register iOS category ZX_2BTN in AppDelegate (see Push Notifications). When notifee displays the notification, handle presses in JS:

function handleNotifeeEvent(
  type: EventType,
  detail: { notification?: { id?: string; data?: Record<string, string> }; pressAction?: { id: string } },
) {
  const data = (detail.notification?.data ?? {}) as Record<string, string | undefined>;

  if (type === EventType.PRESS) {
    trackOpened(data);
    handleDeeplink(data.deeplink_url);
  } else if (type === EventType.ACTION_PRESS && detail.pressAction) {
    trackOpened(data);
    trackActionClick(data, detail.pressAction.id);
    if (detail.notification?.id) {
      notifee.cancelNotification(detail.notification.id);
    }
  }
}

function trackActionClick(
  data: Record<string, string | undefined>,
  actionId: string,
) {
  const actionIndex = parseInt(String(actionId).replace(/\D/g, ''), 10) || 0;
  const buttons = parseButtons(data.action_buttons);
  const actionName = buttons[actionIndex]?.name ?? `Action ${actionIndex + 1}`;
  const actionDeeplink = buttons[actionIndex]?.deeplink ?? '';

  Zixflow.track('Push Notification Action Clicked', {
    'Zixflow-Delivery-ID': data['Zixflow-Delivery-ID'] ?? '',
    'Zixflow-Delivery-Token': data['Zixflow-Delivery-Token'] ?? '',
    action_index: actionIndex,
    action_name: actionName,
    action_deeplink: actionDeeplink,
    notification_id: data['Zixflow-Delivery-ID'] ?? '',
    title: data.title ?? '',
    action_id: actionId,
    source: 'local_notification',
  });

  handleDeeplink(actionDeeplink || data.deeplink_url);
}

const parseButtons = (raw: any) => {
  if (!raw) return [];
  try {
    return typeof raw === 'string' ? JSON.parse(raw) : raw;
  } catch {
    return [];
  }
};

notifee action ids are action_0 / action_1. You can also use the example helper trackActionClick. Required properties:

Property	Required	Description
`Zixflow-Delivery-ID`	Yes	Campaign delivery
`action_index`	Yes	0-based button index
`action_name`	Yes	Button label
`Zixflow-Delivery-Token`	Recommended	Device token
`action_deeplink`	Recommended	Button URL
`notification_id`, `title`, `action_id`, `source`	Optional	Extra context

Deeplink opening (example pattern)

The React Native example uses navigation.ts for in-app hosts and Linking.openURL for everything else:

Source	Field	After tracking
Body	`deeplink_url`	`handleDeeplink`
Action	button `deeplink`, else `deeplink_url`	`handleDeeplink`

import { Linking } from 'react-native';
import { navigate, resolveInAppRoute } from './navigation';

function handleDeeplink(deeplink?: string) {
  if (!deeplink) return;
  const screen = resolveInAppRoute(deeplink);
  if (screen) {
    navigate(screen); // in-app: zixflowdemo://sale | zixflowdemo://dashboard
    return;
  }
  Linking.openURL(deeplink).catch(() => {});
}

export function resolveInAppRoute(deeplink?: string): 'sale' | 'dashboard' | null {
  if (!deeplink) return null;
  const match = /^zixflowdemo:\/\/(sale|dashboard)\b/i.exec(deeplink);
  if (!match) return null;
  return match[1].toLowerCase() as 'sale' | 'dashboard';
}

Also configure native URL schemes / intent filters if you use a custom scheme (see Deep Links).

Delivered (optional manual)

If you need an explicit delivered event when displaying yourself:

await Zixflow.trackMetric({
  deliveryID: data['Zixflow-Delivery-ID'],
  deviceToken: data['Zixflow-Delivery-Token'] ?? cachedToken,
  event: MetricEvent.Delivered,
});

Or forward to the native Android helper (display and/or track):

await Zixflow.pushMessaging.onMessageReceived(remoteMessage, true);
// true = display + track; false = track only

Avoid double UI: if notifee already displays the notification, do not also call onMessageReceived with handleNotificationTrigger: true. Background helper:

await Zixflow.pushMessaging.onBackgroundMessageReceived(remoteMessage);

Converted

await Zixflow.trackMetric({
  deliveryID: data['Zixflow-Delivery-ID'],
  deviceToken: data['Zixflow-Delivery-Token'] ?? cachedToken,
  event: MetricEvent.Converted,
});

Logout / token cleanup

await Zixflow.deleteDeviceToken();
await Zixflow.clearIdentify();

Decision flowchart

Firebase messaging + notifee display?
├── YES (example path)
│   ├── Display / actions → notifee
│   ├── Opened → trackMetric(Opened) in JS
│   ├── Action → Opened + track("Push Notification Action Clicked") + cancel
│   ├── Deeplink → resolveInAppRoute / Linking.openURL
│   └── Delivered → trackMetric(Delivered) on receive and/or native path
│
└── Forward to Zixflow native display instead
    └── Zixflow.pushMessaging.onMessageReceived(message, true)

Non-Zixflow pushes

If the payload has no Zixflow-Delivery-ID, skip Zixflow push metrics. Do not use reserved names (Push Notification Action Clicked, etc.) for external pushes.

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

Overview

Integration used by the example app

Opened

Action button tracking

Deeplink opening (example pattern)

Delivered (optional manual)

Converted

Logout / token cleanup

Decision flowchart

Non-Zixflow pushes

Testing

​Overview

​Integration used by the example app

​Opened

​Action button tracking

​Deeplink opening (example pattern)

​Delivered (optional manual)

​Converted

​Logout / token cleanup

​Decision flowchart

​Non-Zixflow pushes

​Testing

Overview

Integration used by the example app

Opened

Action button tracking

Deeplink opening (example pattern)

Delivered (optional manual)

Converted

Logout / token cleanup

Decision flowchart

Non-Zixflow pushes

Testing