You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Remove version-specific language, update intro and cross-links
- Removed 'New in Anniversary/Creators/Fall Creators Update' prefixes
- Removed 'Requires X Update' notes (Win10 out of support)
- Simplified image size limits to current state
- Removed Desktop Version 1511 known issues
- Updated adaptive-interactive-toasts intro with index/quickstart links
- Removed toast terminology notes
- Fixed broken links to deleted legacy pages
- Kept Desktop-only platform constraints where still relevant
Co-authored-by: Copilot <[email protected]>
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/adaptive-interactive-toasts.md
+21-22Lines changed: 21 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,10 +11,7 @@ ms.localizationpriority: medium
11
11
---
12
12
# App notification content
13
13
14
-
App notifications are flexible notifications with text, images, and buttons/inputs. This article describes the UI elements that can be used in an app notification and provides code examples for generating the XML format for an app notification.
15
-
16
-
> [!NOTE]
17
-
> The term "toast notification" is being replaced with "app notification". These terms both refer to the same feature of Windows, but over time we will phase out the use of "toast notification" in the documentation.
14
+
This article describes the UI elements that can be used in an app notification and provides code examples for generating the notification content. For more information about app notifications, see [App notifications overview](index.md). For a walkthrough of implementing app notifications, see [Quickstart: App notifications in the Windows App SDK](app-notifications-quickstart.md).
18
15
19
16
## Getting started
20
17
@@ -25,13 +22,13 @@ App notifications are defined with an XML payload that is defined by the [App no
25
22
26
23
**Install Notifications Visualizer.** This free Windows app helps you design interactive app notifications by providing an instant visual preview of your toast as you edit it, similar to Visual Studio's XAML editor/design view. See [Notifications Visualizer](../notifications-visualizer.md) for more information, or [download Notifications Visualizer from the Store](https://apps.microsoft.com/detail/9nblggh5xsl1).
27
24
28
-
This article only covers creating the app notification content. For information on sending a notification after you have generated the XML payload, see [Send a local app notification](app-notifications-csharp-legacy.md).
25
+
This article only covers creating the app notification content. For information on sending a notification, see [App notifications overview](index.md).
29
26
30
27
## App notification structure
31
28
32
29
Some important, high-level components of an app notification XML payload include:
33
30
34
-
-**toast**: The **launch** attribute of this element defines what arguments will be passed back to your app when the user clicks your toast, allowing you to deep link into the correct content that the toast was displaying. To learn more, see [Send a local app notification](app-notifications-csharp-legacy.md).
31
+
-**toast**: The **launch** attribute of this element defines what arguments will be passed back to your app when the user clicks your toast, allowing you to deep link into the correct content that the toast was displaying. To learn more, see [App notifications overview](index.md).
35
32
-**visual**: This element represents visual portion of the toast, including the generic binding that contains text and images.
36
33
-**actions**: This element represents interactive portion of the toast, including inputs and actions.
37
34
-**audio**: This element specifies the audio played when the toast is shown to the user.
@@ -89,7 +86,7 @@ Each app notification must have at least one text element, and can contain two a
89
86
90
87

91
88
92
-
Since the Windows 10 Anniversary Update, you can control how many lines of text are displayed by using the **HintMaxLines** property on the text. The default (and maximum) is up to 2 lines of text for the title, and up to 4 lines (combined) for the two additional description elements (the second and third **AdaptiveText**).
89
+
You can control how many lines of text are displayed by using the **HintMaxLines** property on the text. The default (and maximum) is up to 2 lines of text for the title, and up to 4 lines (combined) for the two additional description elements (the second and third **AdaptiveText**).
93
90
94
91
95
92
### [Windows App SDK](#tab/appsdk)
@@ -198,7 +195,7 @@ var builder = new AppNotificationBuilder()
198
195
199
196
## Hero image
200
197
201
-
**New in Anniversary Update**: App notifications can display a hero image, which is a featured [**ToastGenericHeroImage**](toast-schema.md#toastgenericheroimage) displayed prominently within the toast banner and while inside Notification Center. Image dimensions are 364x180 pixels at 100% scaling.
198
+
App notifications can display a hero image, which is a featured [**ToastGenericHeroImage**](toast-schema.md#toastgenericheroimage) displayed prominently within the toast banner and while inside Notification Center. Image dimensions are 364x180 pixels at 100% scaling.
202
199
203
200

204
201
@@ -218,18 +215,18 @@ The images you use in your app notification can be sourced from...
218
215
- ms-appx:///
219
216
- ms-appdata:///
220
217
221
-
For http and https remote web images, there are limits on the file size of each individual image. In the Fall Creators Update (16299), we increased the limit to be 3 MB on normal connections and 1 MB on metered connections. Before that, images were always limited to 200 KB.
218
+
For http and https remote web images, there are limits on the file size of each individual image. The limit is 3 MB on normal connections and 1 MB on metered connections.
222
219
223
-
| Normal connection | Metered connection | Before Fall Creators Update |
224
-
| - | - | - |
225
-
| 3 MB | 1 MB | 200 KB |
220
+
| Normal connection | Metered connection |
221
+
| - | - |
222
+
| 3 MB | 1 MB |
226
223
227
224
If an image exceeds the file size, or fails to download, or times out, the image will be dropped and the rest of the notification will be displayed.
228
225
229
226
230
227
## Attribution text
231
228
232
-
**New in Anniversary Update**: If you need to reference the source of your content, you can use attribution text. This text is always displayed below any text elements, but above inline images. The text uses a slightly smaller size than standard text elements to help to distinguish from regular text elements.
229
+
If you need to reference the source of your content, you can use attribution text. This text is always displayed below any text elements, but above inline images. The text uses a slightly smaller size than standard text elements to help to distinguish from regular text elements.
233
230
234
231
On older versions of Windows that don't support attribution text, the text will simply be displayed as another text element (assuming you don't already have the maximum of three text elements).
235
232
@@ -266,7 +263,7 @@ var builder = new AppNotificationBuilder()
266
263
267
264
## Custom timestamp
268
265
269
-
**New in Creators Update**: You can now override the system-provided timestamp with your own timestamp that accurately represents when the message/information/content was generated. This timestamp is visible within Notification Center.
266
+
You can override the system-provided timestamp with your own timestamp that accurately represents when the message/information/content was generated. This timestamp is visible within Notification Center.
270
267
271
268

272
269
@@ -299,7 +296,7 @@ var builder = new AppNotificationBuilder()
299
296
300
297
## Progress bar
301
298
302
-
**New in Creators Update**: You can provide a progress bar on your app notification to keep the user informed of the progress of operations such as downloads.
299
+
You can provide a progress bar on your app notification to keep the user informed of the progress of operations such as downloads.
303
300
304
301

305
302
@@ -308,7 +305,7 @@ To learn more about using a progress bar, please see [Toast progress bar](toast-
308
305
309
306
## Headers
310
307
311
-
**New in Creators Update**: You can group notifications under headers within Notification Center. For example, you can group messages from a group chat under a header, or group notifications of a common theme under a header, or more.
308
+
You can group notifications under headers within Notification Center. For example, you can group messages from a group chat under a header, or group notifications of a common theme under a header, or more.
312
309
313
310

314
311
@@ -317,7 +314,7 @@ To learn more about using headers, please see [Toast headers](toast-headers.md).
317
314
318
315
## Adaptive content
319
316
320
-
**New in Anniversary Update**: In addition to the content specified above, you can also display additional adaptive content that is visible when the toast is expanded.
317
+
In addition to the content specified above, you can also display additional adaptive content that is visible when the toast is expanded.
321
318
322
319
This additional content is specified using Adaptive, which you can learn more about by reading the [Adaptive Tiles documentation](/windows/uwp/launch-resume/create-adaptive-tiles).
323
320
@@ -366,7 +363,7 @@ Here's an example where columns and some advanced adaptive text elements are use
366
363
367
364
Buttons make your toast interactive, letting the user take quick actions on your app notification without interrupting their current workflow. For example, users can reply to a message directly from within a toast, or delete an email without even opening the email app. Buttons appear in the expanded portion of your notification.
368
365
369
-
To learn more about implementing buttons end-to-end, see [Send local toast](app-notifications-csharp-legacy.md).
366
+
To learn more about implementing buttons end-to-end, see [App notifications overview](index.md).
370
367
371
368
Buttons can activate an app in the following ways:
372
369
@@ -546,7 +543,7 @@ var builder = new AppNotificationBuilder()
546
543
547
544
## Context menu actions
548
545
549
-
**New in Anniversary Update**: You can add additional context menu actions to the existing context menu that appears when the user right clicks your app notification or selects the context menu icon.
546
+
You can add additional context menu actions to the existing context menu that appears when the user right clicks your app notification or selects the context menu icon.
550
547
551
548
> [!NOTE]
552
549
> On older devices, these additional context menu actions will simply appear as normal buttons on your notification.
@@ -740,7 +737,7 @@ To use the system snooze and dismiss actions:
740
737
741
738
## Audio
742
739
743
-
Custom audio has always been supported on Mobile, and is supported in Desktop Version 1511 (build 10586) or later. Custom audio can be referenced via the following paths:
740
+
Custom audio can be referenced via the following paths:
744
741
745
742
- ms-appx:///
746
743
- ms-appdata:///
@@ -969,11 +966,13 @@ Your tiles and app notifications can load strings and images tailored for displa
969
966
970
967
971
968
## Handling activation
972
-
To learn how to handle app activations (the user clicking your toast or buttons on the toast), see [Send local toast](app-notifications-csharp-legacy.md).
969
+
To learn how to handle app activations (the user clicking your notification or buttons on the notification), see [App notifications overview](index.md).
973
970
974
971
## Related topics
975
972
976
-
*[Send a local toast and handle activation](app-notifications-csharp-legacy.md)
973
+
*[App notifications overview](index.md)
977
974
*[Tile and toast notification support for language, scale, and high contrast](/windows/uwp/launch-resume/tile-toast-language-scale-contrast)
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/custom-audio-on-toasts.md
-4Lines changed: 0 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,10 +24,6 @@ using Microsoft.Windows.AppNotifications.Builder;
24
24
25
25
## Add the custom audio
26
26
27
-
Windows Mobile has always supported custom audio in app notifications. However, Desktop only added support for custom audio in Version 1511 (build 10586). If you send a Toast that contains custom audio to a Desktop device before Version 1511, the toast will be silent. Therefore, for Desktop pre-Version 1511, you should NOT include the custom audio in your app notification, so that the notification will at least use the default notification sound.
28
-
29
-
**Known Issue**: If you're using Desktop Version 1511, the custom toast audio will only work if your app is installed via the Store. That means you cannot locally test your custom audio on Desktop before submitting to the Store - but the audio will work fine once installed from the Store. We fixed this in the Anniversary Update, so that custom audio from your locally deployed app will work correctly.
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/custom-timestamps-on-toasts.md
-2Lines changed: 0 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,8 +12,6 @@ ms.localizationpriority: medium
12
12
13
13
By default, the timestamp on app notifications, which is visible within Notification Center, is set to the time that the notification was sent. You can optionally override the timestamp with your own custom date and time, so that the timestamp represents the time the message/information/content was actually created, rather than the time that the notification was sent. This also ensures that your notifications appear in the correct order within Notification Center, which is sorted by time. We recommend that most apps specify a custom timestamp.
14
14
15
-
This feature is available in Windows Build 15063 and later.
16
-
17
15
:::image type="content" source="images/toast-content-custom-timestamp.png" alt-text="App notification with custom timestamp":::
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/notification-listener.md
+1-4Lines changed: 1 addition & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,9 +13,6 @@ ms.localizationpriority: medium
13
13
14
14
The notification listener provides access to a user's notifications. Smartwatches and other wearables can use the notification listener to send the phone's notifications to the wearable device. Home automation apps can use notification listener to perform specific actions when notifications are received, such as making the lights blink when you receive a call.
15
15
16
-
> [!IMPORTANT]
17
-
> **Requires Anniversary Update**: You must target SDK 14393 and be running build 14393 or later to use Notification Listener.
18
-
19
16
20
17
> [!NOTE]
21
18
> The Notification Listener APIs are part of the `Windows.UI.Notifications.Management` WinRT namespace and can be used by both UWP and Windows App SDK apps. For information about sending app notifications with the Windows App SDK, see [Quickstart: App notifications in the Windows App SDK](app-notifications-quickstart.md).
A common way to enable an app to listen to notifications is to set up a background task, so that you can know when a notification was added or dismissed regardless of whether your app is currently running.
182
179
183
-
Thanks to the [single process model](/windows/uwp/launch-resume/create-and-register-an-inproc-background-task) added in the Anniversary Update, adding background tasks is fairly simple. In your main app's code, after you have obtained the user's access to Notification Listener and obtained access to run background tasks by calling [UserNotificationListener.Current.RequestAccessAsync](/uwp/api/windows.ui.notifications.management.usernotificationlistener.requestaccessasync) and [BackgroundExecutionManager.RequestAccessAsync](/uwp/api/windows.applicationmodel.background.backgroundexecutionmanager.requestaccessasync) respectively, simply register a new background task, and set the [UserNotificationChangedTrigger](/uwp/api/windows.applicationmodel.background.usernotificationchangedtrigger) using the [Toast notification kind](/uwp/api/windows.ui.notifications.notificationkinds).
180
+
Thanks to the [single process model](/windows/uwp/launch-resume/create-and-register-an-inproc-background-task), adding background tasks is fairly simple. In your main app's code, after you have obtained the user's access to Notification Listener and obtained access to run background tasks by calling [UserNotificationListener.Current.RequestAccessAsync](/uwp/api/windows.ui.notifications.management.usernotificationlistener.requestaccessasync) and [BackgroundExecutionManager.RequestAccessAsync](/uwp/api/windows.applicationmodel.background.backgroundexecutionmanager.requestaccessasync) respectively, simply register a new background task, and set the [UserNotificationChangedTrigger](/uwp/api/windows.applicationmodel.background.usernotificationchangedtrigger) using the [Toast notification kind](/uwp/api/windows.ui.notifications.notificationkinds).
184
181
185
182
```csharp
186
183
// TODO: Request/check Listener access via UserNotificationListener.Current.RequestAccessAsync
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/toast-collections.md
-3Lines changed: 0 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,9 +11,6 @@ ms.localizationpriority: medium
11
11
# Grouping app notifications with collections
12
12
Use collections to organize your app's toasts in Action Center. Collections help users locate information within Action Center more easily and allow for developers to better manage their notifications. The APIs below allow for removing, creating, and updating notification collections.
13
13
14
-
> [!IMPORTANT]
15
-
> **Requires Creators Update**: You must target SDK 15063 and be running build 15063 or later to use toast collections. Related APIs include [Windows.UI.Notifications.ToastCollection](/uwp/api/windows.ui.notifications.toastcollection) and [Windows.UI.Notifications.ToastCollectionManager](/uwp/api/windows.ui.notifications.toastcollectionmanager).
16
-
17
14
> [!NOTE]
18
15
> Toast collections are managed through the `Windows.UI.Notifications` namespace and do not have direct equivalents in the Windows App SDK `Microsoft.Windows.AppNotifications` namespace. Windows App SDK apps can use these WinRT APIs for collection management alongside the `Microsoft.Windows.AppNotifications` APIs for constructing and sending notifications.
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/toast-headers.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,8 +12,8 @@ ms.localizationpriority: medium
12
12
13
13
You can visually group a set of related notifications inside Action Center by using a toast header on your notifications.
14
14
15
-
> [!IMPORTANT]
16
-
> **Requires Desktop Creators Update**: You must be running Desktop build 15063 or later to see toast headers. Headers are only supported on Desktop. For Windows App SDK apps, use the `AppNotificationBuilder` from the `Microsoft.Windows.AppNotifications.Builder` namespace to construct headers.
15
+
> [!NOTE]
16
+
> Headers are only supported on Desktop. For Windows App SDK apps, use the `AppNotificationBuilder` from the `Microsoft.Windows.AppNotifications.Builder` namespace to construct headers.
17
17
18
18
As seen below, this group conversation is unified under a single header, "Camping!!". Each individual message in the conversation is a separate app notification sharing the same toast header.
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/toast-pending-update.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,8 +14,8 @@ You can use **PendingUpdate** to create multi-step interactions in your app noti
14
14
15
15

16
16
17
-
> [!IMPORTANT]
18
-
> **Requires Desktop Fall Creators Update**: You must be running Desktop build 16299 or later to see pending update work. **PendingUpdate** is only supported on Desktop and will be ignored on other devices. For Windows App SDK apps, use the `AppNotificationBuilder` from the `Microsoft.Windows.AppNotifications.Builder` namespace to construct notification content.
17
+
> [!NOTE]
18
+
> **PendingUpdate** is only supported on Desktop and will be ignored on other devices. For Windows App SDK apps, use the `AppNotificationBuilder` from the `Microsoft.Windows.AppNotifications.Builder` namespace to construct notification content.
Copy file name to clipboardExpand all lines: hub/apps/develop/notifications/app-notifications/toast-progress-bar.md
-3Lines changed: 0 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,9 +12,6 @@ ms.localizationpriority: medium
12
12
13
13
Using a progress bar inside your app notification allows you to convey the status of long-running operations to the user, like downloads, video rendering, exercise goals, and more.
14
14
15
-
> [!IMPORTANT]
16
-
> **Requires Windows 10 Creators Update**: You must target SDK 15063 and be running build 15063 or later to use progress bars on notifications.
17
-
18
15
A progress bar inside an app notification can either be "indeterminate" (no specific value, animated dots indicate an operation is occurring) or "determinate" (a specific percent of the bar is filled, like 60%).
0 commit comments