Push Notifications

Complete guide to implementing push notifications in Flutter with Zixflow using Firebase Cloud Messaging (FCM) and flutter_local_notifications for display and action buttons.

Track your campaigns: Call trackMetric(opened) and track action clicks yourself. Campaigns can be Native (OS-rendered) or Custom (app-rendered). Zixflow sends Zixflow-Delivery-ID, Zixflow-Delivery-Token, plus routing keys (deeplink_url, action_buttons, template_id). For delivery, opens, action-button details, wire format, and Journeys event names (Delivered / Opened / Clicked), see Push Notification Tracking. The reference implementation is lib/push_handlers.dart in sdk-examples/flutter.

Prerequisites

Configure FCM in the Zixflow dashboard — add your Firebase / FCM credentials
Firebase project — create a project and add both iOS and Android apps
Identify users — call identify() before sending notifications so tokens attach to a profile
Test on physical devices — iOS Simulator cannot receive remote pushes

A device cannot receive Zixflow pushes until you: (1) register a device token, (2) identify a person, (3) obtain notification permission.

Platform-Specific Requirements

iOS

iOS 13.0+, Xcode 14.0+
Push Notifications capability enabled
Optional Notification Service Extension for rich push and reliable delivered metrics
Physical device for testing

Android

API 21+ (Android 5.0)
google-services.json in android/app/
POST_NOTIFICATIONS for Android 13+ (API 33+)
coreLibraryDesugaring (required by flutter_local_notifications)

Step 1: Firebase Project Setup

Create or open a project at Firebase Console
Add an iOS app (bundle ID), download GoogleService-Info.plist → ios/Runner/
Add an Android app whose package name matches applicationId in android/app/build.gradle, download google-services.json → android/app/

applicationId must match the package name registered in Firebase, or FCM token registration fails.

Step 2: Add Dependencies

dependencies:
  zixflow: ^1.1.5
  firebase_core: ^3.8.1
  firebase_messaging: ^15.1.5
  flutter_local_notifications: ^18.0.0
  http: ^1.2.0          # download image_url / large_icon_url
  path_provider: ^2.1.0
  url_launcher: ^6.3.1  # open deeplink_url / action deeplinks

flutter pub get

Step 3: Initialize Firebase and Zixflow

Native google-services.json / GoogleService-Info.plist is enough. FlutterFire (firebase_options.dart) is optional.

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'package:zixflow/zixflow.dart';

import 'push_handlers.dart'; // your FCM + local-notifications handlers

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();
  // Or with FlutterFire:
  // await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

  await Zixflow.initialize(
    config: ZixflowConfig(
      apiKey: 'YOUR_API_KEY',
      logLevel: LogLevel.debug,
    ),
  );

  await PushHandlers.initialize(); // after Firebase + Zixflow

  runApp(const MyApp());
}

Step 4: Handle Push Notifications (Dart path)

Use FCM for receive/token and flutter_local_notifications to display notifications (including action buttons). Track opens with trackMetric and action presses with track('Push Notification Action Clicked', ...).

Token registration

final token = await FirebaseMessaging.instance.getToken();
if (token != null) {
  Zixflow.instance.registerDeviceToken(deviceToken: token);
}

FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
  Zixflow.instance.registerDeviceToken(deviceToken: newToken);
});

Permission

await FirebaseMessaging.instance.requestPermission(
  alert: true,
  badge: true,
  sound: true,
  provisional: false,
);

Message listeners and tracking

// Foreground / background: show a local notification (with actions)
FirebaseMessaging.onMessage.listen((message) {
  _showLocalNotification(plugin, message);
});

// Body tap when the system opens the app from an FCM notification
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());
  }
});

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,
    );
  }
}

Do not track opens with a custom event like push_notification_clicked. Use trackMetric(..., MetricEvent.opened) and the reserved action event name below.

Step 5: Identify Users

Zixflow.instance.identify(
  userId: userId,
  traits: {
    'email': email,
    'first_name': 'John',
    'last_name': 'Doe',
  },
);

Tokens are linked to the profile when you call identify().

Local Notifications (Display + Action Buttons)

Channel ID zixflow_default, Android icon app_icon, iOS category ZX_2BTN, actions ACTION_0 / ACTION_1. Pass the full message.data map as JSON payload so taps can track and deep-link.

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

const _channelId = 'zixflow_default';
const _channelName = 'Zixflow Notifications';
const _iosCategoryId = 'ZX_2BTN';

Future<void> initializeLocalNotifications(
  FlutterLocalNotificationsPlugin plugin,
) async {
  await plugin.initialize(
    InitializationSettings(
      android: const AndroidInitializationSettings('app_icon'),
      iOS: DarwinInitializationSettings(
        requestAlertPermission: false,
        requestBadgePermission: false,
        requestSoundPermission: false,
        notificationCategories: [
          DarwinNotificationCategory(
            _iosCategoryId,
            actions: [
              DarwinNotificationAction.plain('ACTION_0', 'Action 1'),
              DarwinNotificationAction.plain('ACTION_1', 'Action 2'),
            ],
          ),
        ],
      ),
    ),
    onDidReceiveNotificationResponse: _handleNotificationResponse,
    onDidReceiveBackgroundNotificationResponse: _notificationTapBackground,
  );

  await plugin
      .resolvePlatformSpecificImplementation<
          AndroidFlutterLocalNotificationsPlugin>()
      ?.createNotificationChannel(
        const AndroidNotificationChannel(
          _channelId,
          _channelName,
          description: 'Zixflow push notifications',
          importance: Importance.high,
        ),
      );
}

/// 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);
}

void _handleNotificationResponse(NotificationResponse response) {
  if (response.payload == null || response.payload!.isEmpty) return;
  final payload = jsonDecode(response.payload!) as Map<String, dynamic>;

  _trackOpened(payload);

  if (response.actionId != null && response.actionId!.isNotEmpty) {
    _trackActionClick(payload, response.actionId!);
    // Action presses do not auto-dismiss on Android — cancel explicitly.
    if (response.id != null) {
      FlutterLocalNotificationsPlugin().cancel(response.id!);
    }
    final buttons = parseActionButtons(payload['action_buttons']);
    final actionIndex =
        int.tryParse(response.actionId!.replaceAll(RegExp(r'\D'), '')) ?? -1;
    final buttonDeeplink = (actionIndex >= 0 && actionIndex < buttons.length)
        ? buttons[actionIndex]['deeplink']?.toString() ?? ''
        : '';
    _handleDeeplink(
      buttonDeeplink.isNotEmpty
          ? buttonDeeplink
          : payload['deeplink_url']?.toString(),
    );
  } else {
    _handleDeeplink(payload['deeplink_url']?.toString());
  }
}

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',
    },
  );
}

When showing the notification, set payload: jsonEncode(data) with the FCM data map so taps can track. Parse up to two AndroidNotificationActions (ACTION_0 / ACTION_1), download image_url / large_icon_url, map sticky to Android ongoing (with autoCancel: true), and set iOS categoryIdentifier: 'ZX_2BTN'. If template_id is present, route to a template-specific renderer first — see Template-Based Custom Rendering.

Background FCM handler

The background handler must also display the local notification (so action buttons work when the app is backgrounded or terminated):

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  final plugin = FlutterLocalNotificationsPlugin();
  await plugin.initialize(
    const InitializationSettings(
      android: AndroidInitializationSettings('app_icon'),
    ),
    onDidReceiveNotificationResponse: _notificationTapBackground,
  );
  // create channel, then:
  await _showLocalNotification(plugin, message);
}

// Register once at startup:
FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);

Push Payload Fields

Zixflow always puts these tracking keys in data:

Field	Purpose
`Zixflow-Delivery-ID`	Campaign delivery ID (tracking)
`Zixflow-Delivery-Token`	Device token used for this send

Native: display content is in FCM notification / APNs aps. data carries tracking + routing keys (deeplink_url, action_buttons, template_id, notif_id, workspace_id). Full wire format: Push Notification Tracking. Custom: there is no notification block — the full content is in data. Official display/routing keys:

Key	How to use it
`title` / `body` (`message` is an alias of `body`)	Notification text
`deeplink_url`	Body-tap deep link
`image_url` / `large_icon_url`	Rich media
`action_buttons`	JSON string of `{name, deeplink}` (max 2)
`sticky`	Android ongoing / FLAG_NO_CLEAR
`template_id`	Dashboard template ID — branch to a custom renderer
`sound` / `badge` / `icon` / `color`	Platform presentation

Example Custom data:

{
  "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",
  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]",
  "sticky": "false",
  "sound": "default",
  "badge": "1",
  "template_id": "469935"
}

iOS-Specific Setup

Push capabilities

Open ios/Runner.xcworkspace
Runner target → Signing & Capabilities
Add Push Notifications
Add Background Modes → enable Remote notifications

AppDelegate — register `ZX_2BTN`

import UIKit
import Flutter
import UserNotifications

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    registerPushActionCategories()
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  private func registerPushActionCategories() {
    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])
  }
}

Notification Service Extension (rich push + delivered)

File → New → Target → Notification Service Extension (e.g. NotificationServiceExtension)
Enable App Groups on Runner and the extension (same group ID, e.g. group.com.yourcompany.app)
Podfile — NSE only (Runner does not need zixflow/fcm for this Dart path):

target 'NotificationServiceExtension' do
  use_frameworks!
  pod 'zixflow_richpush/fcm', :path => '.symlinks/plugins/zixflow/ios'
end

cd ios && pod install --repo-update && cd ..

NotificationService.swift:

import UserNotifications
import ZixflowMessagingPushFCM

class NotificationService: UNNotificationServiceExtension {
    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        MessagingPushFCM.initializeForExtension(
            withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_API_KEY")
                .logLevel(.debug)
                .appGroupId("group.com.yourcompany.app")
                .build()
        )
        MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
    }

    override func serviceExtensionTimeWillExpire() {
        MessagingPush.shared.serviceExtensionTimeWillExpire()
    }
}

Use cdpApiKey (not apiKey) and set .appGroupId(...) to the same App Group as the host app.

Android-Specific Setup

Gradle (plugins DSL)

android/settings.gradle:

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.9.3" apply false
    id "org.jetbrains.kotlin.android" version "2.1.21" apply false
    id "com.google.gms.google-services" version "4.4.0" apply false
}

android/app/build.gradle:

plugins {
    id "com.android.application"
    id "kotlin-android"
    id "dev.flutter.flutter-gradle-plugin"
    id "com.google.gms.google-services"
}

android {
    compileSdk 36
    ndkVersion "27.0.12077973"

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
        coreLibraryDesugaringEnabled true
    }

    defaultConfig {
        // Must match package_name in google-services.json
        applicationId "com.yourcompany.app"
    }
}

dependencies {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.4'
}

Permissions and deeplink package visibility

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<!-- url_launcher http(s) deeplinks on Android 11+ -->
<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="http" />
    </intent>
</queries>

Place a white notification icon drawable named app_icon (referenced by AndroidInitializationSettings('app_icon')).

Deeplink opening (example pattern)

Zixflow sends deeplink_url for body taps and action_buttons[].deeplink for action taps. After tracking Opened / Action Clicked, open those URLs. The sample app (push_handlers.dart + navigation.dart) uses:

Source	Field
Body tap	`deeplink_url`
Action tap	`action_buttons[].deeplink`, else `deeplink_url`

void _handleDeeplink(String? deeplink) {
  if (deeplink == null || deeplink.isEmpty) return;
  final inAppRoute = resolveInAppRoute(deeplink); // zixflowdemo://sale|dashboard
  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. Full open / action / delivered contract: Push Notification Tracking.

Sticky Notifications

data.sticky is an official Custom-mode field. Map it in your AndroidNotificationDetails. Native OS rendering does not honor sticky. Values: “Sticky” means the notification survives passive dismissal — the user swiping it away, or hitting “Clear all”. This is Android-only and only works on the Custom (app-rendered) path.

This requires two separate Android notification flags, not one — and a third piece of manual cleanup for action buttons.

autoCancel: true must always be on, regardless of sticky

ongoing: sticky is what actually blocks swipe and “Clear all” when sticky is "until_click" / "true" / "ongoing"

"until_swipe" / "no_clear" uses FLAG_NO_CLEAR without ongoing

Action buttons need an explicit cancel call in your action handler

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!);
  }
}

Full details: Push Notification Tracking — Sticky Notifications.

Template-based custom rendering (`template_id`)

Every push sent from a dashboard template includes data.template_id. Map known IDs to a dedicated renderer (see push_templates.dart) and fall back to the generic field-driven builder. The sample app also checks template_type == "custom" as a local routing gate — the official payload field is template_id. Full pattern: Template-Based Custom Rendering.

Testing

Register token + identify() a test user
Enable LogLevel.debug
Send a test push from the Zixflow dashboard (add your custom-data keys if testing buttons or deeplinks)
Use a physical iOS device; Android emulator needs Google Play Services

Troubleshooting

Issue	Check
No token	Firebase initialized; `google-services.json` / plist present; package ID matches Firebase
No notifications (Android 13+)	`POST_NOTIFICATIONS` granted at runtime
No action buttons (iOS)	`ZX_2BTN` registered in AppDelegate; local notif uses `categoryIdentifier: 'ZX_2BTN'`
Rich push / delivered missing (iOS)	NSE + App Groups + `cdpApiKey` / `appGroupId`
Deeplink fails (Android 11+)	`<queries>` for `http`/`https`
Desugaring errors	`coreLibraryDesugaringEnabled` + `desugar_jdk_libs`

Best Practices

Initialize Firebase before Zixflow, then your push handlers
Identify users after login; clearIdentify() on logout
Store the full FCM data map in the local-notification payload for tracking
If you add per-button links, prefer the button link over the body link on action taps
Cancel the notification ID on action press (Android)
Re-initialize Zixflow in the background notification-response isolate
See Push Notification Tracking for metrics details

Getting Started

Features

Advanced

Reference

Prerequisites

Platform-Specific Requirements

iOS

Android

Step 1: Firebase Project Setup

Step 2: Add Dependencies

Step 3: Initialize Firebase and Zixflow

Step 4: Handle Push Notifications (Dart path)

Token registration

Permission

Message listeners and tracking

Step 5: Identify Users

Local Notifications (Display + Action Buttons)

Background FCM handler

Push Payload Fields

iOS-Specific Setup

Push capabilities

AppDelegate — register `ZX_2BTN`

Notification Service Extension (rich push + delivered)

Android-Specific Setup

Gradle (plugins DSL)

Permissions and deeplink package visibility

Deeplink opening (example pattern)

Sticky Notifications

Template-based custom rendering (`template_id`)

Testing

Troubleshooting

Best Practices

​Prerequisites

​Platform-Specific Requirements

​iOS

​Android

​Step 1: Firebase Project Setup

​Step 2: Add Dependencies

​Step 3: Initialize Firebase and Zixflow

​Step 4: Handle Push Notifications (Dart path)

​Token registration

​Permission

​Message listeners and tracking

​Step 5: Identify Users

​Local Notifications (Display + Action Buttons)

​Background FCM handler

​Push Payload Fields

​iOS-Specific Setup

​Push capabilities

​AppDelegate — register ZX_2BTN

​Notification Service Extension (rich push + delivered)

​Android-Specific Setup

​Gradle (plugins DSL)

​Permissions and deeplink package visibility

​Deeplink opening (example pattern)

​Sticky Notifications

​Template-based custom rendering (template_id)

​Testing

​Troubleshooting

​Best Practices

Prerequisites

Platform-Specific Requirements

iOS

Android

Step 1: Firebase Project Setup

Step 2: Add Dependencies

Step 3: Initialize Firebase and Zixflow

Step 4: Handle Push Notifications (Dart path)

Token registration

Permission

Message listeners and tracking

Step 5: Identify Users

Local Notifications (Display + Action Buttons)

Background FCM handler

Push Payload Fields

iOS-Specific Setup

Push capabilities

AppDelegate — register `ZX_2BTN`

Notification Service Extension (rich push + delivered)

Android-Specific Setup

Gradle (plugins DSL)

Permissions and deeplink package visibility

Deeplink opening (example pattern)

Sticky Notifications

Template-based custom rendering (`template_id`)

Testing

Troubleshooting

Best Practices