Push Notifications

Complete guide to push notifications in React Native with Zixflow using @react-native-firebase/messaging for FCM and @notifee/react-native for display and action buttons.

Track your campaigns: Track opens with Zixflow.trackMetric({ event: MetricEvent.Opened }) and action presses with Zixflow.track('Push Notification Action Clicked', ...). See Push Notification Tracking. Reference implementation: src/pushHandlers.ts in sdk-examples/react-native.

Prerequisites

Configure FCM (and APNs for iOS) in the Zixflow dashboard
Add Firebase config files (google-services.json, GoogleService-Info.plist)
Call identify() so device tokens attach to a user
Test on a physical device for iOS

Dependencies

npm install @react-native-firebase/app @react-native-firebase/messaging @notifee/react-native
cd ios && pod install && cd ..

Architecture

Concern	Library
Receive FCM / token	`@react-native-firebase/messaging`
Display + action buttons	`@notifee/react-native`
Token → Zixflow	`Zixflow.registerDeviceToken`
Opened / action metrics	`trackMetric(Opened)` + `track('Push Notification Action Clicked')`

The Zixflow native FCM service may still run in parallel for token/delivery on Android. This stack owns display and open/action tracking in JavaScript — no custom Kotlin action installer required.

Initialize handlers

After Zixflow.initialize():

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

const ANDROID_CHANNEL_ID = 'zixflow_default';

async function initializePush() {
  await notifee.requestPermission();

  if (Platform.OS === 'android') {
    await notifee.createChannel({
      id: ANDROID_CHANNEL_ID,
      name: 'Zixflow Notifications',
      importance: AndroidImportance.HIGH,
    });
  }

  if (Platform.OS === 'ios') {
    await messaging().requestPermission();
    if (!messaging().isDeviceRegisteredForRemoteMessages) {
      await messaging().registerDeviceForRemoteMessages();
    }
  }

  const token = await messaging().getToken();
  await Zixflow.registerDeviceToken(token);

  messaging().onTokenRefresh(async (newToken) => {
    await Zixflow.registerDeviceToken(newToken);
  });

  messaging().onMessage(async (message) => {
    await showNotification(message);
  });

  messaging().onNotificationOpenedApp((message) => {
    trackOpened(message.data ?? {});
    handleDeeplink(message.data?.deeplink_url);
  });

  const initial = await messaging().getInitialNotification();
  if (initial) {
    trackOpened(initial.data ?? {});
    handleDeeplink(initial.data?.deeplink_url);
  }

  notifee.onForegroundEvent(({ type, detail }) => {
    handleNotifeeEvent(type, detail);
  });
}

import messaging from '@react-native-firebase/messaging';
import notifee from '@notifee/react-native';
import {
  firebaseBackgroundMessageHandler,
  notifeeBackgroundEventHandler,
} from './src/pushHandlers';

messaging().setBackgroundMessageHandler(firebaseBackgroundMessageHandler);
notifee.onBackgroundEvent(notifeeBackgroundEventHandler);

Background FCM handler should call the same showNotification path so action buttons work when the app is backgrounded or terminated.

Display with notifee (including action buttons)

Parse action_buttons (max 2). Use channel zixflow_default, iOS categoryId: 'ZX_2BTN', and store the full data map on the notification for tap tracking.

function buildNotifeeActions(data: Record<string, string | undefined>) {
  const buttons = parseActionButtons(data.action_buttons);
  return buttons.slice(0, 2).map((button, index) => ({
    title: button.name || `Action ${index + 1}`,
    pressAction: { id: `action_${index}` },
  }));
}

await notifee.displayNotification({
  title,
  body,
  data,
  android: {
    channelId: ANDROID_CHANNEL_ID,
    importance: AndroidImportance.HIGH,
    pressAction: { id: 'default' },
    actions: buildNotifeeActions(data),
    autoCancel: true,
    ongoing: data.sticky === 'true',
    // optional: largeIcon, BigPicture from image_url / large_icon_url
  },
  ios: {
    categoryId: 'ZX_2BTN',
  },
});

Payload fields: Zixflow-Delivery-ID, Zixflow-Delivery-Token, title, body, deeplink_url, image_url, large_icon_url, action_buttons, sticky, sound, badge.

Open and action tracking

Wire trackOpened / handleNotifeeEvent / handleDeeplink as in the example pushHandlers.ts:

Body tap → trackMetric(Opened) + open deeplink_url
Action tap → trackMetric(Opened) + track('Push Notification Action Clicked') + cancel notification + open button deeplink (else deeplink_url)

Full helpers and property contract: Push Notification Tracking.

Custom Action Buttons — iOS category

import UserNotifications

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])
}

Call this from application(_:didFinishLaunchingWithOptions:) (see the example AppDelegate). Also configure Firebase (FirebaseApp.configure()). When notifee displays the notification, action presses are handled in JS via notifee.onForegroundEvent / onBackgroundEvent — you do not need a separate AppDelegate didReceive tracker for that path.

iOS Capabilities

Open the .xcworkspace in Xcode
App target → Signing & Capabilities
Add Push Notifications
Add Background Modes → Remote notifications

Optional: Notification Service Extension + App Groups for rich push and reliable delivered metrics — see App Groups below.

App Groups

App Groups improve delivery metric reliability on iOS. If the system terminates the Notification Service Extension before a tracking request finishes, the SDK can recover pending metrics on the next app launch when both targets share an App Group. Add the same App Group to the host app and the Notification Service Extension:

Host app target → Signing & Capabilities → + Capability → App Groups
Create an ID such as group.com.yourcompany.yourapp.zixflow
NSE target → App Groups → select the same identifier

Both targets must use the identical string. If you use manual signing, register the App Group in the Apple Developer portal, enable it on both App IDs, and regenerate provisioning profiles. Configure .appGroupId(...) in both the host app push init and the NSE init. Values must match the Xcode entitlements. Host app (AppDelegate, APNs example):

MessagingPushAPN.initialize(
  withConfig: MessagingPushConfigBuilder()
    .appGroupId("group.com.yourcompany.yourapp.zixflow")
    .build()
)

For FCM, use MessagingPushFCM.initialize with the same .appGroupId(...). Notification Service Extension:

MessagingPushAPN.initializeForExtension(
  withConfig: MessagingPushConfigBuilder(apiKey: "YOUR_API_KEY")
    .appGroupId("group.com.yourcompany.yourapp.zixflow")
    .build()
)

The sdk-examples React Native app uses group.com.zixflow.demo.rn as a concrete sample. If you omit .appGroupId(...), the SDK may try a default patterned identifier. Prefer an explicit App Group ID to avoid mismatches.

Android Setup

Place google-services.json in android/app/
Apply the Google Services Gradle plugin
Declare POST_NOTIFICATIONS and request it at runtime on API 33+
Create the notifee channel zixflow_default in JS (as above)

Notification Channels

On Android 8.0+, notifications belong to a channel that controls sound, importance, and user settings.

When you display with notifee (example path)

The React Native example creates the channel in JavaScript:

await notifee.createChannel({
  id: 'zixflow_default',
  name: 'Zixflow Notifications',
  importance: AndroidImportance.HIGH,
});

Use the same channel ID in notifee.displayNotification({ android: { channelId: 'zixflow_default', ... } }). Manifest io.customer.notification_channel_* meta-data does not configure this notifee channel.

When the native Zixflow SDK displays the notification

Zixflow creates one channel per app when the first Zixflow push is delivered (unless you customize it via manifest meta-data).

Setting	Default
Channel ID	Your app `packageName`
Channel name	`{App name} Notifications`
Importance	`3` (default / high)

Importance levels: 0 min, 1 low, 2 medium, 3 default/high, 4 urgent.

Customize native SDK channel in AndroidManifest

Set meta-data under <application> before you ship a build that creates the channel. After users have the channel, Android only lets you reliably change the name; ID and importance are sticky for that channel ID.

<manifest>
  <application>
    <meta-data
      android:name="io.customer.notification_channel_id"
      android:value="zixflow_default" />
    <meta-data
      android:name="io.customer.notification_channel_name"
      android:value="Product Updates" />
    <meta-data
      android:name="io.customer.notification_channel_importance"
      android:value="4" />
  </application>
</manifest>

Use these exact android:name strings — the native SDK reads those keys. Changing the displayed android:value for name is supported after release; changing ID/importance for an existing channel generally has no effect for users who already have that channel.

If you previously shipped with an undesired channel ID, Android allows deleting a channel and creating another with new settings. Do this carefully in native code (users lose prior preference for the old ID):

val notificationManager =
  getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
notificationManager.deleteNotificationChannel(oldChannelId)

Deep Links

Deep links send users to a specific screen when they tap a push (or an action button). The React Native example opens them in JS after tracking:

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

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

See Push Notification Tracking — Deeplink opening for the full open / action / payload contract. Also configure native URL handling if you use a custom scheme or universal links:

Android

Add intent filters on your main activity in AndroidManifest.xml:

<intent-filter android:label="deep_linking_filter">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="yourapp"
    android:host="home" />
</intent-filter>

Optional HTTPS app links:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="yourapp.com" />
</intent-filter>

Push click behavior (Android)

Control activity recreation when a notification is tapped:

import {
  Zixflow,
  ZixflowConfig,
  PushClickBehaviorAndroid,
} from 'zixflow-reactnative';

const config: ZixflowConfig = {
  apiKey: 'YOUR_API_KEY',
  push: {
    android: {
      pushClickBehavior: PushClickBehaviorAndroid.ActivityPreventRestart,
    },
  },
};

await Zixflow.initialize(config);

Value	Behavior
`ActivityPreventRestart` (default)	Reuse the foreground activity when possible
`ActivityNoFlags`	Recreate / stack a new activity on tap
`ResetTaskStack`	Clear task stack and launch fresh

Opened metrics are tracked for all options when using the default Zixflow push path.

iOS

App scheme

In Xcode → target Info → URL Types, add your scheme (for example yourapp).
Forward opens to React Native:

func application(
  _ app: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  return RCTLinkingManager.application(app, open: url, options: options)
}

Zixflow push handling forwards deep links from Zixflow notifications into this path when using the recommended AppDelegate wrapper.

Universal Links

Follow React Native’s Linking / associated domains setup for https:// links that should open the app when installed.

import { NavigationContainer } from '@react-navigation/native';

const linking = {
  prefixes: ['yourapp://', 'https://yourapp.com'],
  config: {
    screens: {
      Home: 'home',
      Product: 'product/:id',
      Profile: 'profile',
    },
  },
};

export default function App() {
  return (
    <NavigationContainer linking={linking}>
      {/* stack */}
    </NavigationContainer>
  );
}

Payload link fields

Use deeplink_url for body taps and action_buttons[].deeplink for action taps (fallback to deeplink_url). Open them with handleDeeplink after tracking — see Push Notification Tracking. If deep links fail when the app was killed on iOS, see Troubleshooting.

Multiple Push Providers

The example app uses @react-native-firebase/messaging + @notifee/react-native for receive and display, and tracks opens/actions in JS. If another library also receives FCM, avoid double display and double metrics.

Option 1: Display yourself (Firebase + notifee)

Own display with notifee (or similar), then:

Track opened / action clicked with trackMetric / track (see Push Notification Tracking)
Optionally track delivered with trackMetric(Delivered), or forward for tracking only:

import { Zixflow } from 'zixflow-reactnative';

// Track without Zixflow generating another notification:
await Zixflow.pushMessaging.onMessageReceived(remoteMessage, false);

Do not call onMessageReceived(..., true) if notifee already displayed the same message.

Option 2: Forward payloads for Zixflow to display

import { Zixflow } from 'zixflow-reactnative';

const handled = await Zixflow.pushMessaging.onMessageReceived(remoteMessage);
// handled === true → Zixflow recognized and processed the push

Argument	Meaning
`message`	Incoming remote message
`handleNotificationTrigger`	Default `true`: Zixflow may display + track. Pass `false` to track without a local notification.

Background helper (avoids duplicate display when FCM already showed a notification payload):

await Zixflow.pushMessaging.onBackgroundMessageReceived(remoteMessage);

Example with `@react-native-firebase/messaging`

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

// Foreground — only if Zixflow should display (not when using notifee):
messaging().onMessage(async (remoteMessage) => {
  await Zixflow.pushMessaging.onMessageReceived(remoteMessage);
});

// Background (index.js) — same caveat:
messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  await Zixflow.pushMessaging.onBackgroundMessageReceived(remoteMessage);
});

Option 3: Register Zixflow’s FCM service

Hand Android FCM delivery to Zixflow by declaring the service in AndroidManifest.xml under <application>:

<service
  android:name="com.zixflow.messagingpush.ZixflowFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

Prefer Option 1 when your app displays notifications with notifee (as in the example).

Identify Users

await Zixflow.identify('user@example.com', {
  email: 'user@example.com',
  first_name: 'Demo',
});

On logout:

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

Testing

Register token + identify a test user
Send a push from the Zixflow dashboard (include action_buttons to test buttons)
Use a physical iOS device
Enable ZixflowLogLevel.Debug during development

Full sample: sdk-examples/react-native.

Getting Started

Features

Advanced

Reference

Prerequisites

Dependencies

Architecture

Initialize handlers

Display with notifee (including action buttons)

Open and action tracking

Custom Action Buttons — iOS category

iOS Capabilities

App Groups

Android Setup

Notification Channels

When you display with notifee (example path)

When the native Zixflow SDK displays the notification

Customize native SDK channel in AndroidManifest

Deep Links

Android

Push click behavior (Android)

iOS

App scheme

Universal Links

React Navigation

Payload link fields

Multiple Push Providers

Option 1: Display yourself (Firebase + notifee)

Option 2: Forward payloads for Zixflow to display

Example with `@react-native-firebase/messaging`

Option 3: Register Zixflow’s FCM service

Identify Users

Testing

​Prerequisites

​Dependencies

​Architecture

​Initialize handlers

​Display with notifee (including action buttons)

​Open and action tracking

​Custom Action Buttons — iOS category

​iOS Capabilities

​App Groups

​Android Setup

​Notification Channels

​When you display with notifee (example path)

​When the native Zixflow SDK displays the notification

​Customize native SDK channel in AndroidManifest

​Deep Links

​Android

Push click behavior (Android)

​iOS

App scheme

Universal Links

​React Navigation

​Payload link fields

​Multiple Push Providers

​Option 1: Display yourself (Firebase + notifee)

​Option 2: Forward payloads for Zixflow to display

Example with @react-native-firebase/messaging

​Option 3: Register Zixflow’s FCM service

​Identify Users

​Testing

Prerequisites

Dependencies

Architecture

Initialize handlers

Display with notifee (including action buttons)

Open and action tracking

Custom Action Buttons — iOS category

iOS Capabilities

App Groups

Android Setup

Notification Channels

When you display with notifee (example path)

When the native Zixflow SDK displays the notification

Customize native SDK channel in AndroidManifest

Deep Links

Android

iOS

React Navigation

Payload link fields

Multiple Push Providers

Option 1: Display yourself (Firebase + notifee)

Option 2: Forward payloads for Zixflow to display

Example with `@react-native-firebase/messaging`

Option 3: Register Zixflow’s FCM service

Identify Users

Testing