Editorial Note

This article is a paid placement in the Solution Center for our sponsors at The Code Project. These articles are intended to provide you with information on products and services that we consider useful and of value to developers.

In the last post, I discussed the structure of a
notification template and the mechanics for providing the various bit of
information in that template. As you know many of the notification templates
can include one or more images, and that brings up a host of configuration
options that I didn’t have a chance to get into last time. This post will fill
in the gaps and provide insight into three main topics:

Bookmark-Worthy References

I’ll close with a quick list of not-so-obvious features and behaviors that will hopefully save you some time as you plan out your strategy
for supporting images as part of notifications used within your application.

Images Sizes and Format

There are two overarching constraints for
images used within notifications:

Images used in notifications must be in one
of three formats: .png, .jpg/.jpeg, or .gif, and the format must match
the extension.

Images for notifications must be no larger
than 200 KB and 1024 x 1024 dimension.

Beyond that and depending on the device size
and characteristics, images within Windows 8 may be scaled to one of four
proportions (80%, 100%, 140% and 180%). Since the notification image formats
supported are all raster formats (versus vector-based) you cannot rely on the
scaling to result in clear, crisp imagery, so it’s recommended that you provide
artwork to accommodate all four scaling factors.

The table below (which is adapted from the App images topic on MSDN) shows most of the
sizes needed for tile and toast
notifications as well as the (optional) badge logo for the start screen. Only
those images highlighted in red (100% size for logo and small logo) are
required and must be supplied in the app manifest (as .jpg/jpeg or .png
formats). Other sizes are optional
and if not provided will be generated by scaling the default 100% image.

Image Locations

within the app package, using the ms-appx:/// prefix to a directory in
your deployed application (this is the default).

within local storage, using the ms-appdata:///local
prefix to a directory within local storage. Note that images in temporary and roaming application data storage cannot be
used.

on the web, using an http or https URI that serves up image content (be
sure to declare Internet client capability for your
application in its manifest)

Within the template XML you can specify the
entire image URI or use paths relative to the baseUri value specified
within the template. The baseUri can be set for either the visual
(tile | toast) tag or the binding tag (tile | toast), with the latter overriding the former
when provided.

App Package Images

Here, for example, is a code snippet from the App tiles and badges sample showing the use of
an image within the local application package:

var tileXml = Windows.UI.Notifications.TileUpdateManager.getTemplateContent(
Windows.UI.Notifications.TileTemplateType.tileWideImageAndText01);
// get the text attributes for this template and fill them in
var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode(
"This tile notification uses ms-appx images"));
// get the image attributes for this template and fill them in
var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///images/redWide.png");

Local Storage Images

The code for accessing an image in local
storage is very similar, differing only by the addressing scheme:

Here the image is located in a subdirectory
called images at the location returned by ApplicationData.localFolder; when I ran an
excursion of the sample app using this access mechanism, the image was served
from:

Images in the Cloud

One option to consider when architecting your
application is leveraging the cloud for external resources that your
application uses. If you place images and other content on the web or in the
cloud, you’ve decoupled those resources from your application, and by doing so
you can freshen the look and feel of your application without publishing a new
version of your application or requiring the end users to get an update.

How to: Use Windows
Azure for your notifications

Windows Azure, Microsoft’s public cloud
offering, can be an incredibly convenient and cost effective way to manage the
images you’re using for your notifications. The easiest way to serve image
content from Windows Azure is via blob storage which provides highly scalable and highly available storage of unstructured data
at one of eight Windows Azure data centers worldwide. A Content Delivery Network (currently comprising 24 nodes) is also available to
improve performance and user experience for end-users who aren’t located near a
data center.

Keep in mind there are some caveats when using
cloud or web hosted images:

The most obvious is that if the machine lacks
network connectivity, the image won't be available and the notification will
not be sent.

Web images are cached, so an update to the image in
the cloud may not be immediately reflected on the client. If the cache is full,
images will be removed in a policy opaque to the developer. Additionally the
system will clear the cache when

The application is uninstalled, or

The user clears personal information from all of her application tiles
(via the Settings flyout on the Start screen).

The system will comply with caching and
expiration headers in the HTTP response. Those headers are not configurable in
Windows Azure storage alone, but a web service can be configured and hosted on
Windows Azure to support this.

The cloud isn't free! While there are no-cost
options (like the 90-day trial and MSDN subscriptions), you ultimately may end up
paying for the storage and the transactions (HTTP GET requests) that are made
by your application. The complete
pricing details are available at the Azure pricing
page, but it’s very likely you'll be able to support a popular Windows 8
application for dollars if not pennies a month.

Handling Scaling and Contrast
Themes

The elephant in the room thus far in this post
is that all the samples I’ve shown above refer to a single image of some
unknown size, and I appear to have ignored the advice to provide four different
image sizes (80%, 100%, 140% and 180%) scale to provide the best user
experience!

It turns out that there’s a bit of magic
happening behind the scenes to make managing the combination of image sizes and
contrast mode (don’t forget there’s are high-contrast white and high-contrast
black options too!). The amount of ‘magic’ depends on the image source, so I’ll
cover them independently below.

App Package Images

When you provide images as part of your
application package, a naming convention can be leveraged which
enables you to specify one base image name (say in the notification template image
src attribute) but the system selects a file of the same name (but
different extension) based on the current scale factor and contrast mode.

For instance, while the code sample above
refers to redWide.png, the application can deliver a slew of versions that vary
by scale factor, contrast mode, culture (e.g., en-US versus zh-CN), and several
other resource qualifiers.

A file named redWide.scale-140.png, if
available, would be used in the samples above – in lieu of scaling the default
image – whenever there was a request for redWide.png and the current scale
required was 140%. Your code doesn’t need to do a thing!

If you had a special version of the tile just
for those in French locales, you could name that image,
redWide.lang-FR-fr_scale-140.png. (Note the lang prefix to the BCP-47 language
identifier)

Likewise, redWide.scale-180_contrast-black.png
would be used when the contrast mode is black and an image scaled to 180% is
needed. By the way, redWide.contrast-black_scale-180.png works too!

You can also arrange the images in
subdirectories, to provide a myriad of customization options. Take, for
example, the following directory structure.

If the application were run on a US based
system, but the user selected a black high contrast theme, a reference for
welcome.png for a tile notification would pick the variant on Line 8 (or
possibly Line 7, depending on the characteristics of that system).
Someone running the applications with his locale set to Japan on a
high-resolution device would see the image file associated with Line 17.

Local Images

Unfortunately, none of the conventions
supported for app package images are supported when using local images (the
ms-appdata:///local namespace), but you could create your own mapping algorithm
using the following Windows APIs:

Images in the Cloud

Both the tile schema and the toast schema include an optional attribute
called addImageQuery, on the visual, binding, and image elements (the
value set on the deepest element overriding those above it). When addImageQuery
is set to true, HTTP/HTTPS requests made for images will have a query string
appended consisting of the following three name value pairs:

The good news is that you don’t have to figure
out which variant of an image is being requested – that information is
available in the query parameters; the bad news is that you have to build your
own web service to inspect those parameters and serve up the correct image in
response. You can’t just use the blob storage mechanism shown above, because
those query parameters aren't automatically interpreted by Windows Azure blob
storage, but you can still use Windows Azure with a little bit of code (PHP, ASP.NET, Node.js, or essentially any implementation of a web
service that will run on Windows).

A Recap of the Not-So-Obvious

80% images are used on
tiles for some combinations of screen size and resolution.

Size specifications
haven’t been published for images that appear on toast or that do not fill the
entire tile, such as the template samples below. In most cases, these will be
photographic images which scale fairly well (using the Fant algorithm internally). You could measure
the sizes empirically, but if you create images that work for 180% scale they
should also scale down well for the other three factors.

Default images (those declared in your app
manifest) must be .png or .jpg/.jpeg format, but you can use .gif
in your toast and tile notification templates.

If an image is of the wrong format or not available (such as a image
hosted on the Web when the client is not connected), the notification will not
be sent.

The branding element is taken from the small logo in your manifest. For tiles it appears in
the bottom left and for toast in the bottom right. In the tile schema you can use text, logo, or no
branding; in the toast schema, the branding attribute is not
used and you will always see the logo.

if you don’t supply multiple images to accommodate scaling, try to
create images with dimensions that are a multiple of 5 as they won’t experience
pixel shifting during scaling.

The Visual Studio simulator is an awesome way to
test out tile behavior under different resolutions and contrast modes, but be
aware, you’ll have to restart your debug session in the simulator if your
change in resolution results in loading a different version of the image.

PC Settings > Ease of Access (accessible via the Settings charm) includes a switch to toggle High
Contrast mode; however, since there are four high contrast modes, you’ll need
to use the desktop Control Panel option to pick one. Once you’ve selected
the contrast mode there, PC Settings > Ease of Access will use that High
Contrast mode when you toggle the option.

Windows supports four high
contrast modes (White, Black, #1, and #2), and these map to four overlapping
resource types in Metro (standard, high, black, and white) as follows:

Share

About the Author

Jim is a Technology Evangelist for Microsoft who covers the Northeast District, namely, New England and upstate New York. He is focused on engaging with the development community in the area through user groups, code camps, BarCamps, Microsoft-sponsored events, and on-line. Currently Jim's focus is on mobile applications and their integration with cloud services.

Jim joined Microsoft in April 2008 after nearly 12 years working for Sybase in a support and sales consultant role for its developer tools, specifically PowerBuilder and EAServer. Prior to that he worked on various DoD projects at MITRE (Bedford, MA) and BDM International (in McLean, VA, now subsumed by Northrop Grumman). Jim received a B.S. in Mathematics and Computer Science from Austin Peay State University and his M.S. in Computer Science from Duke University.