---
title: "MappPushHelper Reference"
slug: "mapppushhelper-reference-react-native-engage"
updated: 2026-09-03T14:22:46Z
published: 2026-09-03T14:22:46Z
canonical: "docs.mapp.com/mapppushhelper-reference-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.

# MappPushHelper Reference

`MappPushHelper` is a native Android API for applications that own a custom `FirebaseMessagingService`. It runs without a React Native JavaScript runtime, which makes it the reliable way to forward Mapp push messages and FCM tokens while your application is backgrounded or terminated.

If your application uses the plugin's default Firebase service, you do not need this API. It only applies once you have selected custom push ownership — in Expo, by setting `android.pushHandling` to `"custom"`; in React Native CLI, by registering your own `FirebaseMessagingService` and removing the plugin's default service.

## Methods

| Method | Purpose | Replaces in a native Firebase service |
| --- | --- | --- |
| `MappPushHelper.initialize(application)` | Safely engages Mapp on the main looper and waits for the bounded initialization attempt. | Direct background calls to `Appoxee.engage(...)`. |
| `MappPushHelper.isMappMessage(remoteMessage)` | Returns whether a native `RemoteMessage` belongs to Mapp. | Converting the message to JSON and calling `Mapp.isPushFromMapp(...)`. |
| `MappPushHelper.handleMessage(application, remoteMessage)` | Initializes Mapp when needed and forwards a Mapp message. Returns `true` only when the message was handled by Mapp. | `Mapp.setRemoteMessage(...)` for background and terminated delivery. |
| `MappPushHelper.handleNewToken(application, token)` | Initializes Mapp when needed and forwards a new FCM token. | Calling `Mapp.setToken(...)` from a Firebase token callback. |
| `MappPushHelper.waitUntilReady()` | Waits for the already-engaged SDK to become ready, for a bounded period. | Application-owned polling of `Mapp.isReady()`. |

---

## Usage example

Implement your `FirebaseMessagingService` and delegate to `MappPushHelper`:

```java
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import com.reactlibrary.MappPushHelper;

public final class ApplicationMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage message) {
        if (!MappPushHelper.handleMessage(getApplication(), message)) {
            // Handle non-Mapp messages.
        }
    }

    @Override
    public void onNewToken(String token) {
        MappPushHelper.handleNewToken(getApplication(), token);
    }
}
```

---

## Why not the JavaScript methods

`Mapp.setRemoteMessage()`, `Mapp.isPushFromMapp()`, and `Mapp.setToken()` remain supported, but only while JavaScript is guaranteed to be running. They are not reliable while your application is backgrounded or terminated, because there may be no JavaScript runtime available to call into. `MappPushHelper` runs entirely in native code and has no such dependency.

> [!NOTE]
> Note
> 
> For the full list of behavior changes in 2.0.0, see [Breaking Changes in 2.0.0](/docs/en/breaking-changes-2-0-0-react-native-engage).