Condividi tramite


How to opt in for toast notifications (Windows Runtime apps)

Note  Not using C#/VB/C++? See How to opt in for toast notifications (HTML).

 

This topic explains how to specify that your app is capable of raising toast notifications.

What you need to know

Technologies

  • Windows Runtime

Prerequisites

To understand this topic, you need:

  • A working knowledge of toast notification terms and concepts. For more information, see Toast overview.
  • A familiarity with the toast XML schema as well as a general familiarity with XML and its manipulation through Document Object Model (DOM) APIs. For more information, see Toast schema.

Instructions

Step 1: Declare the toast notification capability

The capability to raise toast notifications is declared in your app's package.appxmanifest file. If you use the Microsoft Visual Studio manifest editor, simply set the Toast capable option to "Yes" in the Notifications section of the Application tab.

The following example shows the XML that is inserted in the package.appxmanifest file as a result of this option choice. The ToastCapable attribute is added to the manifest's VisualElements element.

This example also shows what to add if you are creating the package.appxmanifest file manually, outside of Visual Studio. For more information, see How to create a package manifest manually. Note that while the Visual Studio option is "Yes", what is written to the package.appxmanifest file is "true".

<VisualElements 
    ...
    ToastCapable="true">
</VisualElements>

Step 2: Declare a background and text color for your toast notifications

You can declare a background color and either light or dark text for your toast notification. Note that this setting also applies to your tiles—toast and tile notification background and text colors are always linked.

If you use the Visual Studio manifest editor, select the Foreground text option in the Visual Assets tab.

Note  For Windows Phone Store apps, you cannot set a text or background color. The toast's background color is the system accent color, which can be chosen by the user in Settings, and the text is always light.

Set the Background color option with a W3DC color string (for example, "#FFFFFF").

The following example shows the XML that is inserted in the package.appxmanifest file as a result of these choices. The ForegroundText and BackgroundColor attributes are added to the manifest's VisualElements element.

<VisualElements 
    ...
    ForegroundText="dark" 
    BackgroundColor="#FFFFFF">
</VisualElements>

Step 3: Specify a logo image

The app's small logo image is displayed in the lower right corner of each toast notification, to identify to the user which app has raised it.

Note  Windows Phone 8.1 does not use this logo image. The tile shows only the app's display name (stated in the manifest) or nothing.

If you use the Visual Studio manifest editor, set the Square 30x30 Logo (Windows) or Square 44x44 Logo (Windows Phone) image path in the Visual Assets tab. The specified image must be included in the app's package.

The following example shows the XML that is inserted in the package.appxmanifest file as a result of these choices. The SmallLogo attribute is added to the manifest's VisualElements element.

<VisualElements 
    ...
    SmallLogo="images\smallTile-sdk.png">
</VisualElements>

Remarks

After you have completed the steps above, your app can send toast notifications to the user.

Complete example

The following example shows the full XML for a sample Windows app's VisualElements element in its package.appxmanifest file, including the attributes discussed in this topic.

<VisualElements 
    DisplayName="ToastsSample" 
    Logo="images\squareTile-sdk.png" 
    SmallLogo="images\smallTile-sdk.png" 
    Description="SDK Sample" 
    ForegroundText="dark" 
    BackgroundColor="#FFFFFF" 
    ToastCapable="true">
    <DefaultTile ShortName="ToastsSample" ShowName="allLogos"/>
    <SplashScreen BackgroundColor="white" Image="images\splash-sdk.png"/>
</VisualElements>

Toast notifications overview

Guidelines and checklist for toast notifications

Toast notifications sample