Guidelines and checklist for tiles and badges (Windows Store apps)
This topic describes best practices, troubleshooting, and globalization/localization recommendations for use when creating and updating your app's tile, both on the Start screen and on the lock screen, and lists any special tile-related requirements your app needs to meet to be accepted in the Windows Store.
A tile is an app's representation on the Start screen. A tile allows you to present rich and engaging content to your user on Start when your app is not running. Tapping or clicking the tile launches the app. Tiles come in two sizes: square and wide. Several template variations are provided for each size, with text, image(s), or a combination of text and image(s). Templates can have a single frame or two stacked frames, which is called a peek template. A tile based on a peek template animates between the two frames within the tile space. Single-frame templates do not animate.
In one corner, a tile can optionally show branding, as the app's name or a small logo image.
Tiles can be live (updated through notifications) or you can leave them static. Tiles begin as a default tile, defined in the app's manifest. A static tile will always display the default content, which is generally a full-tile logo image. A live tile can update the default tile to show new content, but can return to the default if the update expires or is removed. In the corner opposite to its branding, a tile can also display a status badge, which can be a number or a glyph.
Two very important points to always remember:
- If you use a wide tile, the user can resize the tile from wide to square or square to wide at any time. You don't know which size is currently displayed.
- The user can turn tile notifications off and on at any time.
This section talks about guidance that you should follow and design considerations that you should keep in mind when you plan how your tiles will look and how they will be used.
- Tile design philosophy
- Choosing between a square and wide tile size
- Using default tiles
- Using peek templates
- Other design considerations
- Using tile notifications
Your goal is to create an appealing tile for your app. If you use a live tile, your goal is to present engaging new content that the user will find valuable to see in their Start screen and that invites them to launch the app. To that end, avoid the overuse of loud colors. Simple, clean, elegantly designed tiles will be more successful than those that scream for attention like a petulant child.
When designing your app, you might ask yourself "Why should I invest in a live tile?" There are several reasons:
- Tiles are the "front door" to your app. A compelling live tile can draw users into your app when your app is not running. A user increasingly values an app that they use frequently.
- A live tile is a selling point that differentiates your app, both from other apps in the Windows Store (users are likely to prefer the app with the great live tile to a similar app with a static tile) and from apps on operating systems that only allow static tiles and icons in their Start screen.
- If users like your live tile, a prominent placement of that tile in Start will drive re-engagement with your app. Serendipitous discovery of cool content in the app through the tile will make users happy.
- If users don't like your tile, they might place it at the end of Start or unpin it altogether, turn off updates, or even uninstall your app.
Some characteristics that make a live tile compelling are:
Fresh, frequently updated content that makes users feel that your app is active even when it's not running.
Example: Showing the latest headlines or a count of new e-mails.
Personalized or tailored updates that use what you know about the user, such as interests that you allow the user to specify through app settings.
Example: Deals of the day tailored to the user's hobbies.
Content relevant to the user's current context.
Example: A traffic condition app that uses the user's current location to display a relevant traffic map.
Your app will always have a square tile. You must decide whether you want to allow for a wide tile as well. This choice is made by providing a wide logo image when you define your default tile in your manifest. If you do not include a wide logo image, your tile will only be square; it cannot be resized by the user and it cannot accept wide notifications. To change that situation, you would release a new version of your app with an updated manifest that includes a wide logo image.
- Use only a square tile if your app will not use tile notifications to send updates to the user. Wide tile content should always be fresh and regularly updated. If you aren't using a live tile, do not provide a wide logo in the manifest.
- Use only a square tile with a badge if your app supports only scenarios with short summary notifications—that is, notifications that can be expressed through only a badge image or a single number. For instance, an SMS app that plans to use notifications to communicate only the number of new texts received would fit this scenario. Do not provide a wide logo in the manifest.
- Use only the square size if your app sends updates that should not be shown in detail on the Start screen. For instance, a paystub app could simply say that a new paystub is available instead of mentioning specifics such as the amount. Do not provide a wide logo in the manifest.
- Use the wide size tile only if your app has new and interesting content to display to the user and those notifications are updated frequently (at least weekly).
Square tiles show less content than wide tiles, so prioritize your content. Don't try to fit everything that you can show in a wide tile into a square tile.
If you have wide tile content that consists of an image plus text, you can use a square peek template to break the content into two frames.
Notifications will often include both a wide and square template, because it cannot know the current size of the tile. If a notification is defined using only a wide template and the tile is displayed as square, or if the notification is defined using only a square template and the tile is displayed as wide, the notification will not be shown.
An app's default tile is defined in its manifest. It is static, square or wide, and generally simple in design. For some apps, the default tile is all that you'll ever need. When an app is installed, the default tile is shown on the Start screen until that tile receives a notification. If a wide logo image is provided, the wide tile will be used. An update can expire or be explicitly removed, in which case the tile will revert to the default content until the next notification arrives.
- Use the default tile image to reflect your app's brand, essentially as a canvas for your app's logo.
- If you are including a wide logo, consider the design relationship between the wide and square tile images that you will provide. Always remember that the user has the option to display your tile as either square or wide and can change that option at any time. Here are some general rules:
- Center the logo horizontally in the tile.
- Keep the same vertical placement of the logo in both the square and wide tiles, which are of equal height.
Include the app name at the bottom of the tile if your logo does not include it. The following examples show both situations.
Tiles using the app name element defined in the manifest:
Tiles that include the app's name in the logo image:
- For apps with longer names, and because the name can wrap over two lines, make sure that your logo image and the name do not overlap. A safe approach is to restrict your logo to about 80x80 pixels in the 100% image resource.
- If you make the space around the logo itself transparent in your image, your app's brand color (declared in the manifest) will show through with a gradient preapplied to it as part of the Windows 8 look. This tactic would be used with a logo such as the mail app tile shown earlier.
- Don't design the default tile to include an explicit text call to launch the app, such as a tile that says "Click Me!"
If your logo contains your app's name, don't repeat that name in the name field. Use one or the other, as shown here:
Peek templates supply tile content which cycles between two frames of information within the tile space. The upper frame is an image or image collection, and the lower frame is text or text plus an image. For examples, see The tile template catalog.
- Use peek templates if your scenario has both primary and supplementary content and contains both images and text. Good examples include notifications for an e-mail that included a photo or a news story with a picture/header/body layout.
- A peek template grabs the user's attention when it animates, so be sure that it provides desirable content. Otherwise, you will just annoy your user.
- When you use a peek template, its display can start at either end (frame) of its cycle—text fully lowered or text fully raised—and animate up or down to the other frame. Therefore, make sure that the contents of each of your frames can stand alone.
- Don't use peek templates to display information about things the user already knows about. For example, a paused video notification shown on a tile shouldn't use a peek template.
- Don't use peek templates for notifications that are not conceptually grouped. For example, a peek template should never be used to send a news story if the photo or photos are not part of that story.
- Don't use peek templates if the most important part of your notification could be off-screen due to the peek animation. For example, for a weather app that displays the temperature and an accompanying image (a smiling sun or a cloud), using a peek template would mean that the temperature (the point of the notification) isn't always visible. A static template that shows the image and temperature at the same time would be more useful to the user.
When determining how to convey an app's brand information in a tile, choose either the app's name, as shown here:
or logo image, as shown here:
These items are originally defined in the app manifest and the developer can choose which of the two to display in each subsequent notification. However, after you make the choice of name or logo, you should stick with it for the sake of consistency.
Don't use the image or text elements to display app branding information in a tile notification. To reinforce your app's brand and provide consistency to the user, branding should be provided through the template's elements provided for that purpose: the app name (short name) or logo image. A live tile can change its appearance considerably from notification to notification, but the location of the name/logo is consistent. This ensures that users can find their favorite apps through a quick scan, seeing that information in the same place on each tile. If your app doesn't leverage the provided branding elements (name and logo), then it can be harder for users to quickly identify your app's tile.
The following images show tiles that use the template's text and image elements to inappropriately convey branding. Note that in both cases, the tiles are also using the name or logo as designed, so the additional branding is redundant information.
For more information on the name and logo image, see Quickstart: Creating a default tile using the Microsoft Visual Studio manifest editor.
- Don't use branding as one of the items in the notification queue or as one of the frames in a peek template. Both of these scenarios involve animated changes to the tile, which catches the user's eye. Calling the user's attention through an animation simply to display your brand instead of interesting new content will only annoy that user.
- If your app's name does not fit in the space provided by the optional "short name", use a shorter version or a meaningful acronym. For example, you could use "Contoso Game" for the very addictive "Contoso Fun Game Version 3". Names that exceed the maximum number of pixels are truncated with an ellipsis. The maximum name length is approximately 40 English characters over two lines, but that varies with the specific letters involved. We encourage shorter app names from a design standpoint. Note that you can also specify a longer name for your app (the "display name") in your manifest. This name is used in the "All apps" view and in the tooltip, though not on the tile.
- Don't use tiles for advertisements.
- Avoid the overuse of loud colors in tiles. Simple, clean, elegantly designed tiles will be more successful than those that scream for attention like a petulant child.
- Don't use images with text on them; use a template with text fields for any text content. Text in an image will not look as sharp as rendered tile text. If an image asset isn't provided that is appropriate to the current display, the image might be scaled, which can further degrade its legibility.
- Don't rely on tiles to send urgent, real-time information to the user. For instance, a tile is not the right surface for a communication app to inform the user of an incoming call. Toast notifications are a better medium for messages of a real-time nature.
- Avoid image content that looks like a hyperlink, button, or other control. Tiles do not support those elements and the entire tile is a single click target.
- Don't use relative time stamps or dates (for instance, "two hours ago") on tile notifications because those are static while time moves on, making the message inaccurate. Use an absolute date and time such as "11:00 A.M.".
There are several mechanisms which can be used to update a live tile:
- Local API calls
- One-time scheduled notifications, using local content
- Push notifications, sent from a cloud server
- Periodic notifications, which pull information from a cloud server at a fixed time interval
The choice of which mechanism to use largely depends on the content you want to show and how frequently that content should be updated. The majority of apps will probably use a local API call to update the tile when the app is launched or the state changes within the app. This makes sure that the tile is up-to-date when it launches and exits. The choice of using local, push, scheduled, or polling notifications, alone or in some combination, completely depends upon the app. For example, a game can use local API calls to update the tile when a new high score is reached by the player. At the same time, that same game app could use push notifications to send that same user new high scores achieved by their friends.
For more information on choosing the right mechanism to update your tile, see Choosing a notification delivery method.
If you choose to use a live tile, consider how often the tile should be updated.
- For personalized content, such as message counts or whose turn it is in a game, we recommend that you update the tile as the information becomes available, particularly if the user would notice that the tile content was lagging, incorrect, or missing.
- For nonpersonalized content, such as weather updates, we recommend that the tile be updated no more than once every 30 minutes. This allows your tile to feel up-to-date without overwhelming your user.
Use what you know about the user to send personalized notifications to them through the tile. Tile notifications should be relevant to the user. The information you have to work with will be largely internal to your particular app and could be limited by a user's privacy choices. For example, a television streaming service can show the user updates about their most-watched show, or a traffic condition app can use the user's current location (if the user allows that to be known) to show the most relevant map.
- Send frequent updates to the tile so the user feels that the app is connected and receiving fresh, live content. The cadence of tile notifications will depend on your specific app scenario. For example, a busy social media app might update every 15 minutes, a weather app every two hours, a news app a few times a day, a daily offers app once a day, and a magazine app monthly. If your app will update less than once a week, consider using a simple square tile with a badge to avoid the appearance of stale content.
- Provide engaging and informative tile notifications so that users can make an informed decision about whether they need to launch your app. In general, a notification is an invitation to the user to launch the app for more details or to perform an action. For example, a notification might cause the user to want to respond to a social media post, read a full news story, or get the details about a sale.
- Send notifications about content hosted on the home or landing page of your app. That way, when the user launches your app in response to your notification, they can easily find the content that the notification was about.
- Don't use live tiles if you don't have interesting, new, personalized content for the user. A calculator app, for instance, just isn't going to have that.
- Don't use live tiles if the only interesting thing to communicate is the user's last state. Utility apps, developer tools like Microsoft Visual Studio, and browsers that would only show thumbnails of the user's last session should not use live tiles.
- Don't use live tiles to spam the user or show advertisements. That will get you kicked out of the store.
- Use the square tile size with a badge if your app supports only scenarios with short summary notifications. For instance, a short message service (SMS) app that plans to show only the number of new texts received.
- Display a number on your badge when the number is small enough to be meaningful in your scenario. If your badge is likely to always display a number of 50 or higher, then consider using a system glyph. Strategies to make the a badge number less overwhelming include showing the count since the user last launched the app rather than the absolute count. For instance, showing the number of missed calls since the user last launched the app is more useful than showing the total number of missed calls since the app was installed.
- Use one of the provided system glyphs to indicate a change in cases where a number would be unhelpful or overwhelming. For instance, the number of new unread articles on a high volume RSS feed can be overwhelming. Instead, use the newMessage system glyph.
- Use a glyph if a number is not meaningful. For instance, if the tile shows a "paused" notification for a playlist, it should use the paused glyph because a number doesn't make any sense for this scenario.
- Use the newMessage glyph in cases where a number is ambiguous. For instance, "10" in a social media tile badge could mean 10 new requests, 10 new messages, 10 new notifications, or some combination of them all.
- Use the newMessage glyph in high-volume scenarios, such as mail or some social media, where the tile's badge could be continually displaying the maximum value of "99+". It can be overwhelming for the user to always see the maximum value and it conveys no useful information by remaining constant.
- Don't repeat badge numbers elsewhere in a wide tile's body content, because the two instances could be out of sync at times.
- Don't use a glyph if what the glyph tells the user never changes. Glyphs represent notifications and transient state, not any sort of permanent branding or state.
To determine whether your app is a good candidate for a lock screen presence, you must understand the operation and limitations of the lock screen. A summary of the lock screen is given here. For more information, see the Lock screen overview.
- A maximum of seven app badges can appear on the lock screen. The badge information reflects the badge information on the app's Start screen tile. The badge (either a glyph or a number) is accompanied by a monochrome icon (logo image) to identify the app the badge is associated with.
- Only one of those seven apps can occupy a detailed status slot, which allows it to display the text content of the app's most recent tile update.
- The lock screen's detailed status tile does not show images included in that tile update.
- The user is in charge of which apps can display information on the lock screen, and which one of those apps can display detailed status.
- All apps that have a lock screen presence can also run background tasks. All apps that can run background tasks have a lock screen presence. An app cannot use background tasks without also claiming a slot on the lock screen.
- The notification queue is not supported by the lock screen's detailed status tile. Only the latest update is shown.
- An app with a lock screen presence, as long as it has set the Toast Capable option to "Yes" in its manifest, displays its received toast notifications on the lock screen when the lock screen is showing. Toast shown on the lock screen is identical to toast shown elsewhere.
- Tile updates, badge updates, and toast notifications are not specifically designed for or sent to the lock screen. You, as the sender, don't know if the device is currently locked. For an app with a lock screen presence, any notification is reflected both on the Start screen and on the lock screen.
The only way that your app can have a lock screen presence is if the user gives their explicit permission. They can do this either in response to a request from your app (and you can ask only once), or manually through the Personalize page of PC Settings. By giving that permission, the user declares that the information coming from your app is important to them. Your app must then be worthy. Therefore, you must consider whether your app is a good candidate to have a lock screen presence at all.
A good candidate for a lock screen presence will have these attributes:
- The information is quickly digestible
- The information is always up-to-date
- The information is understandable without additional context
- The information should be personal and useful to the user
- The information should display only when a change has occurred
- Only toast notifications should play a sound on arrival
If the lock screen is displayed, the user isn't currently interacting with the device. Therefore, any update information that your app displays on the lock screen should be something that the user can take in and understand at a glance. As an analogy, think of an incoming call on a cell phone. You glance at the phone to see who's calling and either answer or let it go to voice mail. Information displayed on the lock screen should be as easy to take in and deal with as the cell phone display. All of the other characteristics support this one.
Good badge updates, tile updates, and toast notifications, whether they're shown on the Start screen or the lock screen, are all potentially actionable. Based on the information those notifications provide, the user can decide whether they want to launch the app in response, such as to read a new e-mail or comment on a social media post. From the lock screen, that also means unlocking the device. Therefore, the information needs to be up-to-date so that the user is making an informed decision. If users begin to see that your app's information on the lock screen is not up-to-date, then you've lost their trust and they'll probably find a more reliably informative app to occupy that lock screen slot.
A messaging app sends a notification when a new message arrives. If that notification is ignored, the app updates its badge with a count of missed messages. If the user is present, they can turn on the screen to assess the importance of the message, and choose to respond promptly or let it wait. If the user isn't present, they will see an accurate count of missed messages when they return.
A mail app uses its badge to display a count of its unread mail. It updates the badge immediately when a new mail arrives. A user can quickly turn on their screen to check how many unread emails they have, and they can be assured that the count is accurate. They have the information to decide if they want to unlock their device and read mail.
- A messaging app updates its badge with its count of missed messages only once every half hour. The user can't rely on the badge count in deciding whether they want to unlock the device.
- A weather app that uses the detailed status slot continues to show a severe weather alert after the alert has expired. This not only gives the user incorrect information, but is particularly egregious if the text specifies when the alert ends, making it obvious to the user that this is old information. The user loses confidence that the app is capable of keeping them properly informed. The app should have cleared this information when it expired.
- A calendar app continues to display an appointment that has passed. Again, the app should have cleared this information when it expired.
This contextual information is not present on the lock screen:
- The tile that goes with the badge, when the app is not allowed to display detailed status. Even when detailed status is shown, the badge is physically separate from the tile. The logo image next to a badge is the only identification of the app it represents.
- Images in tile updates. Only the text portion of the update is shown in the detailed status slot.
- The notification queue. Only the most recent update is shown in the detailed status slot.
Therefore, your updates must be understandable to the user without the additional context available to you on the Start screen. Again, keep in mind that notifications cannot be specifically targeted at the lock screen. Therefore, all of your app's update communications must fall under the "understandable without additional context" rule.
Note Unlike the detailed tile, toast includes both image (if present) and text—toast displayed on the lock screen is identical to toast displayed elsewhere, so it does not lose context.
- A mail app uses its badge to display the count of its unread mail. While its Start screen tile might display more information, such as text snippets from the most recent mails or pictures of the senders, what the badge is communicating is understandable without that extra information.
- A social networking app uses the detailed status slot to inform the user of their friends' recent activity. When a friend sends them a message, that friend's name is included in the notification text (for instance "Kyle sent you a new message!"). On the Start screen, the user can see a rich experience with their friend's picture in the notification, while on the lock screen, even though there is no image, the text still makes it clear who sent the message.
- A messaging app updates its tile with the latest received message, and shows only the sender's picture and the message text. In the Start screen, it is clear to the user who the message is from. In the lock screen, without the sender's picture, the user has no idea who sent the message.
- A social networking app updates its tile with a collage of photos, with no text. In the Start screen this is a pleasant, lively tile. On the lock screen, because there is no text in the tile update, nothing is displayed at all.
Two of the main purposes of the lock screen are to provide a personalized surface for the user and to display app updates. Consider both of these purposes when you judge whether your app is a good candidate for a lock screen presence.
Apps with a lock screen presence are very special—only seven can ever be on the lock screen at a time. By giving an app one of those precious lock screen slots, the user is stating that information coming from that app is important enough to be seen even when the user isn't actively using their device. Therefore, the app should provide information that is both personal and useful to the user.
Note By definition, the lock screen is displayed when the device is locked. No login or other security hurdle is required to see the contents of the lock screen. Therefore, while the information displayed there is ideally personalized, keep in mind that anyone can see it.
- A mail app displays the number of unread emails in the user's account.
- A messaging app displays the number of missed messages sent to the user.
- A news app displays the number of new articles in categories that a user has flagged as favorites.
- A news app displays the total number of new articles coming from its service, not taking into account the user's stated preferences.
- A shopping app sends a notification about a sale, but not based on any item or category preference that the user has given.
As we said earlier, the goal is that information on the lock screen can be taken in at a glance. To that end, if an app is not currently displaying a badge, a gap is left on the lock screen where that badge would otherwise appear. This increases the ability of a user to notice something that needs their attention—the appearance of a badge and logo following an event is more noticeable than if it has been there all along, communicating nothing new.
Do not show status simply for the sake of showing status. Long-running or never-changing status just clutters the lock screen, obscuring more important information. A badge should display only when something has happened that the user should be aware of. The same is true for a tile update. Remove stale notification content from your tile, which causes the tile to revert to its default image in the Start screen and displays nothing on the lock screen.
- A mail app displays a badge only when there is unread mail. When new mail arrives, its badge is updated and shown.
- A messaging app displays its connection status only when the user is unable to receive messages. A "connected" status is the assumed default state of the app, so there is no point in conveying that information. "Everything is fine" is not an actionable notification. However, informing the user when they cannot receive messages is useful, actionable information.
- A mail or messaging app has no count of unread mail to display and so shows a connection status until new mail or messages arrive. This decreases the user's ability to see at a glance whether they have a new message, because the badge is always present.
- A calendar app displays a message stating that the user has no appointments. Again, this decreases the at-a-glance usability of the detailed status slot, since something would always be displayed there.
Do not include code in your app that plays a sound when your badge or tile updates. However, an arriving toast can play a sound as it is designed to do.
By following the guidance described in this article, you will be able to create apps that display the right information in the right way on the lock screen, thereby increasing user satisfaction and confidence in your app.
Only call the lock screen request API (RequestAccessAsync) if your app truly needs background privileges to function properly. Because there are only seven background slots available, users must distinguish which apps truly need background privileges to function properly and which work fine without them (even if they might gain additional functionality with them).
If an app absolutely requires background privileges to meet user expectations, we recommend that it uses the request API to prompt the user to place the app on the lock screen.
However, if an app will meet user expectations without having background privileges, we recommend that you do not explicitly prompt the user to place the app on the lock screen. Instead, let the user place their app on the lock screen through the Personalize page of PC Settings.
Examples of apps that should call the request API:
- A messaging app that requires background privileges to receive messages when the app is not in the foreground
- A mail app that requires background privileges to sync the user's inbox when the app is not in the foreground
Examples of apps that should not call the request API:
- A weather app that uses periodic notifications rather than background activity to update its forecast
- A news app that refreshes its badge count of new articles at a specific time of day
Note Your app should not implement its own dialog to prompt users to add the app to the lock screen. If your app requires lock screen access to run properly, you should rely on the dialog presented by the lock screen request API. If a user previously denied lock screen rights to your app through this dialog, the dialog may not be shown again. In this case, you can use inline text in your app to direct users to the Personalize page of PC Settings to manually add your app to the lock screen.
This section addresses some common errors you might encounter while working with tiles and tile templates. Unless specified otherwise, each solution applies to all notification delivery types: local, scheduled, periodic, or push notifications.
There may also be specific troubleshooting steps to follow for your notification's delivery method. For more information, see these topics:
- Guidelines and checklist for periodic notifications
- Guidelines and checklist for scheduled notifications
- Guidelines and checklist for push notifications
The most common problem in this situation is that the XML used to define your notification is incorrect in some way. However, there are other possible causes, which these steps walk you through:
- Check user settings
- Provide wide logo resources in the app manifest
- Check your image sizes
- Verify your URLs
- Examine your image formats
- Check the syntax of your XML
- Check your notification's expiration time
- Ensure that you've enabled the notification queue
Possible cause: The user or administrator has disabled notifications through settings. Check whether the app has supplied a Turn live tile on/off option in the app bar, and that it isn't turned to "off". As for the administrator, there are several group policies which can disable notifications. Check with your administrator to ensure that notifications are enabled.
Fix: Enable notifications through settings or have an administrator enable notifications through group policy.
For more information, see TileUpdater.Setting.
Possible cause: The app manifest did not specify a default wide tile resource image. If the default wide tile image is not provided, the tile will never display wide-format notification templates. Additionally, tile notifications should provide both a wide and square template in the notification payload because, unless the tile intentionally does not have a wide image, the sender is never guaranteed whether the tile will be displayed as square or wide when the notification arrives. That setting is entirely up to the user.
Fix: Provide a default wide logo image resource in the app manifest.
Possible cause: Images for all notifications must be smaller than 1024 x 1024 pixels and less than 200 KB in size. If any image in a notification exceeds any of these dimensions, the notification will be discarded.
Fix: Shrink your images.
For more information, see Tile and toast image sizes.
Possible cause: URL syntax errors.
Images in notifications are given as a resource reference or a literal path. If a path is used, it must be given using one of these three protocols:
|http:// and https://||Images stored online||
These images might be cached locally, so your image server might not receive a request for the image. Query strings may be appended to these URLs. Make sure your web server returns the original image rather than a 404 if you choose to ignore the query string. An example query string: ?scale=100&contrast=blk&lang=en-US
Note that to retrieve any notification content from the Internet, your app must declare the "Internet (Client)" capability in its app manifest.
|ms-appx:///||Images included with your app's package||The Uniform Resource Identifier (URI) accepts either forward slash (/) or backward slash (\) to separate folders in a path, but most programming languages require you to use an escape character when you specify a backward slash (\\). Note that this reference requires a triple forward slash after the colon.|
|ms-appdata:///local/||Images saved locally by your app||This location corresponds to the folder returned by Windows.Storage.ApplicationData.current.localFolder. Folder separators in the path must use escape characters (\\). Note that this reference requires a triple forward slash after the colon.|
Note The '/' character works as a separator in every specification type. We recommended that you use '/' instead of '\' at all times to avoid inadvertent confusion with escape characters.
|http://www.contoso.com\fail.png||An HTTP path must use the / character. Do not use the \ character.|
|http:www.contoso.com||An HTTP path requires a double-slash (//) after the colon.|
|"ms-appdata:///local/c:\\images\\Drawing.jpg"||An app cannot reference images outside of its local storage.|
|"ms-appx://images/triangle.png"||Use a triple-slash rather than a double-slash with "ms-appx:".|
Possible cause: Images are in an unsupported format.
Notifications can only use images in .gif, .png, or .jpg/.jpeg format. The format of the image must also match its extension. Merely renaming an unsupported file type with a supported extension won't work.
The most common cause of image format errors is serialization of bitmaps to the Windows.Storage.ApplicationData.current.localFolder storage. Be sure to invoke your preferred format, or the image will be stored as a Windows bitmap and its header will include "BMP".
To verify: First, verify that you can successfully send a text-only notification to narrow the problem down to the image. One way to verify your image format is to load your image into an image processing program and save as a .jpg. If you reference this new .jpg file in your notification and the error does not recur, it was probably an image format error. You can also open the file in the Visual Studio binary editor and examine its header.
Fix: Change or correct your image formats.
Possible cause: XML syntax or validation errors.
Apart from basic syntax, make sure that your XML is complete and correct. Some common points of failure in the XML content include the following:
- Case sensitivity. Tag names, attribute names, and attribute values are all case sensitive. Be sure that your XML has the correct casing.
- A binding element must be provided for each tile size. If you support wide tiles, you should provide both square and wide template binding elements for each tile you send.
- Text strings should not contain reserved XML characters. For example, you cannot italicize tile strings by including <i> and </i> tags. If you intend to show the literal characters "<i>", they should be properly escaped. For more information on escape characters in XML, see XML Character Entities and XAML.
- The values supplied for the lang attributes must conform to the ITEF BCP 47 specification.
- XML strings created locally (for local or scheduled notifications) must use the UTF-8 encoding. When sent through push notifications or polled from a URL, the strings should use the UTF-16 encoding.
- If you include an image element in your XML payload with a non-empty src attribute, you must be sure to include a reference to a valid image or the notification will fail.
You can use the Event Log to check for errors when your tile notification does not display. Look for events involving your tile notification in the Event Viewer under Applications and Services Logs > Microsoft > Windows > Immersive-Shell > Microsoft-Windows-TWinUI > Operational.
To verify: Use an XML syntax checker, such as the Visual Studio editor, to look for basic syntax errors. Look at the appropriate template reference (TileTemplateType) to make sure that you have the right number of images and that you're assigning the right images to the right image index.
Fix: Change your XML or use a different template to match your content.
Possible cause: The expiration time is set to too small a value.
If you set the expiration time in your notification through the ExpirationTime method (for a local notification) or the X-WNS-TTL header field (in a push notification), be aware that the values represent milliseconds. For example, if you want a tile notification to last for exactly one hour, the value should be 60 * 60 * 1000 = 3600000.
Fix: Use a larger value.
Possible cause: The tile notification queue has not been enabled.
By default, tiles display only one update at a time and a new incoming notification replaces the existing one. If you want to display the last five notifications in a rotation, you must call TileUpdater.EnableNotificationQueue(true) in your app's initiation code. This needs to be done only once in your app's lifetime. For more information, see How to use the notification queue with local notifications.
Fix: Call EnableNotificationQueue(true) in your initialization code. Also, ensure that notification tags are unique.
For general Windows Store requirements, see Certification requirements for Windows apps. Note that to be accepted in the Windows Store, you cannot use your tiles or notifications to display advertisements.
- App tiles and badges sample
- Lock screen app sample
- Quickstart: Creating a default tile using the Visual Studio manifest editor
- Quickstart: Sending a tile update
- Quickstart: Sending a badge update
- Quickstart: Showing notifications on the lock screen
- The tile template catalog
- How to schedule a tile notification
- How to set up periodic notifications for tiles
- How to use the notification queue with local notifications
- Tiles XML schema
- Tile and tile notification overview
- Badge overview
- Lock screen overview
- The notification queue
- Choosing a notification delivery method
Build date: 11/29/2012