kewa-react-native-notifications

React Native SDK for Kewa mobile push notifications. It requests notification permission, registers the device with Kewa using the contact ktc_id from kewa-react-native, and displays incoming Firebase messages with the iOS and Android options configured in Kewa.

Overview

This package is the mobile client for Kewa’s Firebase notification channel. It works with kewa-react-native in the same app:

1. kewa-react-native identifies the contact and stores ktc_id.
2. This package reads appUrl and projectId from that SDK.
3. After permission is granted, the device FCM token is registered against that ktc_id.
4. The device is subscribed to the Firebase topic contact_{ktc_id}.
5. When Kewa sends a mobile notification, the app receives and displays it.

kewa-react-native                kewa-react-native-notifications
KewaProvider                     KewaNotificationProvider
appUrl + projectId  ──────────▶  firebase-project-id
ktc_id              ──────────▶  FCM token registration
                                         │
                                         ▼
                                       Kewa
                    {appUrl}/t/{projectId}/notification/…
                                         │
                                         ▼
                              Firebase → device

Kewa endpoints used by this package (fixed; built from kewa-react-native config):

| Purpose | URL | | --- | --- | | Subscribe popover settings | {appUrl}/t/{projectId}/notification/mobile-config | | Device registration | {appUrl}/t/{projectId}/notification/appcallback |

Dependencies

Required packages

| Package | Role | | --- | --- | | kewa-react-native >=1.0.5 | Provides appUrl, Kewa projectId, and ktc_id | | @react-native-firebase/app >=21 | Firebase app initialization | | @react-native-firebase/messaging >=21 | FCM token and message delivery | | @notifee/react-native >=9 | Local notification display (iOS / Android options) | | react >=18 | Peer | | react-native >=0.73 | Peer |

Install:

npm install kewa-react-native kewa-react-native-notifications \
  @react-native-firebase/app @react-native-firebase/messaging @notifee/react-native

Host app requirements

| Requirement | Notes | | --- | --- | | Bare React Native or Expo development build | Expo Go is not supported (native modules) | | Firebase project | Same project as Kewa’s Firebase notification integration | | Android google-services.json | Placed under android/app/ | | iOS GoogleService-Info.plist | Added to the Xcode project | | Native rebuild | Required after adding Firebase / Notifee |

Kewa requirements

• Firebase notification integration published
• Firebase selected as the notification transport
• Service account and web/mobile keys configured for the same Firebase project as the app
• Subscribe popover copy configured in notification settings (used by the default permission UI)

Configuration

Props

KewaNotificationProvider reads Kewa connection details from kewa-react-native. Pass only Firebase and UI options here:

| Prop | Type | Default | Description | | --- | --- | --- | --- | | firebase-project-id | string | required | Firebase project id. Must match the app’s Firebase config and Kewa’s Firebase integration. | | autoTriggerNotification | boolean | false | Shows the subscribe popover when the provider mounts. | | androidSmallIcon | string | 'ic_launcher' | Default Android small icon drawable when the notification does not set one. | | displayNotifications | boolean | true | Shows incoming notifications with the built-in UI. Set false to handle them yourself. See Custom handling. | | onNotification | (notification, message) => void \| Promise<void> | — | Called for every Kewa message with the parsed notification and the raw Firebase message. |

appUrl and Kewa projectId come from KewaProvider / Kewa.init and are not configured on this provider.

Example

import { KewaProvider } from 'kewa-react-native';
import { KewaNotificationProvider } from 'kewa-react-native-notifications';

export function Root() {
  return (
    <KewaProvider
      config={{
        appUrl: 'https://acme.example.com',
        projectId: 'acme',
        apiKey: 'your-api-key',
      }}
    >
      <KewaNotificationProvider
        firebase-project-id="acme-firebase"
        autoTriggerNotification
      >
        <App />
      </KewaNotificationProvider>
    </KewaProvider>
  );
}

Setup

Complete these steps in order.

1. Kewa

1. Open Plugins / Integrations and publish Firebase.
2. Set Firebase as the notification transport.
3. Confirm the Firebase project matches the one used by the mobile app.
4. Configure subscribe popover text under notification configuration (title, body, allow / deny labels, duration).

2. Android

1. In Firebase Console, add an Android app with the app package name.
2. Download google-services.json into android/app/.
3. Apply the Google Services plugin:
   • Root android/build.gradle: Google Services classpath
   • App android/app/build.gradle: apply plugin: 'com.google.gms.google-services'
4. Confirm minSdkVersion meets React Native Firebase and Notifee requirements.
5. Rebuild: npx react-native run-android.

Optional assets:

• Sounds: android/app/src/main/res/raw/
• Small icons: drawable resources referenced by Kewa’s android_small_icon

Reference: React Native Firebase — Android, Notifee — installation.

3. iOS

1. In Firebase Console, add an iOS app with the app bundle id.
2. Download GoogleService-Info.plist into the Xcode project.
3. In Xcode → Signing & Capabilities:
   • Add Push Notifications
   • Add Background Modes and enable Remote notifications
4. Create an APNs authentication key in the Apple Developer account and upload it to Firebase Console → Project settings → Cloud Messaging.
5. Install pods: cd ios && pod install (or npx pod-install).
6. Rebuild: npx react-native run-ios.

Optional assets:

• Sounds: files in the iOS app bundle, matching Kewa’s ios_sound value

Reference: React Native Firebase — iOS, Notifee — installation.

4. Application entry

Register the background handler before the root component. This is required for background delivery on Android.

import { AppRegistry } from 'react-native';
import { registerKewaBackgroundHandler } from 'kewa-react-native-notifications';
import App from './App';
import { name as appName } from './app.json';

registerKewaBackgroundHandler();
AppRegistry.registerComponent(appName, () => App);

app.json is the standard React Native app metadata file (name / displayName). Use its name with AppRegistry, or pass the app name as a string. It is not a Kewa or Firebase setting.

registerKewaBackgroundHandler accepts the same displayNotifications and onNotification options as the provider. Background messages run without the React tree, so provider props do not apply to them. See Custom handling.

5. Providers

Wrap the tree with KewaProvider, then KewaNotificationProvider, as shown in Configuration.

Permission

requestNotificationPermission must be called after KewaNotificationProvider is mounted. It returns 'granted' | 'denied'.

The package:

1. Shows a subscribe popover (Kewa copy by default)
2. Requests OS notification permission when the person allows
3. Fetches the FCM token
4. Registers the token with Kewa when ktc_id is available

Basic usage

import { requestNotificationPermission } from 'kewa-react-native-notifications';

const result = await requestNotificationPermission();

Optional callbacks

onAllow and onReject are optional. Use them only for app-specific side effects (analytics, UI). Registration still runs without them.

await requestNotificationPermission({
  onAllow: () => {},
  onReject: () => {},
});

Auto-trigger on launch

<KewaNotificationProvider
  firebase-project-id="acme-firebase"
  autoTriggerNotification
>

Equivalent to calling requestNotificationPermission() once on mount. If permission is already granted, the popover is skipped and registration continues when ktc_id is ready.

Custom popover copy

await requestNotificationPermission({
  popup: {
    title: 'Order updates',
    text: 'Allow notifications for shipping updates.',
    buttonText: 'Allow',
    denyButtonText: 'Not now',
    duration: 0,
  },
});

duration is seconds. 0 keeps the popover open until the person chooses. On timeout, the result is 'denied'.

Custom popover component

await requestNotificationPermission({
  renderPopup: ({ settings, onAllow, onReject }) => (
    <MyPrompt
      title={settings.title}
      message={settings.text}
      allowLabel={settings.buttonText}
      denyLabel={settings.denyButtonText}
      onAllow={onAllow}
      onReject={onReject}
    />
  ),
});

The onAllow / onReject props from renderPopup must be called from the custom UI to continue the permission flow. They are separate from the optional top-level onAllow / onReject callbacks.

Registration behavior

After permission is granted:

1. FCM token is obtained
2. Package waits for ktc_id from kewa-react-native
3. Device is subscribed to contact_{ktc_id}
4. Token is posted to {appUrl}/t/{projectId}/notification/appcallback
5. Token refresh and ktc_id changes re-run registration (and switch topics when the contact id changes)

Incoming notifications

Kewa mobile notifications are delivered as FCM data messages. This package displays them with the configured platform options:

| Kewa field | Behavior | | --- | --- | | Heading, message, URL, button | Title, body, and an action that opens the URL | | iOS subtitle, sound, media | Subtitle, sound, image attachment | | iOS badge set / increment | Sets or increments the badge | | iOS content available | Silent delivery when there is no title or body | | Android sound, small icon, large icon, big picture | Channel sound, icons, big-picture style | | Android LED / accent color | Lights and accent | | Android group key | Notification group | | Android lock screen visibility | Public, private, or secret | | Additional data | Included on the notification data payload |

Listeners

import {
  onKewaNotification,
  onKewaNotificationOpened,
} from 'kewa-react-native-notifications';

const unsubscribeReceived = onKewaNotification((notification) => {
  console.log(notification.title, notification.data);
});

const unsubscribeOpened = onKewaNotificationOpened((notification) => {
  // navigate using notification.actionUrl or notification.data
});

Opening a notification reports source: mobile.open to Kewa for the current ktc_id.

Custom handling

Set displayNotifications={false} to turn off the built-in display and handle each message in onNotification. The callback receives the parsed notification and the raw Firebase message. The full Kewa JSON is in message.data.kewa. The callback also runs when the default display is on.

<KewaNotificationProvider
  firebase-project-id="acme-firebase"
  displayNotifications={false}
  onNotification={(notification, message) => {
    const payload = JSON.parse(String(message.data?.kewa ?? '{}'));
    // show an in-app banner, navigate, store, or display with your own Notifee options
  }}
>

Apply the same options to background and quit-state messages in the entry file:

registerKewaBackgroundHandler({
  displayNotifications: false,
  onNotification: async (notification, message) => {
    // no React tree here: no navigation or UI state
  },
});

If you display notifications yourself with Notifee, pass notification.data, plus notification_id and action_url, as the Notifee data. Kewa open tracking and onKewaNotificationOpened then keep working when the person taps them.

API

| Export | Description | | --- | --- | | KewaNotificationProvider | Provider for permission UI, listeners, and registration | | registerKewaBackgroundHandler | Background message handler; call from the app entry file. Accepts displayNotifications and onNotification | | requestNotificationPermission | Shows the popover and requests OS permission | | onKewaNotification | Listener for received notifications | | onKewaNotificationOpened | Listener for notification opens | | openNotificationSettings | Opens the system notification settings screen | | readKtcId | Returns the current ktc_id from kewa-react-native | | SubscribePrompt | Default popover component |

Notes

• iOS does not deliver background data messages after the app is force-quit. Delivery resumes after the next launch.
• Android background display requires registerKewaBackgroundHandler() in the entry file.
• Custom sounds and Android small icons must exist as native assets in the host app.