How to opt in for toast notifications (Windows Runtime apps)
Note Not using JavaScript? See How to opt in for toast notifications (XAML).
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 (Windows only)
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. Set the Background color option with a W3DC color string (for example, "#FFFFFF").
Note Windows Phone Store apps do not allow you to 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.
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>