Mobile push notification (rich push notification) is a textual push notification with the addition of media (images) and interaction (buttons). Use our SDKs if you want to integrate Exponea with your mobile application on Android or iOS:

• Android
• iOS

📘

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.

Integrate Exponea with your Mobile APP

You can skip this step if you already have working integration between Exponea and Mobile APP. If not, follow these guidelines:

Android SDK

To send mobile push notifications to devices using the Android operating system Exponea uses the Firebase Cloud Messaging(FCM). To learn more about FCM see Firebase Cloud Messaging.

1. Install SDK and configure the SDK with Exponea
2. Configure FCM platform to send push notifications to Android devices

IOS SDK

To send mobile push notifications to devices using IOS Exponea uses the Apple Push Notification service(APNs). For more information about this service see APNs Overview

1. Install SDK and configure the SDK with Exponea
2. Configure Apple developer center to send push notifications to IOS devices

🚧

Note that the google_push_notification_id customer property has the capability to hold only one FCM token at a time.

📘

Push notification settings

You can find push notification settings in application Project settings > Channels > Push notifications.

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

Sending push notifications

You can always test how the notification looks like on a real device. When you click the Test push button Exponea will send the push notification to the user selected in the preview part.

🚧

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

How to track attributes from SDK:
To track google_push_notification_id for Android, use this function.

To track apple_push_notification_id for IOS, use this function.

❗️

Error Customer property "google_push_notification_id" is missing means that the "push_notification_token" is not defined in the customer's attributes.

The delivered status attribute in the campaign event is tracked immediately after the delivery of the push notification.

🚧

Failure to deliver push notification on iOS device

Because of the technical limitations of iOS, not every single intended customer might receive the notification. iOS grants the application at a maximum of only 12-15MB of RAM with 30 seconds of processing time. This means that if the device is overwhelmed the notification might not be delivered.

📘

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

Exponea 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 had already received a notification in the previous bulk. The result is that the latter notification will replace the earlier one:

• With a blink effect in iOS devices.
• Without a blink effect in Android devices.

3rd party errors

🚧

If you are receiving any of the following errors:

NotRegistered BadDeviceToken MismatchSenderId Missing push token Unregistered

These are external errors which means they are NOT from our SDK. Please check with the provider.