1 <?xml version="1.0" encoding="utf-8"?> 2 <!-- 3 Copyright (C) 2019 The Android Open Source Project 4 5 Licensed under the Apache License, Version 2.0 (the "License"); 6 you may not use this file except in compliance with the License. 7 You may obtain a copy of the License at 8 9 http://www.apache.org/licenses/LICENSE-2.0 10 11 Unless required by applicable law or agreed to in writing, software 12 distributed under the License is distributed on an "AS IS" BASIS, 13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 See the License for the specific language governing permissions and 15 limitations under the License. 16 --> 17 <sample> 18 <name>Bubbles</name> 19 <group>Notification</group> 20 <package>com.example.android.bubbles</package> 21 22 <minSdk>Q</minSdk> 23 24 <strings> 25 <intro> 26 <![CDATA[ 27 This sample demonstrates how to use Bubbles API to show notifications as bubbles. 28 ]]> 29 </intro> 30 </strings> 31 32 <tempate src="base-build" /> 33 34 <metadata> 35 <status>PUBLISHED</status> 36 <categories>Notification</categories> 37 <technologies>Android</technologies> 38 <languages>Kotlin</languages> 39 <solutions>Mobile</solutions> 40 <level>INTERMEDIATE</level> 41 <icon>screenshots/icon-web.png</icon> 42 <screenshots> 43 <img>screenshots/main.png</img> 44 <img>screenshots/chat.png</img> 45 </screenshots> 46 <api_refs> 47 <android>android.app.Notification.BubbleMetadata</android> 48 </api_refs> 49 <description> 50 This sample demonstrates how to use Bubbles API to show notifications as bubbles. 51 </description> 52 <intro> 53 <![CDATA[ 54 ### API Usage 55 56 In order to show a notification as a bubble, call [setBubbleMetadata][1] and set metadata to the 57 Notification.Builder. [Notification.BubbleMetadata.Builder] can be used to create the metadata. You 58 can set the icon and the desired height of the bubble. The notification has to be in a notification 59 channel with [IMPORTANCE_HIGH][2] in order to prompt the user to allow bubbles. 60 61 When the bubble is clicked, it expands to a small window. This is called an expanded bubble. An 62 expanded bubble is an Activity. Use [setIntent][3] to specify an Activity to be lauched as the 63 expanded bubble. The Activity must be [resizeable][4] and [embedded][5]. It also has to be able to 64 launch as multiple instances, so set [documentLaunchMode][6] to "always". 65 66 You might want to provide a feature to let users explicitly show an expanded bubble when they 67 perform some actions, e.g. tapping on a button to show content in a bubble. For this, call 68 [setAutoExpandBubble][7] on BubbleMetadata.Builder. It may also make sense to suppress the initial 69 notification using [setSuppressInitialNotification][8] in this situation. These flags work only when 70 your app is in the foreground. *This feature does not yet work in Android Q Beta 2.* 71 72 Bubbles can also be shown explicitly when the app is in the foreground. 73 74 [1]: https://developer.android.com/reference/android/app/Notification.Builder.html#setBubbleMetadata 75 [2]: https://developer.android.com/reference/android/app/NotificationManager.html#IMPORTANCE_HIGH 76 [3]: https://developer.android.com/reference/android/app/Notification.BubbleMetadata.Builder.html#setIntent 77 [4]: https://developer.android.com/guide/topics/manifest/activity-element.html#resizeableActivity 78 [5]: https://developer.android.com/guide/topics/manifest/activity-element.html#embedded 79 [6]: https://developer.android.com/guide/topics/manifest/activity-element.html#dlmode 80 [7]: https://developer.android.com/reference/android/app/Notification.BubbleMetadata.Builder.html#setAutoExpandBubble 81 [8]: https://developer.android.com/reference/android/app/Notification.BubbleMetadata.Builder.html#setSuppressInitialNotification 82 83 ### When to use Bubbles instead of normal notifications 84 85 Bubbles take up screen real estate and cover other app content. You should only send a notification 86 as a bubble if it is important enough such as ongoing communications, or if the user has explicitly 87 requested a bubble for some content. 88 89 ### When Bubble is disabled 90 91 Note that the bubble can be disabled by the user. In that case, a bubble notification is shown as a 92 normal notification. You should always make sure your bubble notification works as a normal 93 notification as well. 94 95 ### Expanded Bubbles 96 97 System UI allows the user to horizontally swipe through expanded bubbles. You should avoid 98 horizontal scrolling content in your Activity for expanded bubbles. 99 100 ### About the sample 101 102 The sample is a dummy chat app. Talk to one of the chat bots, and it will reply back to you in 103 several seconds. The notification is not shown when the app is in the foreground, so just press back 104 or home before you get a reply. 105 106 - cat.jpg: Photo by [Erik-Jan Leusink](https://unsplash.com/photos/IbPxGLgJiMI?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/search/photos/cat?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) 107 - dog.jpg: Photo by [Lui Peng](https://unsplash.com/photos/ybHtKz5He9Y?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on Unsplash 108 - parrot.jpg: Photo by [Nikolay Tchaouchev](https://unsplash.com/photos/jJuq6oNfgRo?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on Unsplash 109 - sheep.jpg, sheep-full.jpg: Photo by [Luke Stackpoole](https://unsplash.com/photos/sfB_Nw9sggw?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on Unsplash 110 ]]> 111 </intro> 112 </metadata> 113 114 </sample> 115
