Configure mobile push notifications

This guide walks you through creating and configuring mobile push notifications in Bloomreach. Learn how to use the notification editor, configure settings, send test notifications, and build advanced notifications using the code builder.

Before you start, ensure you complete the setup steps in Mobile push notifications.

Use notification editor

Create mobile push notifications in scenarios.

1. Go to Campaigns > Scenarios and select Mobile Push Notification under Actions on the left side.

2. Double-click the action node to open the notification builder.

   

3. Work in the default visual editor or switch to the code builder for advanced configurations.

In the notification editor, select which app the notification targets. The platform integrations associated with that app are used when sending the notification.

Set interaction behavior

In the Interaction section, choose what happens when a user taps the notification. There are three action types:

• Open application: Opens your mobile app.
• Open browser: Opens a URL in the device's web browser. You must define the target URL.
• Open deeplink: Opens a specific screen in your app. You must define the deeplink URL. Learn more about handling deeplinks.

Add media

In the Media section, you can attach an image to display in the notification or set a sound to play when it arrives.

Preview notifications

On the right side of the editor, preview how your notification looks on Android and iOS — for individual customers or filtered segments. Enter a customer's email address in the preview field, or use the filter icon to select a segment. This is useful when you use personalization, as it lets you verify that different customers see different content as intended.

Set character limits

Bloomreach doesn't enforce a character limit, but follow these recommendations for the best user experience:

• iOS: No more than 230 characters.
• Android: No more than 500 characters.
• Both platforms: Keep notification text under 50 characters for optimal readability.

Set image sizes

Follow these image guidelines per platform.

iOS

• Maximum dimensions: 1,038 x 1,038 pixels.
• Images taller than 1,038 pixels are downscaled with padding to appear square.
• Use landscape orientation. Portrait images are often resized or cropped.

Android

• Maximum dimensions: 800 x 1,038 pixels.
• Use landscape orientation. Rich push notifications on Android are cropped to approximately 16:9, though the exact ratio varies by device.
• GIF images are not supported.

iOS and Android

Images can be cropped across both platforms. Avoid placing important content at the edges of the image or using edge-to-edge text.

📘

Note

The Bloomreach editor displays fonts in left-to-right formatting. The actual notification follows the user's device language settings. For example, a notification sent to a user with a right-to-left language setting displays in right-to-left formatting, regardless of how it appears in the editor.

Add emojis

On Windows, add emojis to your push notification by right-clicking in the text field or pressing Win + . (Windows key and full stop).

Configure notification settings

The Settings tab contains standard campaign settings covered in the email campaigns article, plus four settings specific to mobile push notifications.

Set notification priority

Android devices in low-power mode block the delivery of notifications with normal priority. High priority is selected by default for all push notifications to ensure immediate delivery, even to devices in low-power mode.

Fix UTM parameters and deep links

From version 1.288, Bloomreach automatically adds UTM parameters to deep links when Auto link transformation is selected.

If your deep links stop working after this update:

1. Open the push notification settings.
2. Change Link transformation from Auto to Manual.
3. Clear all values from the UTM input fields.

This ensures your deep links work without automatic UTM parameter addition.

Send test push notifications

Test how your notification looks on a real device before sending it to customers. Click Test push notification in the editor to send the notification to the customer selected in the preview field. Choose which push integration to test: All, iOS, Android (Firebase), or Android (Huawei).

Customer property tokens

To receive a test push notification, the target customer must have a push token stored in their profile. The attribute name differs by platform:

• iOS: apple_push_notification_id
• Android — Firebase Cloud Messaging: google_push_notification_id
• Android — Huawei Push Service: huawei_push_notification_id

❗️

Warning

The error Customer property "google_push_notification_id" is missing means the push token isn't stored in the customer's profile attributes.

To learn how to track push tokens from your SDK, see the push notifications configuration guide for your platform in SDK installation guides.

Integration testing helper

Bloomreach provides a dedicated route for developers to verify that push notification implementation is working correctly. When called, this route triggers a test push notification, letting you confirm that all parts of the push notification flow — from Bloomreach to the device — are functioning as expected.

Send a silent push notification

A silent push notification delivers a payload to a user's device without displaying a visible notification. This is useful for checking whether a customer still has your app installed. If a silent notification fails to deliver multiple times, the customer has likely uninstalled the app.

📘

Note

Silent push notifications require SDK version 2.8.0 or higher for Android and 2.7.0 or higher for iOS.

Build a notification with the code builder

For advanced use cases, switch to the code builder to build push notifications using JSON. The code builder gives you full control over notification structure and behavior.

You can define three action types:

• app — Opens the application.
• browser — Opens a URL in the device's web browser. Define the target URL in the url field.
• deeplink — Opens a specific screen in your app. Define the deeplink URL in the url field.

Open browser example

{
    "title": "Notification title",
    "message": "Notification text",
    "action": "browser",
    "url": "http://exponea.com",
    "actions": [
        {
            "title": "Open",
            "action": "app"
        },
        {
            "title": "Go to website",
            "action": "browser",
            "url": "https://exponea.com"
        },
        {
            "title": "Cancel",
            "action": "deeplink",
            "url": "exponea://notifications.actions.cancel/fe80c8b8c5fffe62aa10"
        }
    ],
    "image": "https://exponea.com/icon.png",
    "sound": "beep.wav",
    "attributes": {
        "age": 24,
        "gender": "male"
    }
}

Open app example

{
    "title": "Notification title",
    "message": "Notification text",
    "action": "app",
    "actions": [
        {
            "title": "Open",
            "action": "app"
        },
        {
            "title": "Go to website",
            "action": "browser",
            "url": "https://exponea.com"
        },
        {
            "title": "Cancel",
            "action": "deeplink",
            "url": "exponea://notifications.actions.cancel/fe80c8b8c5fffe62aa10"
        }
    ],
    "image": "http://exponea.com/icon.png",
    "sound": "beep.wav",
    "attributes": {
        "age": 24,
        "gender": "male"
    }
}

iOS custom payload

Limitations for iOS 11 and lower

iOS versions lower than 12 don't support rendering push notification actions directly from the received payload. To support actions on these versions, enable legacy iOS actions and add the legacy_ios_category attribute to the push notification payload. Your development team should follow the iOS custom notification actions guide.

{
    "legacy_ios_category": "category_id",
    "title": "Notification title",
    "message": "Notification text",
    "action": "app",
    "actions": [
        {
            "title": "Open",
            "action": "app"
        }
    ]
}

Track campaign events

Mobile push campaigns generate campaign events with action_type = mobile notification for all customers in the campaign audience. These events cover the full delivery lifecycle — from Bloomreach sending the push to the customer's device receiving or clicking it.

The delivered status attribute in the campaign event is tracked immediately after the push notification is delivered to the device. For the full structure of campaign events, see System events.

You can map campaign events to a different event name under Project settings > Campaigns > Mapping > Campaign events.

• iOS devices previously tracked delivered events only after the app was opened, which could happen too late or not at all. The current implementation tracks delivered events immediately after delivery for all push notifications. Due to iOS technical constraints — 12–15MB of RAM and 30 seconds of processing time — this tracking may not be 100% reliable. Rich push notifications are required for delivered event tracking on iOS. Sent and failed statuses are tracked server-side. Delivered and clicked statuses are tracked from the app via the SDK.
• Each UTM parameter is tracked as a separate attribute of the session_start event — for example, utm_source, utm_medium, and utm_campaign. This is consistent with JavaScript SDK tracking and aligned with UTM tracking across all SDKs.