Mobile push notifications

Mobile push notifications are messages you send to your app users' phones. They can include text, images, and buttons.

More people use mobile apps every day, so mobile marketing is becoming more important. Push notifications give you another way to reach your customers. With our SDKs, you can connect Bloomreach Engagement to your mobile app and send personalized notifications to your users.

📘

Note

Mobile push notifications replace the old "Push Notification" feature, which we've deprecated. You can still use the old feature if it's already set up in your project. We support version 2.0.0 or higher for Android and iOS.

How push notifications work

set up push notification campaigns in Integrations and created them in Scenarios. Use the visual builder for simple campaigns or the code builder for advanced ones. Here's how it works:

1. Bloomreach Engagement sends push messages to push notification providers.
2. The providers deliver them to your users' phones.
3. Your mobile app uses our SDK to show the notification on the screen.

Set up push notifications

Before your app can receive and show notifications, you need to:

1. Install one of our mobile SDKs.
2. Set up push credentials

We provide SDKs for iOS and Android. Each platform has different setup steps. Generally, you'll:

1. Add an SDK to your mobile app.
2. Set it up with Bloomreach Engagement credentials.
3. Add specific credentials to your Bloomreach Engagement Project settings.
4. Get user consent and tokens.
5. Launch your first campaign.

For detailed setup instructions, follow the respective guides:

1. Install the SDK and its configuration with Bloomreach Engagement.

   1. iOS SDK : Push notifications configuration
   2. Android SDK : Push notifications configuration
   3. React Native SDK : Push notifications configuration
   4. Flutter SDK : Push notifications configuration
   5. MAUI SDK : Push notifications configuration
   6. Xamarin SDK : Push notifications Android configuration, Push notifications iOS configuration

2. Configure the Apple Development Centre (iOS), the Firebase platform (Android), or Huawei Push Service (Huawei Android) under Data & Assets > Integrations.

3. Select the wished integration in Project Settings > Campaigns > Channels > Push notifications.

Once you're done, you can send notifications to your app straight from Bloomreach Engagement.

👍

iOS SDK Integration Guide

Want to learn more about integrating iOS SDK? Watch the video guide.

Push notification integrations

You need a third-party service to send push notifications. To set up a connection with a push service, go to Data & Assets > Integrations.

These services receive push requests from Engagement and send them to users' phones using device push tokens. Push tokens are saved as customer profile attributes. Our SDK handles push token management and assigns the push token attribute to the customer profile when users subscribe to push notifications. Each push notification integration uses a different attribute name to save the token.

All mobile push services require an integration to be set up under Data & Assets > Integrations and then selected under Project settings > Campaigns > Channels > Push notifications. The integration selected in the project settings will then be used to send push notifications to the chosen devices (Android/iOS). When the integration is changed (and settings are saved), all push notification nodes from all scenarios will immediately use the selected integration.

There are 3 different push services that can be integrated, covering all device types (2 for Android, 1 for iOS).

Android push services

Android devices fall into two groups. Most devices use Google Play Store with Firebase Cloud Messaging. Newer Huawei devices use their own Huawei AppGallery and Huawei Push Service.

📘

Note

Huawei devices originally used Google Play Store and Firebase Cloud Messaging. Some older devices still use Firebase, but usage is decreasing. Newer Huawei devices use the new Huawei Mobile Services.

Firebase Cloud Messaging

We use Firebase Cloud Messaging (FCM) to send mobile push notifications to Android devices (except Huawei devices). To learn more about FCM, see Firebase Cloud Messaging.

• Token attribute name: google_push_notification_id
• SDK support: All
• Configuration guide

❗️

Warning

Google deprecated and removed the FCM legacy API in June 2024. Bloomreach Engagement now uses the new Firebase HTTP v1 API. To keep using Firebase to send push notifications to Android devices, you must add a new FCM integration.

Huawei Push Service

We use Huawei Push Service (HPC) to send mobile push notifications to Huawei Android devices. To learn more about HPC, see Huawei Push Kit.

• Token attribute name: huawei_push_notification_id
• SDK support: Android SDK 3.0.0 and higher or the latest versions of Flutter, Xamarin, and React native SDKs
• Configuration guide

iOS push service

We use Apple Push Notification service (APNs) to send mobile push notifications to iOS devices. For more information about this service, see APNs Overview

• Token attribute name: apple_push_notification_id
• SDK support: All
• Configuration guide

After setting up integrations, select the one you want under Project settings > Campaigns > Channels > Push notifications.

🚧

You can only store one iOS, one Android-Firebase, and one Android-Huawei device token in each customer profile. Customers with multiple devices can only receive one notification per platform, depending on which token is stored in Bloomreach Engagement.

Create a new notification

You create mobile push notifications in scenarios. Go to Campaigns > Scenarios, and on the left side, select Mobile Push Notification under Actions. When you double-click the action node, the notification builder opens. You can work with the default user-friendly interface or switch to coding mode (1).

Use the editor

In the INTERACTION section, you can choose 3 types of actions:

• Open application
• Open browser
• Open deeplink (how to handle deeplinks)

In the MEDIA section, you can set it to show an image in the notification or play a sound when it's received.eived.

On the right side, you can preview (2) how your notification looks on Android/iOS and for each individual customer. You can type a specific email address in the field or use the filter icon to filter a segment of customers to see the preview. This is especially useful when you use personalization to check whether the notification shows different text for different customers as specified.

Character limit

Bloomreach Engagement doesn't set a character limit, but we recommend roughly no more than 230 characters for iOS and 500 for Android. However, for the best user experience, your text shouldn't be longer than 50 characters.

🚧

Jinja limitation: use single quotes

When using Jinja in a push notification, always use single quotes in your Jinja code, never double quotes. Double quotes aren't currently supported and will cause an error.

Image size limit

iOS

The maximum possible dimensions are 1,038 pixels x 1,038 pixels.

• Images taller than 1,038 pixels will be downscaled with padding to give them a square appearance.
• We recommend using images with landscape orientation. Portrait orientation often results in the picture becoming resized or cropped.

Android

The maximum possible dimensions are 800 and 1,038 pixels.

• We recommend using images with landscape orientation, as rich push notifications on Android are cropped to something close to 16:9 (the exact ratio changes depending on the device).
• GIF images aren't supported on Android.

iOS and Android

Images can be cropped and it's not possible to accommodate all possible variants, so you should avoid adding important information to the edges of the image or having edge-to-edge text.

📘

Note

The Bloomreach Engagement editor always shows fonts in left-to-right formatting. However, the actual push notification is either left-to-right or right-to-left formatting according to the user's device settings. For example, with Arabic font, the Bloomreach Engagement editor shows the font from left to right, but if you send a push to a user who has their phone set up in right-to-left formatting, the notification is displayed in right-to-left formatting too.

Emojis in mobile push notifications

If you're using Windows, you can add emojis to push notifications by right-clicking. Or simply, press "win" + "."

Settings

The settings tab mainly contains the same elements as any other campaign. You can find them in the Email Campaigns Article. However, we list four additional settings made specifically for mobile push notifications here.

Fix UTM parameters and deep links

As of version 1.288, we've updated how UTM parameters work with deep links. UTM parameters are automatically added to deep links when "Auto" link transformation is selected.

If you're having issues with deep links after this update:

• Go to the push notification settings.
• Change the "Link transformation" setting from "Auto" to "Manual".
• Remove all values from the UTM input fields.
• This will ensure your deep links work without automatic UTM parameter addition.

We made this change to correct previous behavior where UTM parameters weren't being properly tracked for deep links.

Silent Push Notifications

You can send your customers a silent notification, which they won't see. This is useful, for example, if you want to check whether a particular customer still has your app. If the silent notification fails to be delivered multiple times, then it's likely the customer has uninstalled it.

📘

Note

Silent push notifications are supported from the SDK version 2.8.0. for Android and from 2.7.0. for iOS.

Deliverability

Android devices in low-power mode block the delivery of notifications with normal priority. We've added a Priority setting and all push notifications have High chosen as default. This ensures that messages are delivered immediately, even to devices in low-power mode.

Integration Testing Helper

A special route was implemented for integrators to test whether the push notification implementation is correct. The route will serve as a trigger for test messages. When a call is made, it sends a push notification allowing the developer to check whether all parts of the push notification are working correctly.

Send test push notifications

You can always test how the notification looks on an actual device. When you click the Test push notification button, Bloomreach Engagement will send the push notification to the user selected in the preview part. You can choose which push integration you want to test: All, iOS, Android (Firebase), or Android(Huawei).

Customer property

If you want to send push notifications to a customer, they must have a specific attribute that stores a token of the user. Its name is different for each platform:

• IOS: apple_push_notification_id
• Android - Firebase cloud messaging: google_push_notification_id
• Android - Huawei push service: huawei_push_notification_id

How to track attributes from SDK

To learn how to track the tokens, visit our guides for the respective SDK that you are using, listed in the section Installation and push setup.

❗️

Warning

Error Customer property "google_push_notification_id" is missing means that the push notification token isn't defined in the customer's attributes.

Campaign tracking

Mobile push campaigns generate campaign events with action_type = mobile notification for all customers in the campaign audience, covering actions from the push being sent from Bloomreach Engagement to the customer's device receiving or the customer clicking the push. The delivered status attribute in the campaign event is tracked immediately after the push notification is delivered to the device. The full structure of the campaign events can be found in the System events article.

🚧

Campaign event tracking

This problem relates to campaign events with the status delivered for iOS mobile push notifications. iOS devices previously tracked events only after the start of the application, which could come too late or never. The new implementation ensures that delivered events are tracked immediately after delivery and for all push notifications. However, it may not be 100 % reliable because of the technical limitations of iOS, which gives the application only 12-15MB of RAM and 30 seconds of processing time.

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

📘

UTM parameters tracking

Each UTM parameter is tracked into a separate attribute of the session_start. These would be, for example, utm_source, utm_medium, and utm_campaign. This is consistent with JS SDK tracking. This is united with the tracking of UTMs in all SDKs.

📘

Rich push notifications are required for delivered notification tracking on iOS. Sent/failed is tracked on the server when it is sending the push notification. Delivered/clicked is tracked from the app (SDK).

Create a notification with the code builder

For advanced use cases, you can also build push notifications in the code push notification builder. Take a look at the code in the snippet below and read through the description of some attributes.

You can define three types of actions:

• app - Opens the application.
• browser - Opens a web browser. You need to define the url for redirection.
• deeplink - Opens a particular screen in your application. You need to define the url for redirection

{
    "title": "Notification title", // Name of the notification
    "message": "Notification text", // Text of the notification
    "action": "browser", // The type of action that will be triggered after tapping on notification
    "url": "http://exponea.com",  // Define this if action is browser/deeplink
    "actions": [ // list of buttons
        {
            "title": "Open", 
            "action": "app"
        },
        {
            "title": "Go to website", // button name
            "action": "browser", // action type
            "url": "https://exponea.com" // action additional information
        },
        {
            "title": "Cancel",
            "action": "deeplink",
            "url": "exponea://notifications.actions.cancel/fe80c8b8c5fffe62aa10"
        }
    ],
    "image": "https://exponea.com/icon.png", // URL of image or gif 
    "sound": "beep.wav", // sound name. Sound must be saved in your APP directory
    "attributes": { // Additional data that will be send in background of your push notification
        "age": 24,
        "gender": "male"
    }
}

{
    "title": "Notification title", // Name of the notification
    "message": "Notification text", // Text of the notification
    "action": "app", // The type of action that will be triggered after tapping on notification
    "actions": [ // list of buttons
        {
            "title": "Open", 
            "action": "app"
        },
        {
            "title": "Go to website", // button name
            "action": "browser", // action type
            "url": "https://exponea.com" // action additional information
        },
        {
            "title": "Cancel",
            "action": "deeplink",
            "url": "exponea://notifications.actions.cancel/fe80c8b8c5fffe62aa10"
        }
    ],
    "image": "http://exponea.com/icon.png", // URL of image or gif 
    "sound": "beep.wav", // sound name. Sound must be saved in your APP directory
    "attributes": { // Additional data that will be send in background of your push notification
        "age": 24,
        "gender": "male"
    }
}

iOS Custom payload description

Limitations for IOS platform:
When handling rich push notifications actions for iOS platforms lower than iOS 12, you need to enable Legacy iOS actions. iOS lower than 12 does not support the rendering of push notification actions directly from the received payload. This requires hardcoded action categories with some development and specific attribute in the push notification payload legacy_ios_category: category_id. Your developers should follow this guide.

{
    "legacy_ios_category": "category_id", // when you want to support actions for iOS version < 12. Read a guide from part "Limitations for iOS platform"
    "title": "Notification title", // Name of the notification
    "message": "Notification text", // Text of the notification
    "action": "app", 
    "actions": [ // list of buttons
        {
            "title": "Open", 
            "action": "app"
        },
        {
            "title": "Go to website", // button name
            "action": "browser", // action type
            "url": "https://exponea.com" // action additional information
        },
        {
            "title": "Cancel",
            "action": "deeplink",
            "url": "exponea://notifications.actions.cancel/fe80c8b8c5fffe62aa10"
        }
    ],
    "image": "https://exponea.com/icon.png", // URL of image or gif 
    "sound": "beep.wav", // sound name. Sound must be saved in your APP directory
    "attributes": { // Additional data that will be send in background of your push notification
        "age": 24,
        "gender": "male"
    }
}

Use Case examples

• Personalized push notifications
• Sending a customer notification based on their location - For example, if they are close to your store, you might send them a notification with a discount (requires additional integrations)
• Sending data silently to a mobile application to check whether the customer still has the app

Deduplication

Bloomreach Engagement allows multiple customers to share the same push notification token, which could result in unwanted targeting of the same device of multiple types. Deduplication of push messages is automatically used to prevent this.

This is done through the use of RunID. Scheduled push notifications are sent in bulk to multiple customers at once in 10-second intervals. Every time a new bulk is sent, a new RunID is generated, which allows the system to recognize if the particular device has already received a notification in the previous bulk. The result is that the latest notification will replace the earlier one. Behavior differs for the platforms:

• Android - notification_id parameter is used. The latest notification will replace the previous one.
• iOS - apns-collapse-id header is used. A newer notification will replace the older one with a blink effect.

The parameters are the place on the device where the RunID is stored.

Huawei vs. Firebase Deduplication

Huawei devices still use Android OS but have created a separate push service; originally, they used Firebase. Messages will be sent only via Huawei push service to avoid duplicate delivery to profiles that have both the original Android Firebase push token, and Huawei push token. Selecting the Android target device under the push node setting will follow the same logic and send a push via Firebase or Huawei.

Third-party errors

A list of campaign events is tracked when push notifications fail to be delivered. Those events aren't coming directly from our SDK but are coming from third parties. If they occur, contact your provider. Here's a small overview of the errors that might occur:

Why mobile push notification was not sent

The exact error is often not propagated to the alert returned by the test functionality. The best way to get detailed information on the error cause is to launch a live scenario that would send the push notification to your test customer profile. Include a condition node that will let through only the desired test profiles.

After you've launched the scenario, go to the customer profile page and find the corresponding campaign event. The error code will be propagated to the error attribute of the campaign event, while a short human-readable error description will be propagated to the comment attribute in case of APNs, and to status_code and error attributes in case of Firebase Cloud Messaging and Huawei Push notification service respectively.

From here, you can follow the documentation on the error codes from the push providers:

• APNS
• Firebase
• Huawei