Advanced push notification examples
The following guide covers some advanced push notifications examples for the Braze SDK.
Prerequisites
Before you can use this feature, you’ll need to integrate the Android Braze SDK. You’ll also need to set up push notifications.
Custom notification layout
Braze notifications are sent as data messages, which means that your application will always have a chance to respond and perform behavior accordingly, even in the background (in contrast to notification messages, which can be handled automatically by the system when your app is in the background). As such, your application will have a chance to customize the experience by, for example displaying personalized UI elements within the notification delivered to the notification tray. While implementing push in this way may be unfamiliar to some, one of our well-known features at Braze, Push Stories, are a prime example of using custom view components to create an engaging experience!
Android imposes some limitations on what components can be used to implement custom notification views. Notification view layouts must only contain View objects compatible with the RemoteViews framework.
You can use the IBrazeNotificationFactory
interface to customize how Braze push notifications are displayed. By extending BrazeNotificationFactory
, Braze will call your factory’s createNotification()
method before the notification is displayed to the user. It will then pass a payload containing custom key-value pairs sent through the Braze dashboard or REST API.
In this section, you’ll partner with Superb Owl, the host of a new game show where wildlife rescue teams compete to see who can save the most owls. They’re looking to leverage live updating notifications in their Android app, so they can display the status of an on-going match and make dynamic updates to the notification in realtime.
Step 1: Add a custom layout
You can add one or more custom notification RemoteView layouts to your project. These are helpful for handling how notifications are displayed when collapsed or expanded. Your directory structure should be similar to the following:
1
2
3
4
5
6
.
├── app/
└── res/
└── layout/
├── liveupdate_collapsed.xml
└── liveupdate_expanded.xml
In each XML file, create a custom layout. Superb Owl created the following layouts for their collapsed and expanded RemoteView layouts:
1
2
3
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="vertical">
<TextView
android:id="@+id/notification_title"
style="@style/TextAppearance.Compat.Notification.Title"
android:layout_width="wrap_content"
android:layout_height="0dp"
android:layout_weight="1" />
</LinearLayout>
Step 2: Create a custom notification factory
In your application, create a new file named MyCustomNotificationFactory.kt
that extends BrazeNotificationFactory
to handle how custom RemoteView layouts are displayed.
In the following example, Superb Owl created a custom notification factory to display a RemoteView layout for on-going matches. In the next step, they’ll create a new method called getTeamInfo
to map a team’s data to the activity.
Show the sample code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
import android.app.Notification
import android.widget.RemoteViews
import androidx.core.app.NotificationCompat
import com.braze.models.push.BrazeNotificationPayload
import com.braze.push.BrazeNotificationFactory
import com.braze.push.BrazeNotificationUtils.getOrCreateNotificationChannelId
import com.braze.support.BrazeLogger.brazelog
class MyCustomNotificationFactory : BrazeNotificationFactory() {
override fun createNotification(payload: BrazeNotificationPayload): Notification? {
if (payload.extras.containsKey("live_update")) {
val kvp = payload.extras
val notificationChannelId = getOrCreateNotificationChannelId(payload)
val context = payload.context
if (context == null) {
brazelog { "BrazeNotificationPayload has null context. Not creating notification" }
return null
}
val team1 = kvp["team1"]
val team2 = kvp["team2"]
val score1 = kvp["score1"]
val score2 = kvp["score2"]
val time = kvp["time"]
val quarter = kvp["quarter"]
// Superb Owl will define the 'getTeamInfo' method in the next step.
val (team1name, team1icon) = getTeamInfo(team1)
val (team2name, team2icon) = getTeamInfo(team2)
// Get the layouts to use in the custom notification.
val notificationLayoutCollapsed = RemoteViews(BuildConfig.APPLICATION_ID, R.layout.liveupdate_collapsed)
val notificationLayoutExpanded = RemoteViews(BuildConfig.APPLICATION_ID, R.layout.liveupdate_expanded)
// Very simple notification for the small layout
notificationLayoutCollapsed.setTextViewText(
R.id.notification_title,
"$team1 $score1 - $score2 $team2\n$time $quarter"
)
notificationLayoutExpanded.setTextViewText(R.id.score, "$score1 - $score2")
notificationLayoutExpanded.setTextViewText(R.id.team1name, team1name)
notificationLayoutExpanded.setTextViewText(R.id.team2name, team2name)
notificationLayoutExpanded.setTextViewText(R.id.timeInfo, "$time - $quarter")
notificationLayoutExpanded.setImageViewResource(R.id.team1logo, team1icon)
notificationLayoutExpanded.setImageViewResource(R.id.team2logo, team2icon)
val customNotification = NotificationCompat.Builder(context, notificationChannelId)
.setSmallIcon(R.drawable.notification_small_icon)
.setStyle(NotificationCompat.DecoratedCustomViewStyle())
.setCustomContentView(notificationLayout)
.setCustomBigContentView(notificationLayoutExpanded)
.build()
return customNotification
} else {
// Use the BrazeNotificationFactory for all other notifications
return super.createNotification(payload)
}
}
}
Step 3: Map custom data
In MyCustomNotificationFactory.kt
, create a new method for handling data when Live Updates are displayed.
Superb Owl created the following method to map each team’s name and logo to expanded Live Updates:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class CustomNotificationFactory : BrazeNotificationFactory() {
override fun createNotification(payload: BrazeNotificationPayload): Notification? {
// Your existing code
return super.createNotification(payload)
}
// Your new method
private fun getTeamInfo(team: String?): Pair<String, Int> {
return when (team) {
"WBF" -> Pair("Wild Bird Fund", R.drawable.team_wbf)
"OWL" -> Pair("Owl Rehab", R.drawable.team_owl)
else -> Pair("Unknown", R.drawable.notification_small_icon)
}
}
}
Step 4: Set the custom notification factory
In your application class, use customBrazeNotificationFactory
to set your custom notification factory.
1
2
3
4
5
6
7
8
9
10
import com.braze.Braze
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
// Tell Braze to use your custom factory for notifications
Braze.customBrazeNotificationFactory = MyCustomNotificationFactory()
}
}
Step 5: Send the activity
You can use the /messages/send
REST API endpoint to send a push notification to a user’s Android device.
Example curl command
Superb Owl sent their request using the following curl command:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl -X POST "https://BRAZE_REST_ENDPOINT/messages/send" \
-H "Authorization: Bearer {REST_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"external_user_ids": ["USER_ID"],
"messages": {
"android_push": {
"title": "WBF vs OWL",
"alert": "2 to 4 1:33 Q4",
"extra": {
"live_update": "true",
"team1": "WBF",
"team2": "OWL",
"score1": "2",
"score2": "4",
"time": "1:33",
"quarter": "Q4"
},
"notification_id": "ASSIGNED_NOTIFICATION_ID"
}
}
}'
While curl commands are helpful for testing, we recommend handling this call in your backend where you’re already handling your iOS Live Activities.
Request parameters
Key | Description |
---|---|
REST_API_KEY |
A Braze REST API key with messages.send permissions. This can be created in the Braze dashboard from Settings > API Keys. |
BRAZE_REST_ENDPOINT |
Your REST endpoint URL. Your endpoint will depend on the Braze URL for your instance. |
USER_ID |
The ID of the user you are sending the notification to. |
messages.android_push.title |
The message’s title. By default, this is not used for the custom notification factory’s live notifications, but it may be used as a fallback. |
messages.android_push.alert |
The message’s body. By default, this is not used for the custom notification factory’s live notifications, but it may be used as a fallback. |
messages.extra |
Key-value pairs that the custom notification factory uses for live notifications. You can assign any string to this value—however, in the example above, live_updates is used to determine if it’s a default or live push notification. |
ASSIGNED_NOTIFICATION_ID |
The notification ID you want to assign to the chosen user’s live notification. The ID must be unique to this game, and must be used in order to update their existing notification later. |
Step 6: Update the activity
To update the existing RemoteView notification with new data, modify the relevant key-value pairs assigned to messages.extra
, then use the same notification_id
and call the /messages/send
endpoint again.
Personalized push notifications
Push notifications can display user-specific information inside a custom view hierarchy. In the following example, an API-trigger is used to send personalized push notification to a user so they can track check their current progress after completing a specific task in the app.
To set up a personalized push in the dashboard, register the specific category you want to be displayed, then set any relevant user attributes you’d like to display using Liquid.
Prerequisites
Before you can use this feature, you’ll need to integrate the Swift Braze SDK. You’ll also need to set up push notifications.
This implementation guide is centered around a Swift implementation, but Objective-C snippets are provided for those interested.
Notification content app extensions
Notification content app extensions provide you a great option for push notification customization. Notification content app extensions display a custom interface for your app’s notifications when a push notification is expanded.
Push notifications can be expanded in three different ways:
- A long press on the push banner
- Swiping down on the push banner
- Swiping the banner to the left and selecting “View”
These custom views offer smart ways to engage customers by displaying distinct types of content, including interactive notifications, notifications populated with user data, and even push messages that can capture information like phone numbers and email. One of our well-known features at Braze, Push Stories, are a prime example of what a push notification content app extension can look like!
Requirements
- Push notifications successfully integrated in your app
- The following files generated by Xcode based on your coding language:
Swift
NotificationViewController.swift
MainInterface.storyboard
Objective-C
NotificationViewController.h
NotificationViewController.m
MainInterface.storyboard
Interactive push notification
Push notifications can respond to user actions inside a content app extension. For users running iOS 12 or later, this means you can turn your push notifications into fully interactive messages! This provides an exciting option to introduce interactivity to your promotions and applications. For example, your push notification can include a game for users to play, a spin-to-win wheel for discounts, or a “like” button to save a listing or song.
The following example shows a push notification where users are able to play a match game inside the expanded notification.
Dashboard configuration
To create an interactive push notification, you must set a custom view in your dashboard.
- From the Campaigns page, click Create Campaign to start a new push notification campaign.
- On the Compose tab, toggle on Notification Buttons.
- Enter a custom iOS category in the iOS Notification Category field.
- In the
.plist
of your Notification Content Extension Target, set theUNNotificationExtensionCategory
attribute to your custom iOS category. The value given here must match what is set in the Braze dashboard under iOS Notification Category. - Set the
UNNotificationExtensionInteractionEnabled
key totrue
to enable user interactions in a push notification.
Personalized push notifications
Push notifications can display user-specific information inside a content extension. This allows you to create user-focused push content, such as adding the option to share your progress across different platforms, show unlocked achievements, or display onboarding checklists. This example shows a push notification displayed to a user after they have completed a specific task in the Braze Learning course. By expanding the notification, the user can see their progress through their learning path. The information provided here is user-specific and can be fired off as a session is completed or a specific user action is taken by leveraging an API trigger.
Dashboard configuration
To create a personalized push notification, you must set a custom view in your dashboard.
- From the Campaigns page, click Create Campaign to start a new push notification campaign.
- On the Compose tab, toggle on Notification Buttons.
- Enter a custom iOS category in the iOS Notification Category field.
- In the Settings tab, create key-value pairs using standard Liquid. Set the appropriate user attributes you want the message to show. These views can be personalized based on specific user attributes of a specific user profile.
- In the
.plist
of your Notification Content Extension Target, set theUNNotificationExtensionCategory
attribute to your custom iOS category. The value given here must match what is set in the Braze dashboard under iOS Notification Category.
Handling key-value pairs
The method didReceive
is called when the notification content app extension has received a notification. This method can be found within the NotificationViewController
. The key-value pairs provided in the dashboard are represented in the code through the use of a userInfo
dictionary.
Parsing Key-Value Pairs from Push Notifications
1
2
3
4
5
6
7
8
9
func didReceive(_ notification: UNNotification) {
let userInfo = notification.request.content.userInfo
guard let value = userInfo["YOUR-KEY-VALUE-PAIR"] as? String,
let otherValue = userInfo["YOUR-OTHER-KEY-VALUE-PAIR"] as? String,
else { fatalError("Key-Value Pairs are incorrect.")}
...
}
1
2
3
4
5
6
7
8
9
10
11
- (void)didReceiveNotification:(nonnull UNNotification *)notification {
NSDictionary *userInfo = notification.request.content.userInfo;
if (userInfo[@"YOUR-KEY-VALUE-PAIR"] && userInfo[@"YOUR-OTHER-KEY-VALUE-PAIR"]) {
...
} else {
[NSException raise:NSGenericException format:@"Key-Value Pairs are incorrect"];
}
}
Information capture push notification
Push notifications can capture user information inside a content app extension, pushing the limits of what is possible with a push. Requesting user input through push notifications allows you to not only request basic information like name or email, but also prompt users to submit feedback or complete an unfinished user profile.
For more information, see Logging push notification data.
In the following flow, the custom view is able to respond to state changes. Those state change components are represented in each image.
- User receives a push notification.
- Push is opened. After expanded, the push prompts the user for information. In this example, the user’s email address is requested, but you could request any sort of information.
- Information is provided, and if in the expected format, the registration button is shown.
- Confirmation view is displayed, and push gets dismissed.
Dashboard configuration
To create an information capture push notification, you must set a custom view in your dashboard.
- From the Campaigns page, click Create Campaign to start a new push notification campaign.
- On the Compose tab, toggle on Notification Buttons.
- Enter a custom iOS category in the iOS Notification Category field.
- In the Settings tab, create key-value pairs using standard Liquid. Set the appropriate user attributes you want the message to show.
- In the
.plist
of your Notification Content Extension Target, set theUNNotificationExtensionCategory
attribute to your custom iOS category. The value given here must match what is set in the Braze dashboard under iOS Notification Category.
As seen in the example, you may also include an image in your push notification. To do this, you must integrate rich notifications, set the notification style in your campaign to Rich Notification, and include a rich push image.
Handling button actions
Each action button is uniquely identified. The code checks if your response identifier is equal to the actionIndentifier
, and if so, knows that the user clicked the action button.
Handling Push Notification Action Button Responses
1
2
3
4
5
6
7
func didReceive(_ response: UNNotificationResponse, completionHandler completion: @escaping (UNNotificationContentExtensionResponseOption) -> Void) {
if response.actionIdentifier == "YOUR-REGISTER-IDENTIFIER" {
// do something
} else {
// do something else
}
}
1
2
3
4
5
6
7
- (void)didReceiveNotificationResponse:(UNNotificationResponse *)response completionHandler:(void (^)(UNNotificationContentExtensionResponseOption))completion {
if ([response.actionIdentifier isEqualToString:@"YOUR-REGISTER-IDENTIFIER"]) {
completion(UNNotificationContentExtensionResponseOptionDismiss);
} else {
completion(UNNotificationContentExtensionResponseOptionDoNotDismiss);
}
}
Dismissing pushes
Push notifications can be automatically dismissed from an action button press. There are three pre-built push dismissal options that we recommend:
completion(.dismiss)
- Dismisses the notificationcompletion(.doNotDismiss)
- Notification stays opencompletion(.dismissAndForward)
- Push dismisses and the user gets forwarded into the application