Push Notifications
Enable push notifications in your app using the Android SDK
Engagement enables sending push notifications to your app users using scenarios. The mobile application handles the push message using the SDK and renders the notification on the customer's device.
Push notifications can also be silent, used only to update the app’s interface or trigger some background task.
Refer to Mobile Push Notifications to learn how to create push notifications in the Engagement web app.
Integration
This section describes the steps to add the minimum push notification functionality (receive alert notifications) to your app.
Standard (Firebase) Integration
To be able to send push notifications from the Engagement platform and receive them in your app on Android devices, you must:
- Set up a Firebase project.
- Implement Firebase messaging in your app.
- Configure the Firebase Cloud Messaging integration in the Engagement web app.
Follow the instructions in Firebase Cloud Messaging.
Please note that with Google deprecating and removing the FCM legacy API in June 2024, Bloomreach Engagement is now using Firebase HTTP v1 API.
If your Engagement project uses a deprecated version of the Firebase integration, you must readd and reconfigure the FCM integration following the current instructions.
Huawei Integration
To be able to send push notifications from the Engagement platform and receive them in your app on Huawei devices, you must:
- Set up Huawei Mobile Services (HMS)
- Implement HMS in your app.
- Configure the Huawei Push Service integration in the Engagement web app.
Follow the instructions in Huawei Mobile Services.
Request Notification Permission
As of Android 13 (API level 33), a new runtime notification permission POST_NOTIFICATIONS
must be registered in your AndroidManifest.xml
and must also be granted by the user for your application to be able to show push notifications.
The SDK already registers the POST_NOTIFICATIONS
permission.
The runtime permission dialog to ask the user to grant the permission must be triggered from your application. You can use the SDK API for that purpose:
Exponea.requestPushAuthorization(requireContext()) { granted ->
Logger.i(this, "Push notifications are allowed: $granted")
}
The behavior of this callback is as follows:
- For Android API level <33:
- Permission is not required, return
true
automatically.
- Permission is not required, return
- For Android API level 33+:
- Show the dialog, return the user's decision (
true
/false
). - In case of previously granted permission, don't show the dialog return
true
.
- Show the dialog, return the user's decision (
Require Notification Permission
On Android 13 and higher, the app may not be able to send normal push notifications, even though a freshly generated token (at application start) is valid, if the user didn't grant permission to receive notifications.
If your marketing flow strictly requires normal push notifications usage, configure the SDK to track only authorized push tokens by setting requirePushAuthorization to true
. The SDK will track push tokens only if the user granted push notification permission, otherwise the push token will be removed. If you leave requirePushAuthorization
to false
(the default value), the SDK will track the push token regardless of the user's permission. These tokens can only be used to send silent push notifications.
Customization
This section describes the customizations you can implement once you have integrated the minimum push notification functionality.
Configure Automatic Push Notification Tracking
By default, the SDK tracks push notifications automatically. In the SDK configuration, you can set the desired frequency using the tokenTrackFrequency
property (default value is ON_TOKEN_CHANGE
). You can also disable automatic push notification tracking by setting the Boolean value of the automaticPushNotification
property to false
.
If automaticPushNotification
is enabled, the SDK will display push notifications from Engagement and track a "campaign" event for every delivered/opened push notification with the relevant properties.
Respond to Push Notifications
When creating a push notification in the Engagment web app, you can choose from three different actions to be performed when tapping the notification or additional buttons displayed with the notification.
Open App
The "Open app" action generates an intent with action com.exponea.sdk.action.PUSH_CLICKED
. The SDK automatically responds to it by opening your app's launcher activity.
Previous SDK versions (<=2.9.7) required the creation of your own broadcast receiver to handle the open action, but since notification trampolining (opening activity from a receiver or a service) is no longer allowed since Android S, your activity intent will be opened directly from the notification, and this receiver is no longer needed on the application side.
Deep link
The "Deep link" action creates a "view" intent that contains the URL specified when setting up the action in Engagement. To respond to this intent, create an intent filter on the activity that handles it in your Android manifest file. For details, refer to Create Deep Links to App Content in the official Android documentation.
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<!-- Accepts URIs that begin with "my-schema://”-->
<data android:scheme="my-schema" />
</intent-filter>
If deep link intent is sent to an Activity that is currently active, the default behavior is that the intent is delivered to onNewIntent method rather than onCreate.
Open web browser
The "Open web browser" action is handled automatically by the SDK and no work is required from the developer to handle it.
Handle Additional Data Payload
When creating a push notification in the Engagment web app, you can set it up to contain additional data. Whenever a notification arrives, the SDK will call notificationCallback
, which you can set on the Exponea
object. The additional data is provided as a Map<String, String>
.
Exponea.notificationDataCallback = {
extra -> // handle the additional data
}
Note that if the SDK previously received any additional data while no listener was attached to the callback, it will dispatch that data as soon as a listener is attached.
Exponea.notificationDataCallback
callback will be called after you attach the listener (next app start) and the SDK is initialized. If you need to respond to the notification received immediately, implement your ownFirebaseMessagingService
and set the notification data callback inonMessageReceived
function before callingExponea.handleRemoteMessage
.
The behaviour of
trackDeliveredPush
may be affected by the tracking consent feature, which in enabled mode considers the requirement of explicit consent for tracking. Read more in tracking consent documentation.
Custom Processing of Notification Actions
When a user clicks on a notification or its buttons, the SDK automatically performs the configured action (open app, browser, etc.). If you require additional processing when this event occurs, you can create a receiver for this purpose. The SDK broadcastings com.exponea.sdk.action.PUSH_CLICKED
, com.exponea.sdk.action.PUSH_DEEPLINK_CLICKED
, and com.exponea.sdk.action.PUSH_URL_CLICKED
actions, and you can specify them in an intent filter to respond to them.
Registration in AndroidManifest.xml
:
<receiver
android:name="MyReceiver"
android:enabled="true"
android:exported="true">
<intent-filter>
<action android:name="com.exponea.sdk.action.PUSH_CLICKED" />
<action android:name="com.exponea.sdk.action.PUSH_DEEPLINK_CLICKED" />
<action android:name="com.exponea.sdk.action.PUSH_URL_CLICKED" />
</intent-filter>
</receiver>
Receiver class:
class MyReceiver : BroadcastReceiver() {
// React on push action click
override fun onReceive(context: Context, intent: Intent) {
// Extract push data
val data = intent.getParcelableExtra<NotificationData>(ExponeaExtras.EXTRA_DATA)
val actionInfo = intent.getSerializableExtra(ExponeaExtras.EXTRA_ACTION_INFO) as? NotificationAction
val customData = intent.getSerializableExtra(ExponeaExtras.EXTRA_CUSTOM_DATA) as Map<String, String>
// Process push data as you need
}
}
Silent Push Notifications
The Engagement web app allows you to set up silent push notifications, that are not displayed to the user. The SDK tracks a campaign
event when a silent push notification is delivered. Silent push notifications cannot be opened but if you have set up extra data in the payload, the SDK will call Exponea.notificationDataCallback
as described in Handle Extra Data Payload.
Push Notification Alert Sound
Received push notifications handled by Exponea.handleRemoteMessage()
will play a default or customized sound when the notification is displayed.
To use the default sound for a notification, keep empty or enter default
as value for Media > Sound
in your push notification scenario in the Engagement web app.
To use a custom sound for a notification, you must create a sound file that Android supports. Include the sound file in your 'raw' Android resources.
Once the custom sound is in place in your app, enter the file name of the sound file as value for Media > Sound
in your push notification scenario in the Engagement web app. Ensure that you enter the exact file name (case sensitive) without extension.
Playing of the notification sound may be affected by the notification channel importance, the user's app notification behaviour setup, or by active Do Not Disturb mode. Read more in the notifications overview in the Android documentation.
Manually Track Push Notifications
If you disable automatic push notification tracking or if you want to track push notification from other providers, you can manually track events related to push notifications.
Track Push Token (FCM)
Use the trackPushToken
method to manually track the FCM push token:
Exponea.trackPushToken(
token = "382d4221-3441-44b7-a676-3eb5f515157f"
)
Invoking this method will track the push token immediately regardless of the SDK configuration for tokenTrackFrequency
.
Track Delivered Push Notification
Use the trackDeliveredPush
method to manually track a delivered push notification:
// create NotificationData from your push payload
val notificationData = NotificationData(
dataMap = hashMapOf(
"platform" to "android",
"subject" to "Subject",
"type" to "push",
...
),
campaignMap = mapOf(
"utm_campaign" to "Campaign name",
"utm_medium" to "mobile_push_notification",
"utm_content" to "en",
...
)
)
Exponea.trackDeliveredPush(
data = notificationData
timestamp = currentTimeSeconds()
)
The behaviour of
trackDeliveredPush
may be affected by the tracking consent feature, which, when enabled, requires explicit consent for tracking. Read more in the tracking consent documentation.
Track Clicked Push Notification
Use the trackClickedPush
method to manually track a clicked push notification:
// create NotificationData from your push payload
val notificationData = NotificationData(
dataMap = hashMapOf(
"platform" to "android",
"subject" to "Subject",
"type" to "push",
...
),
campaignMap = mapOf(
"utm_campaign" to "Campaign name",
"utm_medium" to "mobile_push_notification",
"utm_content" to "en",
...
)
)
Exponea.trackClickedPush(
data = notificationData
timestamp = currentTimeSeconds()
)
The behaviour of
trackClickedPush
may be affected by the tracking consent feature, which, when enabled, requires explicit consent for tracking. Read more in the tracking consent documentation.
Custom Push Notification Data Processing
If the provided Exponea.handleRemoteMessage
method does not fit the requirements of your app, or you decide to disable automatic push notifications, you must handle push notifications and process their payload yourself.
Notification payloads are generated from (possibly complex) scenarios in the Engagement platform and contain all data for Android, iOS and web platforms. Therefore, the payload itself can be complex.
Notification payloads use a JSON data structure.
Payload Example
{
"notification_id": 123,
"url": "https://example.com/main_action",
"title": "Notification title",
"action": "app|browser|deeplink|self-check",
"message": "Notification message",
"image": "https://example.com/image.jpg",
"actions": [
{"title": "Action 1", "action": "app|browser|deeplink", "url": "https://example.com/action1"}
],
"sound": "default",
"aps": {
"alert": {"title": "Notification title", "body": "Notification message"},
"mutable-content": 1
},
"attributes": {
"event_type": "campaign",
"campaign_id": "123456",
"campaign_name": "Campaign name",
"action_id": 1,
"action_type": "mobile notification",
"action_name": "Action 1",
"campaign_policy": "policy",
"consent_category": "General consent",
"subject": "Subject",
"language": "en",
"platform": "ios|android",
"sent_timestamp": 1631234567.89,
"recipient": "[email protected]"
},
"url_params": {"param1": "value1", "param2": "value2"},
"source": "xnpe_platform",
"silent": false,
"has_tracking_consent": true,
"consent_category_tracking": "Tracking consent name"
}
Troubleshooting
If push notifications aren't working as expected in your app, consider the following frequent issues and their possible solutions:
Clicking on a push notification does not open the app on Xiaomi Redmi devices
Xiaomi MIUI handles battery optimization in its own way, which can sometimes affect the behavior of push notifications.
If battery optimization is on for devices running MIUI, it can make push notifications stop showing or not working after the click. Unfortunately, there is nothing we can do on our end to prevent this, but you can try this to solve the issues:
- Turn off any battery optimizations in
Settings
>Battery & Performance
. - Set the "No restrictions" option in the battery saver options for your app.
- And (probably) most important, turn off
Memory and MIUI Optimization
underDeveloper Options
.
Push notification token is missing after anonymization
Your app may be using Exponea.anonymize()
as a sign out feature.
Keep in mind that invoking the anonymize
method will remove the push notification token from storage. Your application should retrieve a valid token manually before using any push notification features. You may do this directly after anonymize
or before or after identifyCustomer
, depending on your push notifications usage.
Refer to Firebase Cloud Messaging and Huawai Mobile Services for information on how to retrieve a valid push notification token.
Multiple customer profiles have the same push notification token assigned
This is most likely because your app does not call anonymize
when a user logs out.
It's essential to call anonymize
when a user logs out of your app to ensure that the push notification token is removed from that user's profile. The token will be assigned to the user who logs in next. If your app fails to call anonymize
at one user's logout and a different user logs in, both users will have the same token in their profile.
Updated about 1 month ago