---
title: "Push Notifications"
slug: "push-notifications-react-native-engage"
updated: 2026-09-03T14:22:05Z
published: 2026-09-03T14:22:05Z
canonical: "docs.mapp.com/push-notifications-react-native-engage"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```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:

```javascript
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);
```

> [!NOTE]
> Note
> 
> This JavaScript-based routing only runs reliably while your app's JavaScript is alive. Since 2.0.0, for background and terminated delivery, implement a native `FirebaseMessagingService` and forward through `MappPushHelper` instead — see the [MappPushHelper reference](/docs/en/mapppushhelper-reference-react-native-engage).

### FCM Token

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

```javascript
await Mapp.setToken('your-fcm-token');

try {
  const token = await Mapp.getToken();
} catch (error) {
  // Since 2.0.0, getToken() rejects on failure instead of crashing.
  // Handle unavailable FCM registration.
}
```

### Notification Permission (Android 13+)

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

```javascript
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:

```javascript
// Call before Mapp.engage()
Mapp.setPostponeNotificationRequest(true);
await 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:

```javascript
Mapp.setShowNotificationsAtForeground(true);
```

## Enable and Disable Push

Available on both platforms.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
const granted = await Mapp.requestGeofenceLocationPermission();
if (granted) {
  await Mapp.startGeofencing();
}

// Stop monitoring
await Mapp.stopGeofencing();
```

> [!NOTE]
> Note
> 
> Since 2.0.0, `requestGeofenceLocationPermission()` can display system permission dialogs on Android instead of only checking the current state. Call it from a clear user interaction, after explaining why your app needs location access. `startGeoFencing()`/`stopGeoFencing()` still work but are deprecated in favor of the `startGeofencing()`/`stopGeofencing()` spelling used above.

## Clear Notifications

Remove delivered notifications from the notification tray.

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

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