Standard Android push integration

This article covers how to integrate push notifications in your Android application.

A push notification is an out-of-app alert that appears on the user’s screen when an important update occurs. Push notifications are a valuable way to provide your users with time-sensitive and relevant content or to re-engage them with your app.

Braze sends push notifications to Android devices using Firebase Cloud Messaging (FCM).

Check out our help documentation for push best practices.

Registering for push

Use Firebase Cloud Messaging to register for push. For a full sample of using Firebase with the Braze Android SDK, see our Firebase push sample app.

Step 1: Enable Firebase

To get started, follow the Firebase instructions on adding Firebase to your Android project.

Next, add the Firebase messaging dependency to your module’s build.gradle:

1
implementation "com.google.firebase:firebase-messaging:${FIREBASE_PUSH_MESSAGING_VERSION}"

Step 2: Configure token registration

Braze push notifications won’t work until a Firebase Cloud Messaging token (FCM registration token) is registered. FCM registration tokens can either be registered by the Braze SDK automatically (recommended) or manually registered. Tokens can be manually registered using the Braze.setRegisteredPushToken() method.

Make sure to use your Firebase Sender ID. This is a unique numerical value created when you create your Firebase project, available in the Cloud Messaging tab of the Firebase console Settings pane. The sender ID is used to identify each sender that can send messages to the client app.

• Automatic registration (recommended)
• Manual registration

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">your_fcm_sender_id_here</string>

1
2
3
4
5
BrazeConfig brazeConfig = new BrazeConfig.Builder()
  .setIsFirebaseCloudMessagingRegistrationEnabled(true)
  .setFirebaseCloudMessagingSenderIdKey("YOUR FIREBASE SENDER ID HERE")
  .build();
Braze.configure(this, brazeConfig);

1
2
3
4
5
val brazeConfig = BrazeConfig.Builder()
    .setIsFirebaseCloudMessagingRegistrationEnabled(true)
    .setFirebaseCloudMessagingSenderIdKey("YOUR FIREBASE SENDER ID HERE")
    .build()
Braze.configure(this, brazeConfig)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    final Context applicationContext = this;
    FirebaseMessaging.getInstance().getToken().addOnCompleteListener(task -> {
      if (!task.isSuccessful()) {
        Log.w(TAG, "Exception while registering FCM token with Braze.", task.getException());
        return;
      }

      final String token = task.getResult();
      Braze.getInstance(applicationContext).setRegisteredPushToken(token);
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
class MyApplication: Application() {
  override fun onCreate() {
    super.onCreate()
    FirebaseMessaging.getInstance().token.addOnCompleteListener { task: Task<String?> ->
      if (!task.isSuccessful) {
        Log.w(TAG, "Exception while registering FCM token with Braze.", task.exception)
        return@addOnCompleteListener
      }
      val token = task.result
      Braze.getInstance(applicationContext).setRegisteredPushToken(token)
    }
  }
}

Step 3: Migrate from GCM (Optional)

If you are migrating from using GCM to using Firebase with Braze, visit the GCM migration guide for instructions on switching to using Firebase in your app.

Step 4: Set Your Firebase credentials

First, you must locate your Cloud Messaging API server key and sender ID in the Firebase developers console. Select your Firebase project, go to Settings > Cloud Messaging, and copy the Cloud Messaging API (Legacy) Server Key and Sender ID:

Input your Cloud Messaging API (Legacy) server key and sender ID into the Braze dashboard:

1. On the Settings page (where your API keys are located), select your Android app.
2. Enter your Cloud Messaging API (Legacy) server key in the Firebase Cloud Messaging Server Key field, under the push notification settings section.
3. Enter your Cloud Messaging API (Legacy) sender ID in the Firebase Cloud Messaging Sender ID field, under the push notification settings section.

Step 5: Remove old permissions

Braze no longer requires the following permissions if using Firebase:

1
2
3
4
5
  <uses-permission android:name="android.permission.GET_ACCOUNTS" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />
  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
  <permission android:name="YOUR-APPLICATION-PACKAGE-NAME.permission.C2D_MESSAGE" android:protectionLevel="signature"/>
  <uses-permission android:name="YOUR-APPLICATION-PACKAGE-NAME.permission.C2D_MESSAGE" />

Step 6: Remove automatic actions from your application class

If you have a custom application subclass, ensure you do not have automatic logic that pings your servers in your class’s Application.onCreate() lifecycle method. This will ensure that silent push notifications from Braze don’t cause unnecessary requests to your servers.

Receiving and displaying push

After completing this section, you should be able to receive and display push notifications sent by Braze.

Step 1: Register Braze Firebase Messaging Service

Braze includes a service to handle push receipt and open intents. Our BrazeFirebaseMessagingService class will need to be registered in your AndroidManifest.xml:

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>

Braze’s notification code also uses BrazeFirebaseMessagingService to handle open and click action tracking. This service must be registered in the AndroidManifest.xml to function correctly. Also, remember that Braze prefixes notifications from our system with a unique key to ensure we only render notifications sent from Braze’s systems. You may register additional services separately to render notifications sent from other FCM services. See AndroidManifest.xml in the Firebase push sample app.

Using your own Firebase Messaging Service

If you already have a Firebase Messaging Service registered, you can pass RemoteMessage objects to Braze via BrazeFirebaseMessagingService.handleBrazeRemoteMessage(). This method will only display a notification if the RemoteMessage object originated from Braze and will safely ignore if not.

• JAVA
• KOTLIN

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

Step 2: Ensure small icons conform 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 properly create a notification small icon asset:

• 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 would like to custom handle deep links, you will need to create a push callback that listens for push received and opened intents from Braze. See our Custom handling push receipts and opens article for more information.

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().

You should ensure that any API campaigns with the Android push object parameter are updated 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, 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 - available at Settings > API Keys
• YOUR_EXTERNAL_USER_ID - available by searching 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.

Customizing your integration

Custom displaying notifications

Step 1: Create your custom notification factory

In some scenarios, you may wish to customize push notifications in ways that would be cumbersome or unavailable server side. To give you complete control of notification display, we’ve added the ability to define your own IBrazeNotificationFactory to create notification objects for display by Braze.

If a custom IBrazeNotificationFactory is set, Braze will call your factory’s createNotification() method upon push receipt before the notification is displayed to the user. Braze will pass in a Bundle containing Braze push data and another Bundle containing custom key-value pairs sent either via the dashboard or the messaging APIs:

Braze will pass in a BrazeNotificationPayload containing data from the Braze push notification.

• JAVA
• KOTLIN

1
2
3
4
5
6
7
8
9
// Factory method implemented in your custom IBrazeNotificationFactory
@Override
public Notification createNotification(BrazeNotificationPayload brazeNotificationPayload) {
  // Example of getting notification title
  String title = brazeNotificationPayload.getTitleText();

  // Example of retrieving a custom KVP ("my_key" -> "my_value")
  String customKvp = brazeNotificationPayload.getBrazeExtras().getString("my_key");
}

1
2
3
4
5
6
7
8
// Factory method implemented in your custom IBrazeNotificationFactory
override fun createNotification(brazeNotificationPayload: BrazeNotificationPayload): Notification {
  // Example of getting notification title
  val title = brazeNotificationPayload.getTitleText()

  // Example of retrieving a custom KVP ("my_key" -> "my_value")
  val customKvp = brazeNotificationPayload.getBrazeExtras().getString("my_key")
}

You can return null from your custom createNotification() method to not show the notification at all, use BrazeNotificationFactory.getInstance().createNotification() to obtain Braze’s default notification object for that data and modify it before display, or generate a completely separate notification object for display.

Step 2: Set your custom notification factory

To instruct Braze to use your custom notification factory, use the setCustomBrazeNotificationFactory method to set your IBrazeNotificationFactory:

• JAVA
• KOTLIN

1
setCustomBrazeNotificationFactory(IBrazeNotificationFactory brazeNotificationFactory);

1
setCustomBrazeNotificationFactory(brazeNotificationFactory: IBrazeNotificationFactory)

The recommended place to set your custom IBrazeNotificationFactory is in the Application.onCreate() application lifecycle method (not activity). This will allow the notification factory to be set correctly whenever your app process is active.

To unset your custom IBrazeNotificationFactory and return to default Braze handling for push, pass in null to our custom notification factory setter:

• JAVA
• KOTLIN

1
setCustomBrazeNotificationFactory(null);

1
setCustomBrazeNotificationFactory(null)

Push primers

Push primer campaigns encourage your users to enable push notifications on their device for your app. This can be done without SDK customization using our no code push primer.