NotificationsExtensions updated for Anniversary Update of Windows 10!


The Anniversary Update of Windows 10 brings a number of new Toast/Tile features. We've updated NotificationsExtensions (a NuGet package) to support these new features, and we also converged the Tile and Toast Adaptive content, so that you can share code between notifications.

New version number

Install NotificationsExtensions.Win10 version 14332.0.0 or higher. The major version number corresponds to the build of Windows 10. You can use 14332 even if your app is only targeting 10240 or 10586, since NotificationsExtensions doesn't take any dependencies on the newer Windows 10 SDK.

New features

Breaking changes

While converging Adaptive across Tiles and Toasts, we needed to make a few minor breaking changes. But we were able to limit these changes to two classes: TileBackgroundImage and TilePeekImage. Everywhere else, we left the old API surface functional (with Obsolete warnings) so that you don't need to change your code yet.

Changes on TileBackgroundImage/TilePeekImage

The Source property used to take a TileImageSource object, but we decided to make the API more consistent with the XML, so that Source simply takes a string of the image, and we moved the other TileImageSource properties onto the parent object.

Therefore, the changes are...

  • Source property's type changed from TileImageSource to string
  • AlternateText and AddImageQuery properties added
  • Overlay property renamed to HintOverlay
  • BackgroundImage HintOverlay won't work on first version of Windows 10
new TilePeekImage() /* And TileBackgroundImage */
{
    Source = new TileImageSource("http://msn.com/myimage")
    {
        Alt = "My image",
        AddImageQuery = true,
        Overlay = 30
    }
}
new TilePeekImage() /* And TileBackgroundImage */
{
    Source = "http://msn.com/myimage"
    AlternateText = "My image",
    AddImageQuery = true,
    HintOverlay = 30
}

HintOverlay for TileBackgroundImage will no longer work on the first version of Windows 10 (build 10240). Previously, we made this work by applying the overlay to the binding element in the XML, but now we're directly placing it on the image element (which only Version 1511 and newer of Windows 10 supports). The background overlay will default to 20% on those older systems. Note that for Peek images, the Overlay never worked until Version 1511 anyways, so there's no change there.

New features

The Anniversary Update of Windows 10 added some awesome new Toast features, and one commonly requested Tile feature.

Adaptive Toasts

ToastNotification

We brought the visual-richness of Live Tiles to Toast Notifications. You can now use Adaptive groups, subgroups, and images in your toast notifications. To learn how to send a Weather toast notification, see Quickstart: Sending a weather Tile and Toast Notification

new ToastBindingGeneric()
{
    Children =
    {
        new AdaptiveText()
        {
            Text = "Today will be mostly sunny with a high of 63 and a low of 42."
        },

        new AdaptiveGroup()
        {
            Children =
            {
                GenerateSubgroup("Mon", "Mostly Cloudy.png", 63, 42),
                GenerateSubgroup("Tue", "Cloudy.png", 57, 38),
                GenerateSubgroup("Wed", "Sunny.png", 59, 43),
                GenerateSubgroup("Thu", "Sunny.png", 62, 42),
                GenerateSubgroup("Fri", "Sunny.png", 71, 66)
            }
        }
    }
};

Adaptive converged across Tile and Toast

Since Toast Notifications now support the same Adaptive as tiles (for the most part at least, but Toast doesn't support some of the hints), we've converged the object model so that they share the same AdaptiveText, AdaptiveImage, AdaptiveGroup and AdaptiveSubgroup elements. That means you can share code across Tiles and Toasts if you want your Toast to look similar to your Tile Notification.

var title = new AdaptiveText()
{
    Text = "Text on my Tile and Toast!",
    HintMaxLines = 2,
    HintWrap = true
};

// Use AdaptiveText on your Tile
new TileBindingContentAdaptive()
{
    Children =
    {
        title
    }
};

// And also use it on your Toast!
new ToastBindingGeneric()
{
    Children =
    {
        title
    }
};

You'll notice that the previous API's, like TileText or ToastText, are still present, but they have Obsolete warnings on them. You can continue to use them, but any new features that we add in the future will only be present on the new API's.

Toast Hero Image

The Hero Image is a new image that gets displayed on the top of the toast. You could use an inline image, but a Hero Image gives the image additional importance. The typical use case is the messaging scenario where someone sent you a photo.

The Hero Image is specified on the new ToastBindingGeneric class that we added. The dimensions are 360 x 180, but if in doubt, provide an even higher resolution image so that your image looks crisp on high density displays. However, if you're using remote http images, make sure your image is less than 200 KB in size.

new ToastContent()
{
    Visual = new ToastVisual()
    {
        BindingGeneric = new ToastBindingGeneric()
        {
            Children = { ... }

            HeroImage = new ToastGenericHeroImage()
            {
                Source = "https://unsplash.it/360/180?image=1043"
            },

            AppLogoOverride = ...
        }
    }

    ...
};

Toast Attribution Text

Attribution text allows you to add attribution to your Toast Notification (highlighted in red above). If you're a news app, you might include the news source as attribution text. Edge uses this for web notifications, setting the website, like skype.com, as the attribution text.

This property specified on the new ToastBindingGeneric class.

new ToastContent()
{
    Visual = new ToastVisual()
    {
        BindingGeneric = new ToastBindingGeneric()
        {
            Children = { ... }

            Attribution = new ToastGenericAttributionText()
            {
                Text = "The Animal Times"
            }
        }
    }

    ...
};

Toast Context Menu Actions

You can now add additional actions for when the user right clicks the toast notification. For example, you might let the user easily disable a type of notification. Or you can provide an action that takes the user to your app's notification settings page, where they can fine tune notification settings for your app.

Context menu actions are specified in a new ContextMenuItems property on ToastActionsCustom.

new ToastContent()
{
    Visual = new ToastVisual()
    {
        ...
    },

    Actions = new ToastActionsCustom()
    {
        ContextMenuItems =
        {
            new ToastContextMenuItem("Turn off notifications for stories like this", "args")
            {
                ActivationType = ToastActivationType.Background
            }
        }
    }

    ...
};

Chaseable Tiles

When a user clicks on a tile notification, you finally can know which notification they clicked! For example, if you're a news app, you might want to make sure that the news story they clicked from the Live Tile is prominent and visible inside your app.

To learn how to implement Chaseable Tiles, see our documentation. NotificationsExtensions was updated to allow specifying the Arguments on the Tile Notification content.

TileContent content = new TileContent()
{
    Visual = new TileVisual()
    {
        Arguments = "storyClicked&story=20c45f",

        TileMedium = ...
        TileWide = ...
        TileLarge = new TileBinding()
        {
            Arguments = "storiesClicked&story=43f939&story=201c9", 
            ...
        }
    }
};
Comments (11)

  1. Brett says:

    Please change the Toast Attribution Text example to use this

    Attribution = new ToastGenericAttributionText()
    {
    Text = "The Animal Times"
    }

    instead of

    AppLogoOverride = = new ToastGenericAttributionText()
    {
    Text = "The Animal Times"
    }

    Thank you

    1. andrewbares7 says:

      Whoops! Thanks for catching that Brett, the example code has been updated!

  2. Abdussamad says:

    Hi Andrew,
    First of all, thank you and the rest of the team for the great work! Looking forward to further improvements to the notification and tile system.
    Has there been any change (of plans) to the ability to use custom notification sounds on Desktop? Last I checked it didn't work on 1511.

    1. andrewbares7 says:

      Hey Abdussamad, I'm looking into it, I'll let you know if it's possible or not.

    2. andrewbares7 says:

      So it turns out that custom toast audio for ms-appx:/// on PC *does* work on Version 1511!

      However, it only works on apps installed via the Store. So there's no way to test it before publishing to the Store. We're getting that fixed, but at least it should work!

      You'll have to make sure you don't include custom audio on older devices, since audio will become silent on those older devices.

      I'll try publishing an app to the Store with custom audio to test it out myself (I'll probably update Notifications Visualizer to include some audio files).

      1. Abdussamad says:

        Hi Andrew,

        Ah, thanks for looking into that for me. Great to hear it finally does! I'll test it out in my next beta update.
        Since it didn't work while debugging/deploying through Visual Studio, I assumed it doesn't work at all yet, so I'd implemented a conditional statement that replaces custom audio with the standard notification sound for non-Mobile device families haha, and never got to hear it work on Desktop. Even after deploying to the store.
        Does it work on all 10586 (1511) builds? And with older devices, you mean devices with 10240 builds? If so, I'd just have to modify my conditional statement to check the API contract version when on Desktop/Tablet.

        Thanks again and keep up the good work! 🙂

        1. andrewbares7 says:

          Correct, check the API contract for version 2 on desktop, and if so send the audio! Lemme know if it works. Not sure how soon I'll be able to test it out myself.

          EDIT: It works!

  3. Linda Liu says:

    I am using Azure Mobile app service to send push notification (toast). But the xml "<image placement='hero' " seems not working on there. I am using .NET backend.

    1. andrewbares7 says:

      Hey Linda, could you include a code snippet showing how you're constructing the BindingGeneric property? I'll try to repro your issue later today, but it might help if you include a code snippet of what you're doing! Thanks!

      1. Linda Liu says:

        Hi Andrew,

        I sent email to windowsnotifications@microsoft.com

        Does the new feature only available in latest Windows 10 device? Available in iPhone and Android phone as well?

        Thanks,

        Linda

        1. andrewbares7 says:

          Hey Linda! I responded to your email, but I'll also respond here so others can benefit!

          Correct, the “hero” image is only supported in the latest Anniversary Update of Windows 10 (which is currently available to Insiders, but not yet released to everyone).

          You have a few options…

          1) Make no changes - the hero image will be dropped on older systems – they won’t see any image. Maybe that’s okay.

          2) Send different toasts to specific OS versions - On your Azure database, include the OS build number of the devices that you’re sending push toasts to… and before you send the push notification, check if the OS build number is greater than 10.0.14332. If so, send the payload that includes the hero image. If not, send the payload using an inline image rather than hero image.

          3) Just use inline images for now – Inline images are supported on all versions. In a few months or year from now, you could change it to hero image, when you feel that most of your users have received the Anniversary Update.

Skip to main content