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.

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 notifications providers which then deliver them to the subscribed mobile device. The mobile application then handles the push message using our SDK and renders the notification on the smartphone screens of your customers.

# 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 send out 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. a. [iOS SDK](🔗) : [Push Notifications configuration](🔗) b. [Android SDK](🔗) : [Push Notifications configuration](🔗) c. [React Native SDK](🔗) : [Push Notifications configuration](🔗) d. [Flutter SDK](🔗) : [Push Notifications configuration](🔗) e. [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 the`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 needed. 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 for saving the token described below.

All mobile push services require an integration under the`Data & Assets > Integrations` to be set up and then selected under `Project settings > Campaigns > Channels > Push notifications`. The selected integration in the project settings will then be used for sending 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](🔗)

(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.

# Creating 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.

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.

**GIF** images are _not_ currently supported on iOS.

**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).

**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.

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.

Target DeviceSelect the target device type - iOS, Android, or both. If iOS is selected, the notification will be sent only to iOS devices using the Apple push notification service. If Android is selected, the notification will be sent to both Huawei (Huawei push service) and other Android devices (Firebase cloud messaging). In case the customer profile has both `google_push_notification_id` and `huawei_push_notification_id`, the Huawei token takes preference, and the notification will be only sent using the Huawei Push Service.
Time to live (seconds)The number of seconds the system should try to continue delivering the push notification in case the device is unavailable (turned off or without internet). If you leave the time to live empty (default setting), it is not sent in the request.
PriorityAndroid devices do not currently deliver push notifications with `normal` priority when the device is in low-power mode. We, therefore, recommend using the`high` priority so that the notifications are delivered even in such cases. The setting should not affect anything else.
App InboxMobile push notifications can be stored in the App Inbox in the mobile application, allowing your customers to access the content of mobile push notifications even after interacting with them. See [Persistent storage for mobile push notifications](🔗).

## Silent push notifications

You can send a silent notification to your customers, which they will not see. You can use this, for example, if you want to check whether any 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.

# Sending 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](🔗).

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 delivery 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 the`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).

# Creating a notification using the code builder

You can also build push notifications in the code push notification builder for advanced use cases. You can 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

### 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](🔗).

# 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:

NotRegisteredThis is a provider error and happens when the registration token is invalid in various scenarios. More information is provided [here](🔗)
BadDeviceTokenThis provider error happens when the device has an invalid token. More information is provided [here](🔗).
MismatchSenderIdThis error occurs when the sender's ID does not match the ID used when registering the app.
MissingPushTokenThe error occurs when the receiver of the push notification does not have a valid push token.
UnregisteredThis provider error occurs when the registration token is inactive.

## 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](🔗)