Push Notifications

Introduction

The plugin handles push notifications on Android via Firebase Cloud Messaging (FCM) and on iOS via APNs. This page covers platform-specific configuration, permission handling, push event listeners, deep links, and geofencing.

Android

Default Setup

The plugin registers a Firebase Messaging Service automatically. No additional configuration is required for standard push delivery.

Custom Firebase Integration

When your app uses multiple Firebase services or a custom FirebaseMessagingService, disable the default Mapp service and route messages manually.

In AndroidManifest.xml:

<service android:name=".MessageService"
         android:exported="false"
         tools:node="remove">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Route Mapp messages in your handler:

import FBMessaging from '@react-native-firebase/messaging';
import { Mapp } from 'react-native-mapp-plugin';

const handleMessage = async (remoteMessage) => {
  const isFromMapp = await Mapp.isPushFromMapp(remoteMessage);
  if (isFromMapp) {
    Mapp.setRemoteMessage(remoteMessage);
  }
};

FBMessaging().onMessage(handleMessage);
FBMessaging().setBackgroundMessageHandler(handleMessage);

FCM Token

Set or retrieve the FCM token manually when managing token registration outside the plugin:

await Mapp.setToken('your-fcm-token');
const token = await Mapp.getToken();

Notification Permission (Android 13+)

Android 13 and above requires explicit permission to display notifications. Call this at an appropriate point in your onboarding flow.

const granted = await Mapp.requestPostNotificationPermission();
if (!granted) {
  // inform the user notifications are disabled
}

iOS

Permission Dialog

The system permission dialog appears during Mapp.engage() by default. To delay it:

// Call before Mapp.engage()
Mapp.setPostponeNotificationRequest(true);
Mapp.engage('', '', 'your-server', '', '');

// Trigger the dialog at the right moment
Mapp.showNotificationAlertView();

Foreground Notifications

By default, iOS suppresses notifications when the app is in the foreground. To display them:

Mapp.setShowNotificationsAtForeground(true);

Enable and Disable Push

Available on both platforms.

const enabled = await Mapp.isPushEnabled();
await Mapp.setPushEnabled(false); // opt out
await Mapp.setPushEnabled(true);  // opt in

Push Event Listener

Subscribe to push notification events (received, opened, dismissed) on both platforms.

const subscription = Mapp.addPushListener((pushMessage) => {
  console.log('Push event:', JSON.stringify(pushMessage));
});

// Remove when the component unmounts
subscription.remove();

Deep Links

Subscribe to deep link events triggered from a push notification.

const subscription = Mapp.addDeepLinkingListener((url) => {
  console.log('Deep link:', url);
});

subscription.remove();

GeoFencing

The SDK monitors geofence regions and fires configured push events when the device enters or exits a boundary. Request location permission before starting.

const granted = await Mapp.requestGeofenceLocationPermission();
if (granted) {
  await Mapp.startGeoFencing();
}

// Stop monitoring
await Mapp.stopGeoFencing();

Clear Notifications

Remove delivered notifications from the notification tray.

// Clear all notifications for the app
Mapp.clearNotifications();

// Clear a specific notification by identifier
Mapp.clearNotification('notification-id');