Home Android & Kotlin Tutorials

Bubbles Tutorial for Android 10: Getting Started

In this Bubbles for Android 10 tutorial, you’ll learn how to use the Bubble API to create notification bubbles to let users easily multitask.

4.8/5 5 Ratings


  • Kotlin 1.3, Android 10.0, Android Studio 3.5

At Google I/O in 2019, Google announced an intriguing new feature for Android called Bubbles.

A bubble floats above other app content and can expand or shrink into a small, circular icon. Users can easily move the bubble to different areas of the screen by dragging the icon.

In Android 10, the call feature of the phone app already uses bubbles. If a user navigates to another app during a call, the phone app minimizes into a convenient little bubble that moves around the screen. In messaging apps, bubbles can mimic Facebook’s chat heads feature.

In this tutorial, you’ll learn how to change an app called Code Coach from using normal notifications to using the new bubble feature in Android 10.

Note: This tutorial assumes you have basic knowledge of Kotlin and Android.

If you’re new to Android, check out our Android tutorials.

If you know Android but are unfamiliar with Kotlin, take a look at Kotlin For Android: An Introduction.

Note: Right now, the Bubbles feature is still in Developer Preview and is for developer use only. So, make sure you’re not using it in production.

Also, it is not guaranteed to work on an emulator targeted at Android 10. It is best you try this on a physical device.

Getting Started

Download the project materials by using the Download Materials button found at the top or bottom of this tutorial. Open the Starter project in Android Studio. After the project finishes loading, build and run.

The starter app run for the first time.

Tap the button on the top-right corner of the app.

The starter project showing an inspirational notification.

You’ll see a notification with a random, inspiring quote from the Code Coach. Tap this notification and it’ll open an activity that displays the quote.

The notification displaying an inspiring fullscreen quote.

Now that that the app’s notification has inspired you, wouldn’t it be nice to have inspiration like that bubble up at your fingertips? You’ll now transform this app to provide inspiration whenever you need it while multitasking on your device!

Learning More About Bubbles in Android

Bubbles’ design is a more secure alternative to using the SYSTEM_ALERT_WINDOW. Not to burst any bubbles, but SYSTEM_ALERT_WINDOW is more restricted in Android 10, and the new Android Go devices don’t include it.

Bubbles are part of the notification system. If a user locks the device or activates the always-on-display feature, a bubble appears as a normal notification.

Programmatically, you create a bubble in much the same way you would create a normal notification. Android Notifications: Getting Started has more information about Android Notifications.

Learning About a Bubble’s Lifecycle

A bubble can have two states: expanded or minimized. When a bubble expands, its content activity goes through the stages of the normal process lifecycle. The app becomes a foreground process if it wasn’t already. When the bubble collapses or the user dismisses it, the content activity is destroyed. The system can then cache or kill the process, depending on whether the app had other foreground components running.

Setting the Right Conditions for Bubbles to Appear

For bubbles to appear, at least one of the following conditions must be true:

  • The notification has a Person added and uses MessagingStyle.
  • The notification has a Person added, has a category of CATEGORY_CALL and is from a call to Service.startForeground.
  • An app needs to be in the foreground to send notifications.

Considering Best Practices

When you’re incorporating bubbles into your app, make sure to keep the following points in mind:

  • Bubbles are an opt-in feature. If a user disables bubbles, the bubble will display as a normal notification. So make sure the bubble notification can also work as a regular notification.
  • Bubbles can take up valuable screen space. Unless the user explicitly requests the bubble from the app, use bubbles only for important events, like ongoing communications.
  • Activities that users launch from the content activity also appear inside the content area of the bubble. That means the content activity can accrue a task stack. Keep the navigation inside the content activity simple and specific.

Now that you’ve learned more about bubbles and when to use them, it’s time to get out your bubble wand and make some!

Enabling Bubbles on a Device or Emulator

Android 10 disables bubbles by default. Currently, the feature is in developer preview and is in the developer options.

Go to SettingsDeveloper OptionsBubbles, and use the switch to turn the feature on.

Turning on Bubbles in developer options.

Now that you’ve enabled bubbles, you can modify the app to use them.

Modifying the Android Manifest

The next step to using a bubble in an app is to add the bubble content activity to the manifest.

Bubble activity must be resizeable, embedded and must always launch in document UI mode. If you don’t meet any of these requirements, the app will launch a regular notification instead.

Open AndroidManifest.xml and add the three properties below to QuoteBubbleActivity‘s Activity tag, right below the label attribute:


The code above allows you to make sure you can resize, embed and launch the Activity in document mode.

Next, look at the code that creates the notification.

Creating the Notification

Open model/NotificationHelper.kt and look at the code. setUpNotificationChannels creates the notification channel. Look at showNotification below:

fun showNotification(quote: Quote, fromUser: Boolean) {
  // Create Icon
  val icon = createIcon()
  // Create the Person
  val person = createPerson(icon)
  // Create the Notification
  val notification = createNotification(quote, icon, person)
  // Build and Display the Notification
  notificationManager.notify(NOTIFICATION_ID, notification.build())

The code above is responsible for showing the notification because:

  • createIcon creates the icon for the notification.
  • createPerson creates Code Coach, the person tied to this notification since it’s a MessagingStyle notification.
  • Finally, createNotification creates the notification using the person and icon.
  • notify displays the notification.

It’s important that the notification works on its own in case bubbles are not allowed or available. createNotification looks like:

fun createNotification(quote: Quote, icon: Icon, person: Person): 
    Notification.Builder {
  return Notification.Builder(context, CHANNEL_QUOTES)
    .setContentTitle("Code Coach")
      .addMessage(quote.quoteText, currentTimeMillis(), person)

The method sets the content title, small and large icons, category, style and content intent for the notification. It creates a MessagingStyle and adds the quote as a message. createIntent creates the intent that displays when the user taps the notification.

Now that you’ve seen how to create a notification, add the code to transform the notification into a bubble when bubbles are allowed.

Creating the Bubble Metadata

To turn the notification into a bubble, set the bubble metadata. The bubble metadata contains the attributes of the bubble. Add the following code inside the NotificationHelper class below createIntent:

fun createBubbleMetadata(icon: Icon, fromUser: Boolean):
    Notification.BubbleMetadata {
  return Notification.BubbleMetadata.Builder()
    .apply {
    if (fromUser) {

createBubbleMetadata sets the following attributes:

  • The desired height of the bubble. This sets the height of the content area when the bubble expands.
  • The bubble’s circular icon, which floats above all other app content on the device. It’s attached to the content area.
  • setAutoExpandBubble specifies whether or not the bubble should expand. If the user requested this bubble, it will expand. Initially, this value is false, but you’ll change it in the next steps.
  • setSuppressNotification determines whether a notification should appear as well as the bubble. When the bubble expands, there’s no need to provide a notification with the bubble, so the app suppresses the notification.
  • setIntent sets the intent that launches when the user taps the bubble.

Now, call createBubbleMetadata in showNotification, right above the comment that says // Build and Display the Notification:

// Create the Bubble's Metadata
val bubbleMetaData = createBubbleMetadata(icon, fromUser)

// Set the bubble metadata

The above code creates the bubble metadata and adds it to the notification. Now, if bubbles are allowed, the inspirational quote will display in a bubble rather than as a notification. Build and run the app then tap the button in the top-right:

A bubble presents that hasn't expanded yet.

The effervescent Code Coach pops up in bubble form with an inspirational quote!

Notice how the bubble doesn’t expand and how there’s no notification. The bubble replaced the notification and setSuppressNotification is set to true. There’s no reason to show a notification and a bubble when the user requested a bubble.

Using Bubbles

Tap the Home button or make the home gesture to place the app in the background. The bubble persists:

The bubble persists over the home screen.

Tap and drag the bubble around the screen to different locations. Now, tap the bubble to expand the content area. Notice how you can tap the button to generate new quotes:

The expanded bubble and the button to generate a new quote.

To close the bubble, tap and drag it to the dismiss icon at the bottom-center of the screen:
A gif showing how to dismiss the bubble.

Congratulations, you’ve made your first bubble! :]

Now, you’ll launch the bubble with an expanded content area.

Launching the Expanded Bubble

Return to NotificationHelper.kt in Android Studio, and in createBubbleMetadata, change the argument passed to setAutoExpandBubble from false to true. The line now appears as:


Build and run and tap the button in the top-right to launch the bubble:

The bubble launches in its expanded form.

Ta-da! The bubble floats up, and it’s already expanded.

You’ve done an excellent job transforming a simple notification into an interactive bubble. But what if the user wants to opt out of this feature?

Opting Out of Bubbles

Sometimes, an Android device owner may want to block bubbles. Users can block bubbles system-wide by turning off this feature in the settings. Or they can disable bubbles for a particular app.

To disable the feature, go to the device and choose Settings ▸ Apps and notifications ▸ RW Code Coach from the recent apps. You can also choose displaying all apps, select Notifications, expand Advanced and finally, select Bubbles. You can then turn bubbles on or off for this app:

The app-level settings for bubbles.

Move the switch to the off position to block bubbles. Now build and run the app and tap the button on the top-right to see the effect:

An app with the bubbles feature blocked presents a notification instead.

The app still works, but now a user will see the inspirational quote as a notification instead of a bubble, according to their preference. That’s why it’s important to design the notification as well as the bubble.

Users can also block bubbles on the notification channel. To block bubbles in the channel, go to the device and choose Settings ▸ Apps and notifications. Select Notifications. Under recently sent, select RW Code Coach.

Notice how Bubbles shows as off. Tap Bubbles to turn them back on for now.

Navigate back to the Notifications screen and select the Inspirational Quotes channel. Expand Advanced and you’ll see Bubbles again:

The settings option to turn off bubbles for a particular notification channel.

Toggling this switch turns bubbles on or off for that notification channel instead of for the whole app. If bubbles display when you visit the channel screen, the switch won’t be visible since they’re disabled for the whole app.

Now you’ve seen two levels that Android 10 provides to allow the user to filter or opt out of the bubbles feature. Knowing this can help you to design your app to suit a user’s preferences.

Where to Go From Here?

You can download the completed project files by clicking the Download Materials button at the top or bottom of the tutorial.

In this tutorial, you learned how to turn a normal notification into an app that uses the new bubble feature in Android 10! You also learned how to design bubbles with notifications to fit the user’s preferences and how to turn bubbles on and off.

To learn more about bubbles, visit the Official Android Documentation about this feature.

To learn more about notifications, check out this lesson from the Android Background Processing video course.

To see some bubbles in a more advanced messaging app from Google, check out github repo.

I hope you enjoyed this tutorial! If any questions or comments “bubble up”, please join the forum discussion below.

Average Rating


Add a rating for this content

5 ratings

More like this