Customize Push Notification Functionality for Android Apps

The MobilePush Android SDK offers extensive customization options for notifications through the NotificationCustomizationOptions class and the Engagment UI. The example provided in the Initialize the SDK section of the Android Quickstart Guide depicts the basic configuration, requiring only the Small Icon Resource ID to be provided to the SDK. This example represents only the minimum configuration needed for displaying notifications on your Android apps with the SDK. For information on status bar icons, see Icons in Google's Material Design documentation.

You can further customize push notifications by providing a Launch Intent Provider or specifying the action to be taken when a notification is tapped. For an example configuration, see the Simplified Customization section of this article.

You can also take complete control over push notifications, as described in the Full Control Customization section of this article.

To facilitate additional customization such as deep linking or handling custom keys, use the NotificationMessage class.

The NotificationCustomizationOptions class facilitates push notification customization through a NotificationChannelIdProvider, enabling the assignment of a specific Notification Channel for each NotificationMessage.

Additionally, NotificationLaunchIntentProvider defines the action to be taken when a NotificationMessage is tapped, alongside your application's Notification Icon.

When targeting apps running Android 12 or above, ensure that you specify the mutability of your Pending Intent as per Android guidelines.

MobilePush SDK supports icons in various notification elements, including small icons (in the status bar and notification header), large icons (in the notification body) and rich button icons.

You can use icons by placing icon files in the PNG format inside drawables-**hdpi folders within your client app's resources. The SDK then references these icons by their resource names (for example, ic_notification_icon).

Here's how you can configure and set icons:

  • Small icons: Provide the resource ID within NotificationCustomizationOptions when using MarketingCloudConfigBuilder. Alternatively, you can specify the icon's resource name directly in the Engagement UI.
  • Large icons: Provide the resource name and optional public URL for remote retrieval in the Engagement UI.
  • Rich button icons: Provide the resource names in the Engagement UI.

For example, to use an icon named ic_notification_icon.png, place it in the appropriate drawables-**hdpi folder. Then, provide ic_notification_icon as the resource name on the Engagement UI. If its a small icon, you can also specify the resource ID in NotificationCustomizationOptions when using MarketingCloudConfigBuilder.

You can customize notification channels by setting priorities, colors, and sounds. To use a custom sound in notifications, follow these steps:

  1. Add the sound file to the app’s res/raw/ folder.

  2. Create a notification channel for the audio file and configure it in the code using NotificationChannelIdProvider. This sample code creates a notification channel named myaudio, enables badges and lights, and sets a default importance level.

  3. In the Engagement UI, set the sound file name (including the extension) under the Custom option in Sound settings.

    Supported audio file formats: .mp3, .wav, .aac, .m4a

This sample code configures the MobilePush SDK for an Android application. It sets up notification customization options, including the small icon, launch intent, and notification channel ID.

When providing a builder to the NotificationCustomizationOptions class, you're responsible for managing all aspects of the notification’s display properties and tap actions, including Notification Channel creation, Launch Intent action, and so on.

You can access the NotificationCompat.Builder that would have been used by the SDK and use it as a baseline for modifications. Additionally, the SDK can create a default NotificationChannel for your application.

If you wish to have Marketing Cloud Engagement collect notification open analytics for your notifications, you must wrap your PendingIntent in the SDK’s analytics helper method NotificationManager.redirectForAnalytics().

Marketers can configure the action when an end user taps a button or a carousel image in a push notification. The actions for Web URL and App URL require that you implement UrlHandler as a new SDK initialization method.

This example shows how to configure the SDK to handle button and carousel clicks in push messages.

On devices running Android Oreo or above, the SDK creates a default notification channel called marketing to assign all notifications to it. To change the name of the default channel, set a string resource value for mcsdk_default_notification_channel_name.

After the SDK creates the NotificationChannel, the channel isn’t updated unless your application calls NotificationManager#createDefaultNotificationChannel(Context context, boolean forceRecreate).

You can create custom notification channels and assign channels to each notification, as depicted by the following example configuration.

To assign a notification to a channel, implement the SDK NotificationChannelIdProvider interface. Ensure that you include a channel with your message. Otherwise, the app doesn’t display the message to the recipient.

You can customize channel priority, colors, and sounds. To use custom sounds, give each channel its own sound configuration while creating it. You can’t use sounds with the SDK default channel option.

You can deliver location messages to a subset of your MobilePush audience by using the Android SDK. For example, when a mobile device breaches a geofence or enters the vicinity of a Bluetooth beacon, the SDK can prompt a callback to your mobile app for assessing whether to display a message.

Your app can apply criteria, including information within the MobilePush message itself, to determine whether to show a push notification, geofence message, or beacon message. Here are some use cases.

  • Show the message if the user’s preferred store location is within the geofence region.
  • Show the message if the user has items in the app shopping cart and if the message has an “abandonedCart”:”true” custom key.
  • Show the message only when the store is open based on the app’s store location list and the region and local time.
  • Don’t show messages if the user isn’t logged in to the app.
  • Show specific messages based on the user’s customer profile. For example, customers who are coffee lovers get messages about coffee, but customers who prefer pastry receive a message to "buy coffee” when they’re in the shop.

Provide an implementation of ShouldShowNotificationListener to the NotificationManager. When you implement shouldShowNotification, you can access all information about the triggering message, including region data for geofence and beacon triggers.

In this example, to target only Gold loyalty-level customers for message delivery, the marketer sets the custom key loyaltyLevel to gold while creating the location message. Then, the message is shown only if the customer’s contact attribute is also set to gold.

Starting with version 9.0.0, the MobilePush Android SDK tracks successful delivery of push notifications to the SDK. To enable this feature, contact your Marketing Cloud admin.

For more information, see MobilePush Install, Inactive Devices, Push Delivery events