Mobile push notifications

Mobile push notification (rich push notification) is a textual push notification with the addition of media (images) and interaction (buttons) that you can send to your mobile app users.

With the growing number of mobile app users, mobile strategy becomes a larger and more significant part of the overall marketing strategy. Having an additional channel can provide a competitive edge. With the use of our SDKs, you can integrate Bloomreach Engagement with your mobile application on Android or iOS and send engaging, personalized push notifications to your customers.

📘

Note

Mobile push notifications replace the old "Push Notification" feature, which has been deprecated (you can keep using it if it has already been set up in your project). Version 2.0.0 or higher for Android and iOS is supported.

How does it work

Push notification campaigns can be configured in Integrations and created within our Scenarios, using the visual builder for simpler use cases or the code builder for more advanced ones. Bloomreach Engagement dispatches the push messages to integrated push notification providers, who then deliver them to the subscribed mobile device. The mobile application then handles the push message using our SDK and renders the notification on your customers' smartphone screens.

Installation and push setup

You need to install one of our mobile SDKs and set up push credentials before the mobile app can receive and show notifications from Bloomreach Engagement.

We provide several mobile SDKs for both iOS and Android. Each platform has separate steps for configuring the integration and installation of the SDK. Generally, you will need to add an SDK to your mobile app, initialize it with Bloomreach Engagement credentials, and add specific credentials into Bloomreach Engagement Project settings. After collecting consent and tokens, you can launch your first campaign.

For detailed installation of mobile SDK and enabling push notifications, 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 complete, the notifications can be sent to your application straight from Bloomreach Engagement.

👍

iOS SDK Integration Guide

If you want to learn more about integrating iOS SDK, check our short video guide!

Push notification integrations

To send push notifications, a third-party service is required. To set up an integration with a push service, navigate to the Data & Assets > Integrations.

These services will receive the push request from Engagement and send it to the target mobile devices based on the device push token. Push tokens are saved as an attribute to the customer profile; our SDK will take care of the push token management and assign the push token attribute to the customer profile upon subscribing to push notifications. Each push notification integration uses a different attribute name to save the token described below.

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

Android devices can be split into two groups. Most of the devices use Google Play Store with Firebase Cloud Messaging, and then newer devices from Huawei use their own Huawei AppGallery and Huawei Push Service (Huawei devices were originally also using Google Play Store and Firebase Cloud Messaging; therefore some older devices still use and can be targeted using Firebase, but the usage is decreasing. Newer Huawei devices use the new Huawei Mobile Services).

(A) Firebase Cloud Messaging - to send mobile push notifications to devices using the Android operating system (except Huawei devices), Bloomreach Engagement uses the Firebase Cloud Messaging (FCM). To learn more about FCM, see Firebase Cloud Messaging.

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

❗️

Please note that due to Google deprecating and removing the FCM legacy API in June 2024, Bloomreach Engagement is moving to the new Firebase HTTP v1 API.

In order to keep using Firebase to send push notifications to Android devices, you must add a new FCM integration.

(B) Huawei Push Service - To send mobile push notifications to Huawei Android devices, Bloomreach Engagement uses the Huawei Push Service (HPC). 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

Apple Push Notification service - To send mobile push notifications to devices using iOS, Bloomreach Engagement uses the Apple Push Notification service (APNs). For more information about this service, see APNs Overview

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

Then, the desired integration has to be selected under Project settings > Campaigns > Channels > Push notifications.

🚧

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

Create a new notification

Mobile push notifications are created in scenarios. Go to Campaigns > Scenarios, and on the left side, select Mobile Push Notification under Actions. When you double-click on the action node, it will open the notification builder, where you can specify the notification. You can work with the default UX-friendly interface or switch to coding mode (1), which is explained later in this guide.

Editor

In the INTERACTION section, you can specify 3 types of interactions that will be performed:

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

In the MEDIA section, you can set it to display an image within the notification or play a sound when it is received.

On the right side, you can preview (2) how your notification will look on Android / iOS and also for every 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 if you use personalization to check whether the notification displays different text for different customers as specified.

🚧

Character limit

Bloomreach Engagement sets no character limit, but it is recommended to have roughly no more than 230 characters for iOS and 500 for Android. However, for optimal user experience, your text should not 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 are currently not supported and will cause an error.

🚧

Image size limit

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

Images that are taller than 1,038 pixels will be downscaled with padding to give them a square appearance.

We recommend using images that have a 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 a 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 are not supported on Android.

iOS and Android:

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

📘

Note

The Bloomreach Engagement editor always displays fonts in the 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, in the case of Arabic font, the Bloomreach Engagement editor displays the font from left to right, but if you send a push to the user who has the phone set up in the right-to-left formatting, the notification is displayed in the 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.

Silent Push Notifications

You can send your customers a silent notification, which they will not 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 is likely the customer has uninstalled it.

🚧

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

Deliverability

Currently, Android devices in low-power mode block the delivery of notifications with normal priority. Therefore, we have added a Priority setting and all push notifications have High chosen as a default. This ensures that the 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).

🚧

Sending push notifications - 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, please 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 is not 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.

Events can be mapped 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 are not coming directly from our SDK but are coming from third parties. If they occur, please contact your provider. Here is a small overview of the errors that might occur:

Why mobile push notification was not sent

Unfortunately, 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. Keep in mind that you would need to include a condition node that will let through only the desired test profiles.

After you have launched the scenario, navigate 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