Push Notification Tracking

Last Updated: July 2, 2026
Audience: Client developers integrating Zixflow SDK (Flutter)
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 push_handlers.dart.

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 flutter_local_notifications.

	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 (`flutter_local_notifications`)
Image / color	Native image + color work with zero app code (verify FlutterFire fallback — it can 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): your onMessage/background handler is not invoked at all when the payload has a notification block and the app is backgrounded. Track Opened from onMessageOpenedApp / getInitialMessage. 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 your local-notification tap handlers.

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

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  // Foreground: OS never auto-shows anything, so if you truly want zero custom UI,
  // you show nothing here — just track. (Most apps still build a notification in
  // foreground; this snippet is the "OS/FCM-only" extreme for comparison.)
  final deliveryId = message.data['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = message.data['Zixflow-Delivery-Token'] ?? fcmToken ?? '';
  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.trackMetric(
      deliveryID: deliveryId, deviceToken: deliveryToken, event: MetricEvent.delivered,
    );
  }
});

// Background/killed tap (notification-block push, OS already rendered it):
FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) => _trackOpened(message.data));
final initial = await FirebaseMessaging.instance.getInitialMessage();
if (initial != null) _trackOpened(initial.data);

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

A note on FlutterFire and Path A: FlutterFire’s fallback (fcm_fallback_notification_channel) renders title+body only and silently drops notification.image, even though genuine stock FCM rendering supports it. If you need images on Path A, build a minimal renderer yourself that reads notification.title/body/android.imageUrl rather than relying on the library’s fallback.

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 (Android) / top-level keys (iOS).

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.decode() before use.

On Android, Native-mode display content lives in notification.title / body / image. On iOS it lives in aps.alert. Prefer message.notification?.x ?? data['x'] so a single renderer covers both modes while the app is in the foreground.

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 `notification` / `aps` · Custom: matching `data.*` keys	See Field Support Summary. Sticky is Android-only.
`notif_id`	`data.notif_id`	Diagnostic send-job ID — not `Zixflow-Delivery-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. FlutterFire’s fallback can drop the image — build a minimal renderer if you need it.
`color`	Fully supported on Android.
`icon` / `sound`	Supported when the resource is bundled in the app.
`sticky`	Not supported on Native. Custom path only (`data.sticky`). Android-only.
`large_icon_url`	Not supported on Native.
`action_buttons`	Not supported on Native — always requires Custom handling.
`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 (both modes). Map known IDs to a dedicated renderer and fall back to the generic field-driven builder. The Flutter sample also checks template_type == "custom" before looking up template_id — that extra gate is a sample-app routing convention. The official payload field is template_id.

// push_templates.dart
const String _exampleTemplateId = '469935'; // swap in your own template's ID

Future<void> _showLocalNotification(FlutterLocalNotificationsPlugin plugin, RemoteMessage message) async {
  final data = Map<String, dynamic>.from(message.data);
  final title = message.notification?.title ?? data['title']?.toString() ?? 'Notification';
  final body = message.notification?.body ?? data['body']?.toString() ?? '';

  if (data['template_id']?.toString() == _exampleTemplateId) {
    await _showTemplateExampleNotification(plugin, message, data, title, body);
    return;
  }
  // ...generic field-driven notification building continues here
}

Future<void> _showTemplateExampleNotification(
  FlutterLocalNotificationsPlugin plugin, RemoteMessage message,
  Map<String, dynamic> data, String title, String body,
) async {
  final id = message.hashCode;
  final imagePath = await _downloadToTempFile(data['image_url']?.toString(), 'template_img_$id.jpg');
  final largeIconPath = await _downloadToTempFile(data['large_icon_url']?.toString(), 'template_icon_$id.jpg');
  final soundName = data['sound']?.toString();
  final sticky = data['sticky']?.toString() == 'true';

  await plugin.show(
    id, title, body,
    NotificationDetails(
      android: AndroidNotificationDetails(
        'zixflow_template_example', 'Template Example',
        largeIcon: largeIconPath != null ? FilePathAndroidBitmap(largeIconPath) : null,
        styleInformation: imagePath != null
            ? BigPictureStyleInformation(FilePathAndroidBitmap(imagePath), contentTitle: title, summaryText: body)
            : BigTextStyleInformation(body),
        number: int.tryParse(data['badge']?.toString() ?? ''),
        sound: soundName != null ? RawResourceAndroidNotificationSound(soundName) : null,
        playSound: soundName != null,
        ongoing: sticky, autoCancel: true,
      ),
      iOS: DarwinNotificationDetails(
        categoryIdentifier: 'ZX_2BTN',
        attachments: imagePath != null ? [DarwinNotificationAttachment(imagePath)] : null,
      ),
    ),
    payload: jsonEncode(data),
  );
}

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/flutter.

Future<void> showZixflowNotification(RemoteMessage message) async {
  final data = message.data;
  final title = message.notification?.title ?? data['title'] ?? 'Notification';
  final body = message.notification?.body ?? data['body'] ?? data['message'] ?? '';

  final imagePath = await _downloadToTempFile(data['image_url'], 'img.jpg');
  final largeIconPath = await _downloadToTempFile(data['large_icon_url'], 'icon.jpg');

  final soundName = data['sound'];
  final androidSound = (soundName != null && soundName != 'default' && soundName != 'none')
      ? RawResourceAndroidNotificationSound(soundName)
      : null;

  final badgeCount = int.tryParse(data['badge'] ?? '');

  final sticky = data['sticky'];
  final ongoing = sticky == 'true' || sticky == 'until_click' || sticky == 'ongoing';
  final noClearOnly = sticky == 'until_swipe' || sticky == 'no_clear';

  final priority = data['priority'];
  final channelId = priority == 'normal' ? 'zixflow_normal' : 'zixflow_default';
  final channelName = priority == 'normal' ? 'Zixflow Notifications (normal priority)' : 'Zixflow Notifications';

  final buttons = parseActionButtons(data['action_buttons']);
  final androidActions = [
    for (var i = 0; i < buttons.length && i < 2; i++)
      AndroidNotificationAction('ACTION_$i', buttons[i]['name'] ?? 'Action ${i + 1}', showsUserInterface: true),
  ];

  await FlutterLocalNotificationsPlugin().show(
    message.hashCode,
    title,
    body,
    NotificationDetails(
      android: AndroidNotificationDetails(
        channelId, channelName,
        icon: 'ic_notification',
        color: const Color(0xFFFA2438),
        importance: priority == 'normal' ? Importance.defaultImportance : Importance.high,
        priority: priority == 'normal' ? Priority.defaultPriority : Priority.high,
        autoCancel: true, ongoing: ongoing,
        additionalFlags: noClearOnly ? Int32List.fromList([0x00000020 /* FLAG_NO_CLEAR */]) : null,
        sound: androidSound, playSound: androidSound != null,
        number: badgeCount,
        largeIcon: largeIconPath != null ? FilePathAndroidBitmap(largeIconPath) : null,
        styleInformation: imagePath != null
            ? BigPictureStyleInformation(FilePathAndroidBitmap(imagePath), contentTitle: title, summaryText: body)
            : null,
        actions: androidActions,
      ),
      iOS: DarwinNotificationDetails(
        categoryIdentifier: 'ZX_2BTN',
        badgeNumber: badgeCount,
        sound: (soundName != null && soundName != 'default') ? '$soundName.caf' : null,
        attachments: imagePath != null ? [DarwinNotificationAttachment(imagePath)] : null,
      ),
    ),
    payload: jsonEncode(data),
  );
}

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 / onMessageReceived / willPresent handler.
SDK method: Zixflow.instance.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`

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  final deliveryId    = message.data['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = message.data['Zixflow-Delivery-Token'] ?? fcmToken ?? '';

  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.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 `FirebaseMessaging.onMessage` / the background handler.
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` (already set in Custom mode). 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.instance.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`

// Background tap — app was backgrounded
FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
  final deliveryId    = message.data['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = message.data['Zixflow-Delivery-Token'] ?? fcmToken ?? '';

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

// Terminated tap — app was closed when user tapped
bool _initialHandled = false;
final initial = await FirebaseMessaging.instance.getInitialMessage();
if (initial != null && !_initialHandled) {
  _initialHandled = true;
  final deliveryId    = initial.data['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = initial.data['Zixflow-Delivery-Token'] ?? fcmToken ?? '';

  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.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.instance.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"`

// In FlutterLocalNotificationsPlugin.initialize()
onDidReceiveNotificationResponse: (NotificationResponse response) {
  final payload = jsonDecode(response.payload ?? '{}') as Map<String, dynamic>;

  // Always fire opened first
  final deliveryId    = payload['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = payload['Zixflow-Delivery-Token'] ?? '';
  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.trackMetric(
      deliveryID: deliveryId, deviceToken: deliveryToken, event: MetricEvent.opened,
    );
  }

  // Then fire action clicked (only if a button was tapped, not body tap)
  if (response.actionId != null) {
    final actionIndex = int.tryParse(response.actionId!.replaceAll(RegExp(r'\D'), '')) ?? -1;
    final buttons     = _parseButtons(payload['action_buttons']);
    final actionName  = (actionIndex >= 0 && actionIndex < buttons.length)
        ? buttons[actionIndex]['name'] ?? 'Action ${actionIndex + 1}'
        : 'Action ${actionIndex + 1}';

    Zixflow.instance.track(
      name: 'Push Notification Action Clicked',
      properties: {
        'Zixflow-Delivery-ID':    deliveryId,
        'Zixflow-Delivery-Token': deliveryToken,
        'action_index':           actionIndex,
        'action_name':            actionName,
        'action_deeplink':        actionIndex >= 0 ? (buttons[actionIndex]['deeplink'] ?? '') : '',
      },
    );
  }
},

Platform-Specific Integration

Flutter is the reference implementation. The pattern is the same for both platforms once FCM / APNs tokens are obtained.

Step 1 — Register Device Token

import 'package:zixflow/zixflow.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

// On app start, get the FCM token and register it
final fcmToken = await FirebaseMessaging.instance.getToken();
if (fcmToken != null) {
  Zixflow.instance.registerDeviceToken(deviceToken: fcmToken);
}

// Keep token fresh — re-register whenever FCM rotates it
FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
  Zixflow.instance.registerDeviceToken(deviceToken: newToken);
});

Step 2 — Track Delivery (Foreground)

When the app is in the foreground, FCM delivers the message to onMessage. Track delivery immediately.

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  final deliveryId    = message.data['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = message.data['Zixflow-Delivery-Token'] ?? fcmToken ?? '';

  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.trackMetric(
      deliveryID:  deliveryId,
      deviceToken: deliveryToken,
      event:       MetricEvent.delivered,
    );
  } else {
    // Fallback: no Zixflow IDs present (non-Zixflow push source)
    Zixflow.instance.track(
      name: 'Push Notification Delivered',
      properties: {
        'notification_id': message.messageId ?? '',
        'title': message.notification?.title ?? message.data['title'] ?? '',
        'body':  message.notification?.body  ?? message.data['body']  ?? '',
      },
    );
  }

  // Show a local notification (since app is in foreground)
  _showLocalNotification(message);
});

Step 3 — Track Open (Background / Terminated)

// Background: app was in background, user tapped banner
FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
  _trackOpened(message.data, fcmToken);
  _handleDeeplink(message.data['deeplink_url']);
});

// Terminated: app was closed, notification tap launched the app
final initial = await FirebaseMessaging.instance.getInitialMessage();
if (initial != null) {
  _trackOpened(initial.data, fcmToken);
  _handleDeeplink(initial.data['deeplink_url']);
}

void _trackOpened(Map<String, String> data, String? fallbackToken) {
  final deliveryId    = data['Zixflow-Delivery-ID'] ?? '';
  final deliveryToken = data['Zixflow-Delivery-Token'] ?? fallbackToken ?? '';

  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.trackMetric(
      deliveryID:  deliveryId,
      deviceToken: deliveryToken,
      event:       MetricEvent.opened,
    );
  } else {
    Zixflow.instance.track(
      name: 'Push Notification Opened',
      properties: {
        'notification_id': data['notif_id'] ?? '',
        'deeplink':        data['deeplink_url'] ?? '',
      },
    );
  }
}

Step 4 — Track Action Button Click (Local Notification Response)

For foreground-received notifications displayed as local notifications, handle taps via flutter_local_notifications:

// In FlutterLocalNotificationsPlugin.initialize()
onDidReceiveNotificationResponse: (NotificationResponse response) {
  final payload = jsonDecode(response.payload ?? '{}') as Map<String, dynamic>;

  if (response.actionId == null) {
    // Body tap → opened
    _trackOpened(payload, null);
  } else {
    // Action button tap → opened + clicked
    _trackOpened(payload, null);

    final actionIndex = int.tryParse(
        response.actionId!.replaceAll(RegExp(r'\D'), '')) ?? -1;
    final buttons = _parseButtons(payload['action_buttons']);
    final buttonName = (actionIndex >= 0 && actionIndex < buttons.length)
        ? buttons[actionIndex]['name'] ?? 'Action ${actionIndex + 1}'
        : 'Action ${actionIndex + 1}';

    Zixflow.instance.track(
      name: 'Push Notification Action Clicked',
      properties: {
        'Zixflow-Delivery-ID':    payload['Zixflow-Delivery-ID'] ?? '',
        'Zixflow-Delivery-Token': payload['Zixflow-Delivery-Token'] ?? '',
        'notification_id':        payload['Zixflow-Delivery-ID'] ?? '',
        'title':                  payload['title'] ?? '',
        'action_id':              response.actionId!,
        'action_index':           actionIndex,
        'action_name':            buttonName,
        'action_deeplink':        _resolveButtonDeeplink(buttons, actionIndex),
        'source':                 'local_notification',
      },
    );
  }
},

List<Map<String, dynamic>> _parseButtons(dynamic raw) {
  if (raw == null) return [];
  try {
    final decoded = raw is String ? jsonDecode(raw) : raw;
    return List<Map<String, dynamic>>.from(decoded as List);
  } catch (_) {
    return [];
  }
}

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 build the local notification. 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 (iOS system limit; Android supports more but keep it consistent)
deeplink may be an empty string — handle gracefully, don’t navigate to a blank URL
Button index is 0-based — button at index 0 is leftmost/first
On iOS, button labels are pre-registered at app init due to OS constraints. Only the deeplinks are dynamic from the payload. Use generic labels in the pre-registration (“Action 1”, “Action 2”) and rely on the action_name in the tracking event for analytics.

iOS pre-registration example (required):

// Must be done at app launch in AppDelegate / UNUserNotificationCenter setup
let actions = [
    UNNotificationAction(identifier: "ACTION_0", title: "Action 1", options: .foreground),
    UNNotificationAction(identifier: "ACTION_1", title: "Action 2", options: .foreground),
]
let category = UNNotificationCategory(identifier: "ZX_2BTN", actions: actions,
                                       intentIdentifiers: [], options: [])
UNUserNotificationCenter.current().setNotificationCategories([category])

Parsing `action_buttons`

/// Parses the Zixflow `action_buttons` payload (JSON string or already-decoded list).
List<Map<String, dynamic>> parseActionButtons(dynamic raw) {
  if (raw == null) return [];
  try {
    final decoded = raw is String ? jsonDecode(raw) : raw;
    return List<Map<String, dynamic>>.from(decoded as List);
  } catch (e) {
    return [];
  }
}

Building the Buttons on the Notification (Foreground Path)

// push_handlers.dart pattern
final buttons = parseActionButtons(data['action_buttons']);
final androidActions = <AndroidNotificationAction>[];
for (var i = 0; i < buttons.length && i < 2; i++) {
  androidActions.add(
    AndroidNotificationAction(
      'ACTION_$i',
      buttons[i]['name']?.toString() ?? 'Action ${i + 1}',
      showsUserInterface: true,
    ),
  );
}

final androidDetails = AndroidNotificationDetails(
  channelId,
  channelName,
  importance: Importance.high,
  priority: Priority.high,
  actions: androidActions,     // ← dynamic buttons attached here
);

// iOS buttons are pre-registered (see category above) — deeplinks/names for tracking
// come from the payload at tap time, not from anything attached here. Just make sure
// `categoryIdentifier: 'ZX_2BTN'` is set on the iOS notification details so the OS
// shows the pre-registered actions:
final iosDetails = DarwinNotificationDetails(
  categoryIdentifier: 'ZX_2BTN',
);

onDidReceiveNotificationResponse’s response.actionId (e.g. "ACTION_0") is what you parse back into an index for tracking.

Handling the Tap (End-to-End)

Platform	Callback	Identifier format	Resolve to index
Flutter	`onDidReceiveNotificationResponse`	`response.actionId` = `"ACTION_0"` / `"ACTION_1"`	`int.parse(actionId.replaceAll(RegExp(r'\D'), ''))`

Important on Android (Flutter): pressing an action button does not automatically dismiss the notification the way tapping the notification body does — see Sticky Notifications below.

New Notification Layouts

Not Zixflow-defined. If you want Android layouts, add keys such as style / progress / timer yourself and render them. Sample-app convention below. Android-only.

`style` — notification layout

`style` value	Layout	Notes
absent	Basic text (auto-expands to `BigText` if the body is long)	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`.

Maps to Android’s setUsesChronometer(true) + setChronometerCountDown(true) + setWhen(endTimeMillis).

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 ongoing / FLAG_NO_CLEAR in your builder — Native OS rendering does not honor sticky. Values: 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 — there is no iOS/APNs equivalent. Sticky only works on the Custom (app-rendered) path.

Regardless of which mode:

autoCancel: true must always be on

ongoing / FLAG_NO_CLEAR is driven by the sticky value (see Complete Field Mapping Reference)

Action buttons need an explicit cancel call except for until_click, where only a body tap should dismiss

final sticky = data['sticky']?.toString() == 'true';

final androidDetails = AndroidNotificationDetails(
  channelId,
  channelName,
  importance: Importance.high,
  priority: Priority.high,
  autoCancel: true,   // always true — body tap always dismisses
  ongoing: sticky,    // true = survives swipe + "Clear all"
);

// In onDidReceiveNotificationResponse, after tracking the action click:
if (response.actionId != null && response.actionId!.isNotEmpty) {
  // Required regardless of `sticky` — action buttons never auto-dismiss on Android.
  if (response.id != null) {
    FlutterLocalNotificationsPlugin().cancel(response.id!);
  }
}

Unlike native Android, Flutter’s Zixflow SDK does not intercept messages with its own background service — your app’s FirebaseMessaging.onMessage / onBackgroundMessage handler is what builds the local notification, so this flag must be read and applied in your own app code.

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 data.click_action key is optional — the sample app maps "OPEN_SALE" / "OPEN_DASHBOARD" ahead of deeplink_url.

Resolution order your routing code should follow, regardless of platform:

Try to resolve the link to one of your app’s own screens (e.g. a custom yourapp:// scheme, or https://yourapp.com/... paths you own).
If it doesn’t match anything you own, fall back to opening it externally (browser, another installed app, mailto:, etc.).
If the URL is empty/missing, do nothing (or navigate to a default/home screen).

// navigation.dart — resolve in-app first, caller falls back externally
bool resolveInAppRoute(String? deeplink) {
  if (deeplink == null || deeplink.isEmpty) return false;
  final uri = Uri.tryParse(deeplink);
  if (uri == null || uri.scheme != 'zixflowdemo') return false;

  switch (uri.host) {
    case 'sale':
      navigatorKey.currentState?.pushNamed('/sale');
      return true;
    case 'dashboard':
      navigatorKey.currentState?.pushNamed('/dashboard');
      return true;
    default:
      return false;
  }
}

// push_handlers.dart — called from onMessageOpenedApp / getInitialMessage / action tap
void _handleDeeplink(String? url) {
  if (url == null || url.isEmpty) return;
  if (resolveInAppRoute(url)) return;   // handled by one of our own screens

  final uri = Uri.tryParse(url);
  if (uri != null) launchUrl(uri);      // fall back to external browser/app
}

Decision Flowchart

Use this when deciding which SDK call to make for any notification interaction:

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 (e.g., a direct FCM API call, a test tool, or a third-party system), 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 (e.g., to build a custom funnel), use a custom event name instead:

// Use a custom event name — push system events are not stored as profile events
Zixflow.instance.track(
  name: 'External Push Received',   // choose a name that makes sense for your use case
  properties: {
    'notification_id': message.messageId ?? '',
    'title':           message.notification?.title ?? '',
    'body':            message.notification?.body ?? '',
    'source':          'external',
  },
);

Background Isolate Taps

When the app was terminated and the user taps a local notification, the response may run in a background isolate. Re-initialize Zixflow before tracking:

@pragma('vm:entry-point')
Future<void> _notificationTapBackground(NotificationResponse response) async {
  await Zixflow.initialize(
    config: ZixflowConfig(apiKey: 'YOUR_API_KEY'),
  );
  _handleNotificationResponse(response);
}

Wire this as onDidReceiveBackgroundNotificationResponse when initializing FlutterLocalNotificationsPlugin.

Testing Push Tracking

final config = ZixflowConfig(
  apiKey: 'YOUR_API_KEY',
  logLevel: LogLevel.debug,
);

In the dashboard: Messaging → Push Notifications → check Delivered, Opened, and Clicked (action) for your campaign.

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

Platform-Specific Integration

Step 1 — Register Device Token

Step 2 — Track Delivery (Foreground)

Step 3 — Track Open (Background / Terminated)

Step 4 — Track Action Button Click (Local Notification Response)

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification (Foreground Path)

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)

Background Isolate Taps

Testing Push 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

​Platform-Specific Integration

​Step 1 — Register Device Token

​Step 2 — Track Delivery (Foreground)

​Step 3 — Track Open (Background / Terminated)

​Step 4 — Track Action Button Click (Local Notification Response)

​Action Buttons Format

​Parsing action_buttons

​Building the Buttons on the Notification (Foreground Path)

​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)

​Background Isolate Taps

​Testing Push 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

Platform-Specific Integration

Step 1 — Register Device Token

Step 2 — Track Delivery (Foreground)

Step 3 — Track Open (Background / Terminated)

Step 4 — Track Action Button Click (Local Notification Response)

Action Buttons Format

Parsing `action_buttons`

Building the Buttons on the Notification (Foreground Path)

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)

Background Isolate Taps

Testing Push Tracking