Push notifications

Prerequisites

Before you can use this feature, you’ll need to integrate the Android Braze SDK.

Built-in features

The following features are built into the Braze Android SDK. To use any other push notification features, you will need to set up push notifications for your app.

Setting up push notifications

Rate limits

Firebase Cloud Messaging (FCM) API has a default rate limit of 600,000 requests per minute. If you reach this limit, Braze will automatically try again in a few minutes. To request an increase, contact Firebase Support.

Step 1: Add Firebase to your project

First, add Firebase to your Android project. For step-by-step instructions, see Google’s Firebase setup guide.

Step 2: Add Cloud Messaging to your dependencies

Next, add the Cloud Messaging library to your project dependencies. In your Android project, open build.gradle, then add the following line to your dependencies block.

1
implementation "google.firebase:firebase-messaging:+"

Your dependencies should look similar to the following:

1
2
3
4
dependencies {
  implementation project(':android-sdk-ui')
  implementation "com.google.firebase:firebase-messaging:+"
}

Step 3: Enable the Firebase Cloud Messaging API

In Google Cloud, select the project your Android app is using, then enable the Firebase Cloud Messaging API.

Step 4: Create a service account

Next, create a new service account, so Braze can make authorized API calls when registering FCM tokens. In Google Cloud, go to Service Accounts, then choose your project. On the Service Accounts page, select Create Service Account.

Enter a service account name, ID, and description, then select Create and continue.

In the Role field, find and select Firebase Cloud Messaging API Admin from the list of roles. For more restrictive access, create a custom role with the cloudmessaging.messages.create permission, then choose it from the list instead. When you’re finished, select Done.

Step 5: Generate JSON credentials

Next, generate JSON credentials for your FCM service account. On Google Cloud IAM & Admin, go to Service Accounts, then choose your project. Locate the FCM service account you created earlier, then select  Actions > Manage Keys.

Select Add Key > Create new key.

Choose JSON, then select Create. If you created your service account using a different Google Cloud project ID than your FCM project ID, you’ll need to manually update the value assigned to the project_id in your JSON file.

Be sure to remember where you downloaded the key—you’ll need it in the next step.

Step 6: Upload your JSON credentials to Braze

Next, upload your JSON credentials to your Braze dashboard. In Braze, select  Settings > App Settings.

Under your Android app’s Push Notification Settings, choose Firebase, then select Upload JSON File and upload the credentials you generated earlier. When you’re finished, select Save.

Step 7: Set up automatic token registration

When one of your users opt-in for push notifications, your app needs to generate an FCM token on their device before you can send them push notifications. With the Braze SDK, you can enable automatic FCM token registration for each user’s device in your project’s Braze configuration files.

First, go to Firebase Console, open your project, then select  Settings > Project settings.

Select Cloud Messaging, then under Firebase Cloud Messaging API (V1), copy the number in the Sender ID field.

Next, open your Android Studio project and use your Firebase Sender ID to enable automatic FCM token registration within your braze.xml or BrazeConfig.

• braze.xml
• brazeconfig

1
2
<bool translatable="false" name="com_braze_firebase_cloud_messaging_registration_enabled">true</bool>
<string translatable="false" name="com_braze_firebase_cloud_messaging_sender_id">FIREBASE_SENDER_ID</string>

1
2
3
4
5
6
<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string translatable="false" name="com_braze_api_key">12345ABC-6789-DEFG-0123-HIJK456789LM</string>
  <bool translatable="false" name="com_braze_firebase_cloud_messaging_registration_enabled">true</bool>
<string translatable="false" name="com_braze_firebase_cloud_messaging_sender_id">603679405392</string>
</resources>

1
2
.setIsFirebaseCloudMessagingRegistrationEnabled(true)
.setFirebaseCloudMessagingSenderIdKey("FIREBASE_SENDER_ID")

1
2
.setIsFirebaseCloudMessagingRegistrationEnabled(true)
.setFirebaseCloudMessagingSenderIdKey("FIREBASE_SENDER_ID")

1
2
3
4
5
6
7
8
9
10
BrazeConfig brazeConfig = new BrazeConfig.Builder()
  .setApiKey("12345ABC-6789-DEFG-0123-HIJK456789LM")
  .setCustomEndpoint("sdk.iad-01.braze.com")
  .setSessionTimeout(60)
  .setHandlePushDeepLinksAutomatically(true)
  .setGreatNetworkDataFlushInterval(10)
  .setIsFirebaseCloudMessagingRegistrationEnabled(true)
  .setFirebaseCloudMessagingSenderIdKey("603679405392")
  .build();
Braze.configure(this, brazeConfig);

1
2
3
4
5
6
7
8
9
10
val brazeConfig = BrazeConfig.Builder()
  .setApiKey("12345ABC-6789-DEFG-0123-HIJK456789LM")
  .setCustomEndpoint("sdk.iad-01.braze.com")
  .setSessionTimeout(60)
  .setHandlePushDeepLinksAutomatically(true)
  .setGreatNetworkDataFlushInterval(10)
  .setIsFirebaseCloudMessagingRegistrationEnabled(true)
  .setFirebaseCloudMessagingSenderIdKey("603679405392")
  .build()
Braze.configure(this, brazeConfig)

Step 8: Remove automatic requests in your application class

To prevent Braze from triggering unnecessary network requests everytime you send silent push notifications, remove any automatic network requests configured in your Application class’s onCreate() method. For more information see, Android Developer Reference: Application.

Displaying notifications

Step 1: Register Braze Firebase Messaging Service

You can either create a new, existing, or non-Braze Firebase Messaging Service. Choose whichever best meets your specific needs.

• new
• existing
• non-braze

1
2
3
4
5
6
<service android:name="com.braze.push.BrazeFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

1
2
3
4
5
6
7
8
9
10
11
12
13
public class MyFirebaseMessagingService extends FirebaseMessagingService {
  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
    super.onMessageReceived(remoteMessage);
    if (BrazeFirebaseMessagingService.handleBrazeRemoteMessage(this, remoteMessage)) {
      // This Remote Message originated from Braze and a push notification was displayed.
      // No further action is needed.
    } else {
      // This Remote Message did not originate from Braze.
      // No action was taken and you can safely pass this Remote Message to other handlers.
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
class MyFirebaseMessagingService : FirebaseMessagingService() {
  override fun onMessageReceived(remoteMessage: RemoteMessage?) {
    super.onMessageReceived(remoteMessage)
    if (BrazeFirebaseMessagingService.handleBrazeRemoteMessage(this, remoteMessage)) {
      // This Remote Message originated from Braze and a push notification was displayed.
      // No further action is needed.
    } else {
      // This Remote Message did not originate from Braze.
      // No action was taken and you can safely pass this Remote Message to other handlers.
    }
  }
}

1
2
<bool name="com_braze_fallback_firebase_cloud_messaging_service_enabled">true</bool>
<string name="com_braze_fallback_firebase_cloud_messaging_service_classpath">com.company.OurFirebaseMessagingService</string>

1
2
3
4
5
BrazeConfig brazeConfig = new BrazeConfig.Builder()
        .setFallbackFirebaseMessagingServiceEnabled(true)
        .setFallbackFirebaseMessagingServiceClasspath("com.company.OurFirebaseMessagingService")
        .build();
Braze.configure(this, brazeConfig);

1
2
3
4
5
val brazeConfig = BrazeConfig.Builder()
        .setFallbackFirebaseMessagingServiceEnabled(true)
        .setFallbackFirebaseMessagingServiceClasspath("com.company.OurFirebaseMessagingService")
        .build()
Braze.configure(this, brazeConfig)

Step 2: Conform small icons to design guidelines

For general information about Android notification icons, visit the Notifications overview.

Starting in Android N, you should update or remove small notification icon assets that involve color. The Android system (not the Braze SDK) ignores all non-alpha and transparency channels in action icons and the notification small icon. In other words, Android will convert all parts of your notification small icon to monochrome except for transparent regions.

To create a notification small icon asset that displays properly:

• Remove all colors from the image except for white.
• All other non-white regions of the asset should be transparent.

The following large and small icons pictured are examples of properly designed icons:

Step 3: Configure notification icons

Specifying icons in braze.xml

Braze allows you to configure your notification icons by specifying drawable resources in your braze.xml:

1
2
<drawable name="com_braze_push_small_notification_icon">REPLACE_WITH_YOUR_ICON</drawable>
<drawable name="com_braze_push_large_notification_icon">REPLACE_WITH_YOUR_ICON</drawable>

Setting a small notification icon is required. If you do not set one, Braze will default to using the application icon as the small notification icon, which may look suboptimal.

Setting a large notification icon is optional but recommended.

Specifying icon accent color

The notification icon accent color can be overridden in your braze.xml. If the color is not specified, the default color is the same gray Lollipop uses for system notifications.

1
<integer name="com_braze_default_notification_accent_color">0xFFf33e3e</integer>

You may also optionally use a color reference:

1
<color name="com_braze_default_notification_accent_color">@color/my_color_here</color>

Step 4: Add deep links

Enabling automatic deep link opening

To enable Braze to automatically open your app and any deep links when a push notification is clicked, set com_braze_handle_push_deep_links_automatically to true, in your braze.xml:

1
<bool name="com_braze_handle_push_deep_links_automatically">true</bool>

This flag can also be set via runtime configuration:

• java
• kotlin

1
2
3
4
BrazeConfig brazeConfig = new BrazeConfig.Builder()
        .setHandlePushDeepLinksAutomatically(true)
        .build();
Braze.configure(this, brazeConfig);

1
2
3
4
val brazeConfig = BrazeConfig.Builder()
        .setHandlePushDeepLinksAutomatically(true)
        .build()
Braze.configure(this, brazeConfig)

If you want to custom handle deep links, you will need to create a push callback that listens for push received and opened intents from Braze. For more information, see Using a callback for push events.

Creating custom deep links

Follow the instructions found within the Android developer documentation on deep linking if you have not already added deep links to your app. To learn more about what deep links are, see our FAQ article.

Adding deep links

The Braze dashboard supports setting deep links or web URLs in push notifications campaigns and Canvases that will be opened when the notification is clicked.

Customizing back stack behavior

The Android SDK, by default, will place your host app’s main launcher activity in the back stack when following push deep links. Braze allows you to set a custom activity to open in the back stack in place of your main launcher activity or to disable the back stack altogether.

For example, to set an activity called YourMainActivity as the back stack activity using runtime configuration:

• java
• kotlin

1
2
3
4
5
BrazeConfig brazeConfig = new BrazeConfig.Builder()
        .setPushDeepLinkBackStackActivityEnabled(true)
        .setPushDeepLinkBackStackActivityClass(YourMainActivity.class)
        .build();
Braze.configure(this, brazeConfig);

1
2
3
4
5
val brazeConfig = BrazeConfig.Builder()
        .setPushDeepLinkBackStackActivityEnabled(true)
        .setPushDeepLinkBackStackActivityClass(YourMainActivity.class)
        .build()
Braze.configure(this, brazeConfig)

See the equivalent configuration for your braze.xml. Note that the class name must be the same as returned by Class.forName().

1
2
<bool name="com_braze_push_deep_link_back_stack_activity_enabled">true</bool>
<string name="com_braze_push_deep_link_back_stack_activity_class_name">your.package.name.YourMainActivity</string>

Step 5: Define notification channels

The Braze Android SDK supports Android notification channels. If a Braze notification does not contain the ID for a notification channel or that a Braze notification contains an invalid channel ID, Braze will display the notification with the default notification channel defined in the SDK. Braze users use Android Notification Channels within the platform to group notifications.

To set the user facing name of the default Braze notification channel, use BrazeConfig.setDefaultNotificationChannelName().

To set the user facing description of the default Braze notification channel, use BrazeConfig.setDefaultNotificationChannelDescription().

Update any API campaigns with the Android push object parameter to include the notification_channel field. If this field is not specified, Braze will send the notification payload with the dashboard fallback channel ID.

Other than the default notification channel, Braze will not create any channels. All other channels must be programmatically defined by the host app and then entered into the Braze dashboard.

The default channel name and description can also be configured in braze.xml.

1
2
<string name="com_braze_default_notification_channel_name">Your channel name</string>
<string name="com_braze_default_notification_channel_description">Your channel description</string>

Step 6: Test notification display and analytics

Testing display

At this point, you should be able to see notifications sent from Braze. To test this, go to the Campaigns page on your Braze dashboard and create a Push Notification campaign. Choose Android Push and design your message. Then click the eye icon in the composer to get the test sender. Enter the user ID or email address of your current user and click Send Test. You should see the push show up on your device.

For issues related to push display, see our troubleshooting guide.

Testing analytics

At this point, you should also have analytics logging for push notification opens. Clicking on the notification when it arrives should result in the Direct Opens on your campaign results page to increase by 1. Check out our push reporting article for a break down on push analytics.

For issues related to push analytics, see our troubleshooting guide.

Testing from command line

If you’d like to test in-app and push notifications via the command-line interface, you can send a single notification through the terminal via cURL and the messaging API. You will need to replace the following fields with the correct values for your test case:

• YOUR_API_KEY (Go to Settings > API Keys.)
• YOUR_EXTERNAL_USER_ID (Search for a profile on the Search Users page.)
• YOUR_KEY1 (optional)
• YOUR_VALUE1 (optional)

1
2
3
4
5
6
7
8
9
10
11
12
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR_API_KEY}" -d '{
  "external_user_ids":["YOUR_EXTERNAL_USER_ID"],
  "messages": {
    "android_push": {
      "title":"Test push title",
      "alert":"Test push",
      "extra": {
        "YOUR_KEY1":"YOUR_VALUE1"
      }
    }  
  }
}' https://rest.iad-01.braze.com/messages/send

This example uses the US-01 instance. If you are not on this instance, replace the US-01 endpoint with your endpoint.

Conversation push notifications

The people and conversations initiative is a multi-year Android initiative that aims to elevate people and conversations in the system surfaces of the phone. This priority is based on the fact that communication and interaction with other people is still the most valued and important functional area for the majority of Android users across all demographics.

Usage requirements

• This notification type requires the Braze Android SDK v15.0.0+ and Android 11+ devices.
• Unsupported devices or SDKs will fallback to a standard push notification.

This feature is only available over the Braze REST API. See the Android push object for more information.

FCM quota exceeded errors

When your limit for Firebase Cloud Messaging (FCM) is exceeded, Google returns “quota exceeded” errors. The default limit for FCM is 600,000 requests per minute. Braze retries sending according to Google’s recommended best practices. However, a large volume of these errors can prolong sending time by several minutes. To mitigate potential impact, Braze will send you an alert that the rate limit is being exceeded and steps you can take to prevent the errors.

To check your current limit, go to your Google Cloud Console > APIs & Services > Firebase Cloud Messaging API > Quotas & System Limits, or visit the FCM API Quotas page.

Best practices

We recommend these best practices to keep these error volumes low.

Request a rate limit increase from FCM

To request a rate limit increase from FCM, you can contact Firebase Support directly or do the following:

1. Go to the FCM API Quotas page.
2. Locate the Send requests per minute quota.
3. Select Edit Quota.
4. Enter a new value and submit your request.

Request global rate limiting via Braze

To apply a workspace-wide limit for Android push notifications, contact Braze Support.