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[
27This 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
56In order to show a notification as a bubble, call [setBubbleMetadata][1] and set metadata to the
57Notification.Builder. [Notification.BubbleMetadata.Builder] can be used to create the metadata. You
58can set the icon and the desired height of the bubble. The notification has to be in a notification
59channel with [IMPORTANCE_HIGH][2] in order to prompt the user to allow bubbles.
60
61When the bubble is clicked, it expands to a small window. This is called an expanded bubble. An
62expanded bubble is an Activity. Use [setIntent][3] to specify an Activity to be lauched as the
63expanded bubble.  The Activity must be [resizeable][4] and [embedded][5]. It also has to be able to
64launch as multiple instances, so set [documentLaunchMode][6] to "always".
65
66You might want to provide a feature to let users explicitly show an expanded bubble when they
67perform 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
69notification using [setSuppressInitialNotification][8] in this situation. These flags work only when
70your app is in the foreground. *This feature does not yet work in Android Q Beta 2.*
71
72Bubbles 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
85Bubbles take up screen real estate and cover other app content. You should only send a notification
86as a bubble if it is important enough such as ongoing communications, or if the user has explicitly
87requested a bubble for some content.
88
89### When Bubble is disabled
90
91Note that the bubble can be disabled by the user. In that case, a bubble notification is shown as a
92normal notification. You should always make sure your bubble notification works as a normal
93notification as well.
94
95### Expanded Bubbles
96
97System UI allows the user to horizontally swipe through expanded bubbles. You should avoid
98horizontal scrolling content in your Activity for expanded bubbles.
99
100### About the sample
101
102The sample is a dummy chat app. Talk to one of the chat bots, and it will reply back to you in
103several seconds. The notification is not shown when the app is in the foreground, so just press back
104or 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