Push Notification Tracking

Last Updated: July 2, 2026
Audience: Client developers integrating Zixflow SDK (Web)
Purpose: Track push notification lifecycle events — delivery, open, and action clicks — so Zixflow can measure campaign performance accurately. See also: Web Push Notifications and the reference implementation sw.js.

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.

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.

Note: trackMetric is not available in a service worker context — call the Zixflow HTTP API directly from your service worker.

The Push Payload

Zixflow injects two special fields into every web-push JSON body. Your service worker uses these to associate the tracking event with the correct campaign delivery.

Field	Example value	Purpose
`Zixflow-Delivery-ID`	`"626533406292836846"`	Unique ID for this delivery
`Zixflow-Delivery-Token`	`"dcFRlDhiRbehM1vg-Lx_yn:..."`	The push subscription endpoint

The rest of the payload is the same official schema used on mobile Custom mode — display and routing keys live in the JSON body your service worker receives:

{
  "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",
  "template_id": "469935",
  "workspace_id": "68be4f797a6494676161e98b"
}

Important: action_buttons is a JSON string (not a nested object). Parse it before passing to showNotification({ actions }). There is no dashboard field named data.actions.

Complete Key Reference (web)

Key	Purpose
`Zixflow-Delivery-ID` / `Zixflow-Delivery-Token`	Required for delivery/open tracking from the service worker.
`title` / `body`	Notification text (`body` may also appear as `message`).
`image_url`	Icon / image.
`deeplink_url`	URL to open on body tap.
`action_buttons`	JSON string of `{name, deeplink}` — up to 2 buttons.
`notif_id`	Diagnostic send-job ID.
`template_id`	Dashboard template ID — branch to a custom renderer if you have one.
`workspace_id`	Diagnostic workspace ID.

Mobile Native vs Custom wire format (FCM notification vs data, APNs aps) is documented on Android and iOS. Web push always delivers a JSON body to the service worker — treat it like Custom mode.

The Three Tracking Events

Event naming — read this first: On mobile SDKs, trackMetric() 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. The service worker cannot call trackMetric(); it posts to the HTTP track API. The event strings in the snippets below are unchanged (Push Notification Delivered, Push Notification Opened, Push Notification Action Clicked). Both old and new names are recognized by the backend. If you have older dashboards/segments filtering on "Report Delivery Event", update them to filter on "Delivered" / "Opened" / "Clicked" (and the action event name) instead.

1. Delivery Confirmed

Event name (sent to Zixflow): Delivered (mobile trackMetric) / Push Notification Delivered (service-worker HTTP)
When to fire: The moment the push data payload arrives on the device — inside your service worker push event handler.
What happens: Zixflow updates the campaign delivery record to delivered. No profile event is stored.

// service-worker.js
self.addEventListener('push', (event) => {
  const data        = event.data?.json() ?? {};
  const deliveryId  = data['Zixflow-Delivery-ID'] ?? '';
  const token       = data['Zixflow-Delivery-Token'] ?? '';

  if (deliveryId && token) {
    fetch('https://events.zixflow.in/v1/track', {
      method:  'POST',
      headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${WRITE_KEY}` },
      body: JSON.stringify({
        event:      'Push Notification Delivered',
        userId:     self.__ZIXFLOW_USER_ID__,
        properties: {
          'Zixflow-Delivery-ID':    deliveryId,
          'Zixflow-Delivery-Token': token,
        },
      }),
    }).catch(() => {});
  }

  event.waitUntil(
    self.registration.showNotification(data.title ?? 'Notification', {
      body: data.body ?? '', icon: data.image_url, data,
      actions: parseButtons(data.action_buttons),
    })
  );
});

2. Notification Opened

Event name (sent to Zixflow): Opened (mobile trackMetric) / Push Notification Opened (service-worker HTTP)
When to fire: When the user taps the notification banner. Fire for both body taps and action button taps.
What happens: Zixflow updates the campaign delivery record to opened. No profile event is stored.

// service-worker.js — inside notificationclick
self.addEventListener('notificationclick', (event) => {
  const data        = event.notification.data ?? {};
  const deliveryId  = data['Zixflow-Delivery-ID'] ?? '';
  const token       = data['Zixflow-Delivery-Token'] ?? '';

  event.notification.close();

  if (deliveryId && token) {
    fetch('https://events.zixflow.in/v1/track', {
      method:  'POST',
      headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${WRITE_KEY}` },
      body: JSON.stringify({
        event:      'Push Notification Opened',
        userId:     self.__ZIXFLOW_USER_ID__,
        properties: { 'Zixflow-Delivery-ID': deliveryId, 'Zixflow-Delivery-Token': token },
      }),
    }).catch(() => {});
  }

  const deeplink = data['deeplink_url'] ?? '';
  event.waitUntil(deeplink ? clients.openWindow(deeplink) : clients.openWindow('/'));
});

3. Action Button Clicked

Event name (sent to Zixflow): Push Notification Action Clicked
When to fire: When the user taps a named action button. Always fire Opened first, then fire this event.
What happens: Zixflow records a clicked delivery report and captures which button was tapped for campaign analytics. 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
`source`	string	Optional	`"web_push"`

// service-worker.js — inside notificationclick, after tracking opened
if (event.action) {
  const actionIndex = parseInt(event.action.replace(/\D/g, ''), 10);
  const buttons     = parseButtons(data['action_buttons']);
  const actionName  = buttons[actionIndex]?.name ?? '';
  const actionDeep  = buttons[actionIndex]?.deeplink ?? '';

  fetch('https://events.zixflow.in/v1/track', {
    method:  'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${WRITE_KEY}` },
    body: JSON.stringify({
      event:      'Push Notification Action Clicked',
      userId:     self.__ZIXFLOW_USER_ID__,
      properties: {
        'Zixflow-Delivery-ID':    deliveryId,
        'Zixflow-Delivery-Token': token,
        'action_index':           actionIndex,
        'action_name':            actionName,
        'action_deeplink':        actionDeep,
      },
    }),
  }).catch(() => {});

  if (actionDeep) { event.waitUntil(clients.openWindow(actionDeep)); return; }
}

Platform-Specific Integration

Token Registration

import { AnalyticsBrowser } from '@zixflow/analytics-browser';

// After requesting notification permission
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
});

// Register the endpoint with Zixflow
Zixflow.registerPushToken({
  endpoint:  subscription.endpoint,
  keys:      subscription.toJSON().keys,
  platform:  'web',
});

Track Delivery (Service Worker — push event)

// service-worker.js
self.addEventListener('push', (event) => {
  const data       = event.data?.json() ?? {};
  const deliveryId = data['Zixflow-Delivery-ID'] ?? '';
  const token      = data['Zixflow-Delivery-Token'] ?? '';

  if (deliveryId && token) {
    // Best-effort — fire and forget from service worker
    fetch('https://events.zixflow.in/v1/track', {
      method:  'POST',
      headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${WRITE_KEY}` },
      body: JSON.stringify({
        event:      'Push Notification Delivered',
        userId:     self.__ZIXFLOW_USER_ID__ ?? undefined,
        properties: {
          'Zixflow-Delivery-ID':    deliveryId,
          'Zixflow-Delivery-Token': token,
        },
      }),
    }).catch(() => {});
  }

  event.waitUntil(
    self.registration.showNotification(data.title ?? 'Notification', {
      body:    data.body ?? '',
      icon:    data.image_url,
      badge:   data.badge_url,
      data:    data,
      actions: parseButtons(data.action_buttons),
    })
  );
});

Track Open (Service Worker — notificationclick event)

// service-worker.js
self.addEventListener('notificationclick', (event) => {
  const data        = event.notification.data ?? {};
  const deliveryId  = data['Zixflow-Delivery-ID'] ?? '';
  const token       = data['Zixflow-Delivery-Token'] ?? '';
  const actionIndex = event.action ? parseInt(event.action.replace(/\D/g, ''), 10) : -1;

  event.notification.close();

  // Always track opened
  trackEvent('Push Notification Opened', {
    'Zixflow-Delivery-ID':    deliveryId,
    'Zixflow-Delivery-Token': token,
  });

  // If action button tapped
  if (event.action) {
    const buttons    = parseButtons(data.action_buttons);
    const actionName = actionIndex >= 0 ? buttons[actionIndex]?.name ?? '' : '';
    const deeplink   = actionIndex >= 0 ? buttons[actionIndex]?.deeplink ?? '' : '';

    trackEvent('Push Notification Action Clicked', {
      'Zixflow-Delivery-ID':    deliveryId,
      'Zixflow-Delivery-Token': token,
      'notification_id':        deliveryId,
      'action_index':           actionIndex,
      'action_name':            actionName,
      'action_deeplink':        deeplink,
      'source':                 'web_push',
    });

    if (deeplink) { event.waitUntil(clients.openWindow(deeplink)); return; }
  }

  // Default: open deeplink or focus existing tab
  const deeplink = data['deeplink_url'] ?? '';
  event.waitUntil(deeplink ? clients.openWindow(deeplink) : clients.openWindow('/'));
});

Action Buttons Format

The action_buttons field is a JSON-encoded string of {name, deeplink} objects. Parse it before passing to showNotification({ actions }). 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 (Chrome/desktop browsers support up to 2 actions)
deeplink may be an empty string — handle gracefully, don’t navigate to a blank URL
Button index is 0-based

Parsing `action_buttons`

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

Building the Buttons on the Notification

// service-worker.js — inside the 'push' event handler
const buttons = parseButtons(data.action_buttons);

self.registration.showNotification(data.title ?? 'Notification', {
  body: data.body ?? '',
  icon: data.image_url,
  data,
  actions: buttons.map((btn, i) => ({
    action: `action_${i}`,   // ← read back in 'notificationclick' as event.action
    title: btn.name || `Action ${i + 1}`,
  })),
});

Chrome/desktop browsers support up to 2 actions per notification; unsupported browsers silently ignore the actions array and show a plain notification.

Handling the Tap (End-to-End)

Platform	Callback	Identifier format	Resolve to index
Web	`notificationclick`	`event.action` = `"action_0"` / `"action_1"`	`parseInt(event.action.replace(/\D/g, ''), 10)`

Deep Link Handling

Every Zixflow web push may carry a deeplink_url and per-button deeplinks in action_buttons. The service worker can’t render an in-app screen directly — it either focuses/navigates an existing tab or opens a new one.

// service-worker.js — inside notificationclick, after tracking opened/clicked
const deeplink = data['deeplink_url'] ?? '';

event.waitUntil((async () => {
  const allClients = await clients.matchAll({ type: 'window', includeUncontrolled: true });
  const target = deeplink || '/';

  // Reuse an existing tab if one is open, instead of always opening a new one
  const existing = allClients.find((c) => new URL(c.url).origin === self.location.origin);
  if (existing) {
    existing.navigate(target);
    return existing.focus();
  }
  return clients.openWindow(target);
})());

Priority order for navigation on tap:

If an action button was tapped → use action_buttons[index].deeplink
If body was tapped → use deeplink_url
If neither is set → open app to default screen

Write Key via SDK_CONFIG

Prefer receiving the write key from the WebPush plugin (not a hardcoded constant):

self.addEventListener('message', (event) => {
  const msg = event.data || {}
  if (msg.type === 'SDK_CONFIG') {
    if (msg.apiKey) WRITE_KEY = msg.apiKey
    if (msg.apiBase) {
      ZIXFLOW_API = String(msg.apiBase).replace(/\/$/, '') + '/track'
    }
  }
  if (msg.type === 'SET_USER_ID') {
    self.__ZIXFLOW_USER_ID__ = msg.userId || null
  }
  if (msg.type === 'SET_WRITE_KEY' && msg.writeKey) {
    WRITE_KEY = msg.writeKey
  }
})

function trackEvent(eventName, properties) {
  if (!WRITE_KEY) return Promise.resolve()
  return fetch(ZIXFLOW_API, {
    method: 'POST',
    keepalive: true,
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Basic ' + btoa(WRITE_KEY + ':'),
    },
    body: JSON.stringify({
      event: eventName,
      userId: self.__ZIXFLOW_USER_ID__,
      properties,
    }),
  }).catch(() => {})
}

Setting User ID

After analytics.identify():

navigator.serviceWorker.controller?.postMessage({
  type: 'SET_USER_ID',
  userId: 'user@example.com',
})

Decision Flowchart

Notification received?
├── YES → track Delivered        [always, as soon as data payload arrives]
│
User interacted?
├── Tapped notification body
│   └── track Opened             [with deliveryID + deviceToken]
│       └── Navigate to deeplink_url
│
└── Tapped action button
    ├── track 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 tracking with reserved event names. 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. If you send a custom event named exactly Delivered, Opened, or Clicked with no delivery identifier, it is stored as a normal profile event.

Testing

DevTools → Application → Service Workers → Console. Dashboard → Messaging → Push Notifications.

Getting Started

Features

Advanced

Reference

Push Notification Tracking

Why Push Tracking Matters

The Delivery Lifecycle at a Glance

The Push Payload

Complete Key Reference (web)

The Three Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Platform-Specific Integration

Token Registration

Track Delivery (Service Worker — push event)

Track Open (Service Worker — notificationclick event)

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification

Handling the Tap (End-to-End)

Deep Link Handling

Write Key via SDK_CONFIG

Setting User ID

Decision Flowchart

Fallback Behaviour (No Zixflow-Delivery-ID)

Testing

​Why Push Tracking Matters

​The Delivery Lifecycle at a Glance

​The Push Payload

​Complete Key Reference (web)

​The Three Tracking Events

​1. Delivery Confirmed

​2. Notification Opened

​3. Action Button Clicked

​Platform-Specific Integration

​Token Registration

​Track Delivery (Service Worker — push event)

​Track Open (Service Worker — notificationclick event)

​Action Buttons Format

​Parsing action_buttons

​Building the Buttons on the Notification

​Handling the Tap (End-to-End)

​Deep Link Handling

​Write Key via SDK_CONFIG

​Setting User ID

​Decision Flowchart

​Fallback Behaviour (No Zixflow-Delivery-ID)

​Testing

Why Push Tracking Matters

The Delivery Lifecycle at a Glance

The Push Payload

Complete Key Reference (web)

The Three Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Platform-Specific Integration

Token Registration

Track Delivery (Service Worker — push event)

Track Open (Service Worker — notificationclick event)

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification

Handling the Tap (End-to-End)

Deep Link Handling

Write Key via SDK_CONFIG

Setting User ID

Decision Flowchart

Fallback Behaviour (No Zixflow-Delivery-ID)

Testing