Overview

This guide explains how to configure push messaging using the Mapp Engage Android SDK v7 in an Android application.

It covers:

Using Mapp Engage as the only push provider
Using Mapp Engage alongside another SDK that also uses Firebase Cloud Messaging (FCM)

This guide focuses on the SDK configuration required to receive push notifications in your app.

Prerequisite:
The Mapp Engage Android SDK must already be installed and initialized in your application.

Setting Up Push Messaging When Using Only Mapp as Push Provider

If you are using Mapp Engage as your only push provider, the setup is straightforward. To receive push messages in your Android application, complete the following steps.

1. Configure Firebase

Create a Firebase project.
Register your Android application within the project.
Download the google-services.json file.
Add the file to your app module.

Complete the steps in Enable Firebase Cloud Messaging before continuing.

Android 13+ (API 33+):
Your app must request the POST_NOTIFICATIONS runtime permission before notifications can be displayed.

2. Configure Push in Mapp Engage

Create and configure a push channel in Mapp Engage.
Ensure the channel is properly connected to your Firebase project.

Refer to Enable Android Channel in Mapp Engage for details on channel configuration and message setup.

3. (Optional) Subscribe to Push Events

If your implementation requires handling push-related events, subscribe to them as described in Setting Up a Notification Broadcast Receiver.

4. (Optional) Customize Notification Icons

Android notifications can be customized by defining small and large icons.

Small Icon

Must be a monochrome drawable
Must be placed in res/drawable
Adaptive launcher icons from the mipmap folder are not supported
If no small icon is provided, a default notification icon is used

Android requires a small icon for every notification.

Large Icon (Optional)

Supports PNG or JPEG images
If not provided, no large icon is displayed

After creating the required resources, declare them inside the <application> tag of your AndroidManifest.xml:

<application ...>

    <meta-data
        android:name="com.engage.mapp_notification_small_icon"
        android:resource="@drawable/mapp_notification_small_icon" />

    <meta-data
        android:name="com.engage.mapp_notification_large_icon"
        android:resource="@drawable/mapp_notification_large_icon" />

    <meta-data
        android:name="com.engage.mapp_notification_small_icon_color"
        android:resource="@color/your_color" />

</application>

Send Your First Push Notification

After completing the configuration:

Install the app on a test device.
Ensure the device is registered and can receive Firebase push notifications.
In Mapp Engage, create a push message.
Target your test device or a test audience.
Send the message and confirm it appears on the device.

If the notification is not delivered, verify your Firebase configuration, device registration, and channel setup in Mapp Engage.

Setting Up Push Messaging with Multiple Providers

If your application already uses another push provider, additional configuration is required to avoid conflicts between Firebase messaging services.

Only one FirebaseMessagingService should actively handle incoming Firebase messages. Having multiple active services may lead to race conditions or unexpected behavior. In practice, ensure only one service is registered for com.google.firebase.MESSAGING_EVENT in the merged manifest.

Note
The Android SDK APIs and package names may still use the Appoxee namespace. This is expected and refers to the Mapp Engage Android SDK.

1. Disable Mapp’s Default Firebase Messaging Service

When using a custom Firebase messaging service, disable the default service provided by the Mapp Engage Android SDK.

Add the following inside the <application> tag of your AndroidManifest.xml:

<application
    xmlns:tools="http://schemas.android.com/tools"
    ...>

    <service
        android:name="com.appoxee.shared.MappMessagingService"
        tools:node="remove" />

</application>

The tools:node="remove" attribute removes the default Mapp messaging service from the merged manifest.

2. Create a Custom Firebase Messaging Service

Create a custom service to handle Firebase messages and ensure that messages intended for Mapp Engage are properly forwarded to the SDK.

Two approaches are supported.

Recommended: Extend MappMessagingService

The preferred approach is to extend the SDK’s MappMessagingService. This ensures proper integration and reduces the risk of incorrect message handling.

public class MyMessageService extends MappMessagingService {

    @Override
    public void onNewToken(@NonNull String token) {
        super.onNewToken(token);
        // Additional logic if required
    }

    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        super.onMessageReceived(remoteMessage);
        // Additional logic if required
    }
}

<application ...>

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

</application>

Alternative: Extend FirebaseMessagingService Directly

If you extend FirebaseMessagingService directly, you must manually forward relevant messages to the Mapp Engage Android SDK.

public class MyMessageService extends FirebaseMessagingService {

    @Override
    public void onNewToken(@NonNull String token) {
        super.onNewToken(token);
        Appoxee.instance().updateFirebaseToken(token);
    }

    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        if (Appoxee.instance().isPushMessageFromMapp(remoteMessage)) {
            Appoxee.instance().handlePushMessage(remoteMessage);
        } else {
            // Handle messages from other providers here
        }
    }
}

<application ...>

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

</application>

Important

Ensure that:

Only one Firebase messaging service is active in the merged manifest.
The Firebase token is properly forwarded to the Mapp Engage Android SDK.
Push messages intended for Mapp Engage are correctly identified and handled.
The same setup principles are consistently applied to any additional push providers used in your application.

Ensure that your custom service forwards messages to the Mapp Engage Android SDK as required by your implementation.

Notification Limitations

A notification can contain up to three action buttons that allow users to respond quickly (for example, snooze a reminder or reply to a message).
Action buttons must not duplicate the primary action triggered when the user taps the notification.

For detailed design and behavior guidelines, refer to the official Android documentation.

In-app messaging

In-app messaging is configured separately from push notifications.

To use in-app messaging:

Ensure the Android channel is enabled in Mapp Engage.
Ensure required trigger events are tracked via the SDK.
See:

Push Messaging Setup