Push Notification Tracking

Overview

With the Dart FCM + flutter_local_notifications integration (see Push Notifications and push_handlers.dart), you track engagement yourself:

Delivered — call trackMetric(delivered) when the FCM data payload arrives (foreground and background), before showing the local notification; optionally also use an iOS NSE
Opened — call trackMetric(..., MetricEvent.opened) on body taps and action presses
Action Button Clicked — call track(name: 'Push Notification Action Clicked', ...)

The Flutter example tracks delivered, opened, and action clicked, then opens deeplinks via navigation.dart + url_launcher.

How Push Tracking Works

Field	Purpose
`Zixflow-Delivery-ID`	Unique ID for this delivery
`Zixflow-Delivery-Token`	FCM/APNs token the notification was sent to

Example push payload:

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

Tracking Events

1. Delivery Confirmed

When: The push payload arrives on the device. SDK method: Zixflow.instance.trackMetric(..., event: MetricEvent.delivered)

Path	Who tracks delivered
iOS + Notification Service Extension	Extension (via `MessagingPushFCM.initializeForExtension`)
Dart-only (no NSE / no native display)	Call `trackMetric(delivered)` yourself if you need the metric

Optional manual delivery tracking (e.g. foreground Android):

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  final deliveryId = message.data['Zixflow-Delivery-ID']?.toString() ?? '';
  final deliveryToken = message.data['Zixflow-Delivery-Token']?.toString() ?? '';
  if (deliveryId.isNotEmpty && deliveryToken.isNotEmpty) {
    Zixflow.instance.trackMetric(
      deliveryID: deliveryId,
      deviceToken: deliveryToken,
      event: MetricEvent.delivered,
    );
  }
});

2. Notification Opened

When: User taps the notification body (or an action button — track opened first, then the action event). SDK method: Zixflow.instance.trackMetric(..., event: MetricEvent.opened)

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

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

FirebaseMessaging.onMessageOpenedApp.listen((message) {
  _trackOpened(message.data);
  _handleDeeplink(message.data['deeplink_url']?.toString());
});

FirebaseMessaging.instance.getInitialMessage().then((message) {
  if (message != null) {
    _trackOpened(message.data);
    _handleDeeplink(message.data['deeplink_url']?.toString());
  }
});

Also call _trackOpened from the local-notification tap handler (body and actions), using the JSON payload you stored when showing the notification.

3. Action Button Clicked

When: User taps ACTION_0 or ACTION_1. SDK method: Zixflow.instance.track(name: 'Push Notification Action Clicked', properties: {...})

void _trackActionClick(Map<String, dynamic> payload, String actionId) {
  final actionIndex =
      int.tryParse(actionId.replaceAll(RegExp(r'\D'), '')) ?? -1;
  final buttons = parseActionButtons(payload['action_buttons']);
  final actionName = (actionIndex >= 0 && actionIndex < buttons.length)
      ? buttons[actionIndex]['name']?.toString() ?? 'Action ${actionIndex + 1}'
      : 'Action ${actionIndex + 1}';
  final actionDeeplink = (actionIndex >= 0 && actionIndex < buttons.length)
      ? buttons[actionIndex]['deeplink']?.toString() ?? ''
      : '';

  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': actionId,
      'action_index': actionIndex,
      'action_name': actionName,
      'action_deeplink': actionDeeplink,
      'source': 'local_notification',
    },
  );
}

On action press: track opened → track action clicked → cancel notification by id → open button deeplink if set, else deeplink_url. Required / recommended properties:

Property	Required	Description
`Zixflow-Delivery-ID`	Yes	Links to 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 (used in the example)

Deeplink opening (example pattern)

Shared helper used for FCM system opens and local-notification taps (navigation.dart):

Source	Field	After tracking
Body	`deeplink_url`	`_handleDeeplink`
Action	`action_buttons[].deeplink`, else `deeplink_url`	`_handleDeeplink`

final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

String? resolveInAppRoute(String? deeplink) {
  if (deeplink == null || deeplink.isEmpty) return null;
  final uri = Uri.tryParse(deeplink);
  if (uri == null || uri.scheme != 'zixflowdemo') return null; // your scheme
  switch (uri.host) {
    case 'sale':
      return '/sale';
    case 'dashboard':
      return '/dashboard';
    default:
      return null;
  }
}

void _handleDeeplink(String? deeplink) {
  if (deeplink == null || deeplink.isEmpty) return;
  final inAppRoute = resolveInAppRoute(deeplink);
  if (inAppRoute != null) {
    navigatorKey.currentState?.pushNamed(inAppRoute);
    return;
  }
  final uri = Uri.tryParse(deeplink);
  if (uri == null) return;
  launchUrl(uri, mode: LaunchMode.externalApplication);
}

Attach navigatorKey to MaterialApp and register named routes for in-app hosts. On Android 11+, declare <queries> for http/https if you open external links with url_launcher (see Push Notifications). Full tap hub (body vs action) from the example:

void _handleNotificationResponse(NotificationResponse response) {
  // decode JSON payload stored at display time...
  _trackOpened(payload);

  if (response.actionId != null && response.actionId!.isNotEmpty) {
    _trackActionClick(payload, response.actionId!);
    if (response.id != null) {
      FlutterLocalNotificationsPlugin().cancel(response.id!);
    }
    // prefer button deeplink, else body
    _handleDeeplink(buttonDeeplink.isNotEmpty ? buttonDeeplink : payload['deeplink_url']?.toString());
  } else {
    _handleDeeplink(payload['deeplink_url']?.toString());
  }
}

Action Buttons Format

"[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]"

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 (_) {
    return [];
  }
}

Maximum 2 buttons (ACTION_0, ACTION_1)
Empty deeplink is allowed — fall back to deeplink_url or skip navigation

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.

Tracking Decision Flow

Notification displayed (local notifications / FCM)
│
User interacted?
├── Tapped notification body
│   ├── trackMetric(opened)
│   └── _handleDeeplink(deeplink_url)  // in-app route or url_launcher
│
└── Tapped action button
    ├── trackMetric(opened)
    ├── track("Push Notification Action Clicked")
    ├── Cancel notification id (Android)
    └── _handleDeeplink(button deeplink, else deeplink_url)

Delivered?
├── On FCM receive → trackMetric(delivered) before local display (example)
└── iOS + NSE → also tracked by extension when configured

Fallback for Non-Zixflow Push

If the payload has no Zixflow-Delivery-ID, skip Zixflow push metrics. For your own analytics, use a different event name (do not use reserved push event names):

Zixflow.instance.track(
  name: 'External Push Received',
  properties: {
    'notification_id': message.messageId ?? '',
    'title': message.notification?.title ?? message.data['title'] ?? '',
    'source': 'external',
  },
);

Reserved names include Push Notification Action Clicked and the metric pipeline behind trackMetric.

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

Overview

How Push Tracking Works

Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Deeplink opening (example pattern)

Action Buttons Format

Background Isolate Taps

Tracking Decision Flow

Fallback for Non-Zixflow Push

Testing Push Tracking

​Overview

​How Push Tracking Works

​Tracking Events

​1. Delivery Confirmed

​2. Notification Opened

​3. Action Button Clicked

​Deeplink opening (example pattern)

​Action Buttons Format

​Background Isolate Taps

​Tracking Decision Flow

​Fallback for Non-Zixflow Push

​Testing Push Tracking

Overview

How Push Tracking Works

Tracking Events

1. Delivery Confirmed

2. Notification Opened

3. Action Button Clicked

Deeplink opening (example pattern)

Action Buttons Format

Background Isolate Taps

Tracking Decision Flow

Fallback for Non-Zixflow Push

Testing Push Tracking