|
1 | | ---- |
2 | | -title: Custom timestamps on app notifications |
3 | | -description: Learn how to override the default timestamp on an app notification with a custom timestamp that indicates when the message/information/content was generated. |
4 | | -label: Custom timestamps on an notifications |
5 | | -template: detail.hbs |
6 | | -ms.date: 12/15/2017 |
7 | | -ms.topic: article |
8 | | -keywords: windows 10, windows 11, windows app sdk, winappsdk, uwp, toast, custom timestamp, timestamp, notification, Action Center |
9 | | -ms.localizationpriority: medium |
10 | | ---- |
11 | | -# Custom timestamps on app notifications |
12 | | - |
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 | | - |
15 | | -This feature is available in Windows Build 15063 and later. |
16 | | - |
17 | | -:::image type="content" source="images/toast-content-custom-timestamp.png" alt-text="App notification with custom timestamp"::: |
18 | | - |
19 | | -> [!NOTE] |
20 | | -> 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. |
21 | | -
|
22 | | - |
23 | | -To use a custom timestamp, simply assign the **displayTimestamp** property on the **toast** element of your app notification XML payload. Starting with Windows App SDK 1.2, you can add a custom timestamp to an app notification with the [Microsoft.Windows.AppNotifications.Builder](/windows/windows-app-sdk/api/winrt/microsoft.windows.appnotifications.builder). For UWP apps, you can use version 1.4.0 or later of the [UWP Community Toolkit Notifications NuGet library](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.Notifications/). You can also specify the timestamp using raw xml. |
24 | | - |
25 | | - |
26 | | -### [Windows App SDK](#tab/appsdk) |
27 | | - |
28 | | -```csharp |
29 | | -var builder = new AppNotificationBuilder() |
30 | | - .AddText("Matt sent you a friend request") |
31 | | - .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?") |
32 | | - .SetTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc)); |
33 | | -``` |
34 | | - |
35 | | -### [Community Toolkit](#tab/toolkit) |
36 | | - |
37 | | -```csharp |
38 | | -var builder = new ToastContentBuilder() |
39 | | - .AddText("Matt sent you a friend request") |
40 | | - .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?") |
41 | | - .AddCustomTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc)); |
42 | | -``` |
43 | | - |
44 | | -### [XML](#tab/xml) |
45 | | - |
46 | | -```xml |
47 | | -<toast displayTimestamp='2017-04-15T12:45:00-07:00'> |
48 | | - <visual> |
49 | | - <binding template='ToastGeneric'> |
50 | | - <text>Matt sent you a friend request</text> |
51 | | - <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text> |
52 | | - </binding> |
53 | | - </visual> |
54 | | -</toast> |
55 | | -``` |
56 | | - |
57 | | ---- |
58 | | - |
59 | | -If you are using XML, the date must be formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). |
60 | | - |
61 | | -> [!NOTE] |
62 | | -> You can only use at most 3 decimal places on the seconds (although realistically there's no value in providing anything that granular). If you provide more, the payload will be invalid and you will receive the "New notification" notification. |
63 | | -
|
64 | | - |
65 | | -## Usage guidance |
66 | | - |
67 | | -In general, we recommend that most apps specify a custom timestamp. This ensures that the notification's timestamp accurately represents when the message/information/content was generated, regardless of network delays, airplane mode, or the fixed interval of periodic background tasks. |
68 | | - |
69 | | -For example, a news app might run a background task every 15 minutes that checks for new articles and displays notifications. Before custom timestamps, the timestamp corresponded to when the app notification was generated (therefore always in 15 minute intervals). However, now the app can set the timestamp to the time the article was actually published. Similarly, email apps and social network apps can benefit from this feature if a similar pattern of periodic pulling is used for their notifications. |
70 | | - |
71 | | -Additionally, providing a custom timestamp ensures that the timestamp is correct even if the user was disconnected from the internet. For example, when the user turns their computer on and your background task runs, you can finally ensure that the timestamp on your notifications represents the time that the messages were sent, rather than the time the user turned on their computer. |
72 | | - |
73 | | - |
74 | | -## Default timestamp |
75 | | - |
76 | | -If you don't provide a custom timestamp, we use the time that your notification was sent. |
77 | | - |
78 | | -If you sent a push notification through WNS, we use the time when the notification was received by WNS server (so any latency on delivering the notification to the device won't impact the timestamp). |
79 | | - |
80 | | -If you sent a local notification, we use the time when the notification platform received the notification (which should be immediately). |
81 | | - |
82 | | - |
83 | | -## Related topics |
84 | | - |
85 | | -- [Send a local toast](send-local-toast.md) |
| 1 | +--- |
| 2 | +title: Custom timestamps on app notifications |
| 3 | +description: Learn how to override the default timestamp on an app notification with a custom timestamp that indicates when the message/information/content was generated. |
| 4 | +label: Custom timestamps on an notifications |
| 5 | +template: detail.hbs |
| 6 | +ms.date: 12/15/2017 |
| 7 | +ms.topic: article |
| 8 | +keywords: windows 10, windows 11, windows app sdk, winappsdk, uwp, toast, custom timestamp, timestamp, notification, Action Center |
| 9 | +ms.localizationpriority: medium |
| 10 | +--- |
| 11 | +# Custom timestamps on app notifications |
| 12 | + |
| 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 | + |
| 15 | +This feature is available in Windows Build 15063 and later. |
| 16 | + |
| 17 | +:::image type="content" source="images/toast-content-custom-timestamp.png" alt-text="App notification with custom timestamp"::: |
| 18 | + |
| 19 | +> [!NOTE] |
| 20 | +> 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. |
| 21 | +
|
| 22 | + |
| 23 | +To use a custom timestamp, simply assign the **displayTimestamp** property on the **toast** element of your app notification XML payload. Starting with Windows App SDK 1.2, you can add a custom timestamp to an app notification with the [Microsoft.Windows.AppNotifications.Builder](/windows/windows-app-sdk/api/winrt/microsoft.windows.appnotifications.builder). You can also specify the timestamp using raw XML. |
| 24 | + |
| 25 | + |
| 26 | +### [Windows App SDK](#tab/appsdk) |
| 27 | + |
| 28 | +```csharp |
| 29 | +var builder = new AppNotificationBuilder() |
| 30 | + .AddText("Matt sent you a friend request") |
| 31 | + .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?") |
| 32 | + .SetTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc)); |
| 33 | +``` |
| 34 | + |
| 35 | +### [XML](#tab/xml) |
| 36 | + |
| 37 | +```xml |
| 38 | +<toast displayTimestamp='2017-04-15T12:45:00-07:00'> |
| 39 | + <visual> |
| 40 | + <binding template='ToastGeneric'> |
| 41 | + <text>Matt sent you a friend request</text> |
| 42 | + <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text> |
| 43 | + </binding> |
| 44 | + </visual> |
| 45 | +</toast> |
| 46 | +``` |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +If you are using XML, the date must be formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). |
| 51 | + |
| 52 | +> [!NOTE] |
| 53 | +> You can only use at most 3 decimal places on the seconds (although realistically there's no value in providing anything that granular). If you provide more, the payload will be invalid and you will receive the "New notification" notification. |
| 54 | +
|
| 55 | + |
| 56 | +## Usage guidance |
| 57 | + |
| 58 | +In general, we recommend that most apps specify a custom timestamp. This ensures that the notification's timestamp accurately represents when the message/information/content was generated, regardless of network delays, airplane mode, or the fixed interval of periodic background tasks. |
| 59 | + |
| 60 | +For example, a news app might run a background task every 15 minutes that checks for new articles and displays notifications. Before custom timestamps, the timestamp corresponded to when the app notification was generated (therefore always in 15 minute intervals). However, now the app can set the timestamp to the time the article was actually published. Similarly, email apps and social network apps can benefit from this feature if a similar pattern of periodic pulling is used for their notifications. |
| 61 | + |
| 62 | +Additionally, providing a custom timestamp ensures that the timestamp is correct even if the user was disconnected from the internet. For example, when the user turns their computer on and your background task runs, you can finally ensure that the timestamp on your notifications represents the time that the messages were sent, rather than the time the user turned on their computer. |
| 63 | + |
| 64 | + |
| 65 | +## Default timestamp |
| 66 | + |
| 67 | +If you don't provide a custom timestamp, we use the time that your notification was sent. |
| 68 | + |
| 69 | +If you sent a push notification through WNS, we use the time when the notification was received by WNS server (so any latency on delivering the notification to the device won't impact the timestamp). |
| 70 | + |
| 71 | +If you sent a local notification, we use the time when the notification platform received the notification (which should be immediately). |
| 72 | + |
| 73 | + |
| 74 | +## Related topics |
| 75 | + |
| 76 | +- [Send a local toast](send-local-toast.md) |
86 | 77 | - [App notification content documentation](adaptive-interactive-toasts.md) |
0 commit comments