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 larger part of the overall marketing strategy, and 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 customer's smartphone screen.

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 the configuration of 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 consents and tokens you will be able to send your first campaign.

For detailed installation of mobile SDK and enabling push notifications follow the respective guides:

1. Installation of 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. Configuration of the Apple Development Centre (iOS), the Firebase platform (Android) or Huawei Push Service (Huawei Android) under Data & Assets -> Integrations

3. Selection of the wished integration in Project Settings -> Campaigns -> Channels -> Push notifications

Once this is complete, the notifications can be sent to your application straight from Bloomreach Engagement.

Push notification integrations

To send push notifications, a 3rd party service is needed. To set up an integration with a push service, navigate to Data & Assets -> Integrations.

These services will receive the push request from Engagement and send it to the target mobile device 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 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 (new Flutter, Xamarin and React native SDKs with Huawei support will be released soon)
• 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 click on Other under "Actions", then select Mobile Push Notification. This 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 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 like 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 for. This is especially useful if you use personalization to check whether the notification displays different text for different customers as specified.

🚧

Character limit

There is no character limit set by Bloomreach Engagement 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 shouldn't be longer than 50 characters.

🚧

Image size limit

iOS:
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 often becomes resized or cropped.

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

We recommend using images that have 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).

📘

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.

Settings

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

Silent push notifications

You can send a silent notification to your customers which will not be seen by them. 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 had 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 implementation of the push notification is correct. The route will serve as a trigger for test messages. When a call is made, it sends a push notification that will allow the developer to check whether all parts of the push notification are working correctly. Read more

Sending test push notifications

You can always test how the notification looks like on a real 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 notification to a customer, they must have a specific attribute which 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 audience of the campaign, covering actions from the push being sent from Bloomreach Engagement to customer's device receiving or customer clicking the push. The delivered status attribute in the campaign event is tracked immediately after the delivery of the push notification 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 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 to be 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, for example, be utm_source, utm_medium, 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’s sending the push notification. Delivered/clicked is tracked from the app(SDK).

Creating a notification using the code builder

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

You can define 3 types of actions:

• app - opens application
• browser - opens a web browser. You need to define url for redirection
• deeplink - opens a particular screen in your application. You need to define 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 platform lower than iOS 12, you need to enable Legacy iOS actions. iOS lower than 12 doesn't support the rendering of push notification actions directly from the received payload. This requires hardcoded action categories with some development and specific attribute in 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
     "badge": "increment", // "increment" or custom value, e.g. "100". Custom value is available only on IOS platform
    "attributes": { // Additional data that will be send in background of your push notification
        "age": 24,
        "gender": "male"
    }
}

Deduplication

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

This is done through the use of RunID. Scheduled push notifications are sent in bulks to multiple customers at once in 10-second intervals. Every time a new bulk 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 latter notification will replace the earlier one. Behavior differs for the platforms:

• Android - notification_id parameter is used. The latter 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. To avoid potential duplicate delivery to profiles that have both original Android firebase push token and Huawei push token, messages will be sent only via Huawei push service. Selecting the Android target device under the push node setting will follow the same logic, send push either via Firebase or Huawei.

3rd Party Errors

There is a list of campaign events that are tracked when push notifications failed to be delivered. Those events are not coming directly from our SDK but are coming from the 3rd parties. If they occur, please contact your provider. Here is a small overview of the errors that might occur: