Windows 8 Notifications: Image Handling

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

App images

Application data

Globalizing tile and toast notifications

Leveraging Windows Azure Storage

What image sizes and formats do you need to provide?

Where can the images be hosted?

How do you accommodate different device resolutions and themes?

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:

1. Images used in notifications must be in one of three formats: .png, .jpg/.jpeg, or .gif, and the format must match the extension.
2. Images for notifications must be no larger than 200 KB and 1024 x 1024 in 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 ^{[see note]} 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 ^{[see note]}). Other sizes are optional and if not provided will be generated by scaling the default 100% image.

appxmanifest Image Name (where used)	80% [see note]	100%	140%	180%
Logo (default square tile)	120x120	150x150	210x210	270x270
Small logo (tile under semantic zoom, tile and toast branding) [see note]	24x24	30x30	42x42	54x54
Wide logo (default wide tile)	248x120	310x150	434x210	558x270
Badge Logo [see note] (Lock screen)		24x24	33x33	43x43

Tip: Use the Visual Studio 2012 simulator to check out the appearance of your images under various scaling factors (and contrast modes ^{[see note]}).

Image Locations

Images used for notifications can be stored in one of three places:

• 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 (this requires that the application declare Internet client capability 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:

 tileImageAttributes[0].setAttribute("src", "ms-appdata:///local/images/redWide.png");

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:

 C:\Users\joneil\AppData\Local\Packages\Microsoft.SDKSamples.Tiles.JS_8wekyb3d8bbwe\
    
LocalState\images\redWide.png

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 Storage in 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:

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

2. 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

   1. The application is uninstalled, or
   2. 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.

3. 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) yet the system automatically selects a file with a modified name 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.

    1:  /ProjectFolder

    2:      /images

    3:          welcome.scale-80.png

    4:          welcome.scale-100.png

    5:          welcome.scale-140.png

    6:          /contrast-black

    7:              welcome.scale-80.png

    8:              welcome.scale-100.png

    9:              welcome.scale-140.png

   10:          /contrast-white

   11:              welcome.scale-80.png

   12:              welcome.scale-100.png

   13:              welcome.scale-140.png

   14:          /ja-JP

   15:              welcome.scale-80.png

   16:              welcome.scale-100.png

   17:              welcome.scale-140.png

   18:              /contrast-black

   19:                  welcome.scale-80.png

   20:                  welcome.scale-100.png

   21:                  welcome.scale-140.png

   22:              /contrast-white

   23:                  welcome.scale-80.png

   24:                  welcome.scale-100.png

   25:                  welcome.scale-140.png

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 on a typical laptop would pick the variant on Line 8.  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 implement similar semantics programmatically using the following Windows APIs:

Attribute	Windows Class or Property	Values
Resolution	DisplayProperties.resolutionScale	Scale100Percent Scale140Percent Scale180Percent
Language	ApplicationLanguage.languages	a list of BCP-47 codes corresponding to the applications supported languages (see “How to manage language and region” for details)
Contrast Scheme [see note]	AccessibilitySettings.highContrast AccessibilitySettings.highContrastScheme	true | false ”High Contrast White” ”High Contrast Black” ”High Contrast #1” ”High Contrast #2”
Home Region	GlobalizationPreferences.homeGeographicRegion	BCP-47 subtag code corresponding to user’s Region preference in Control Panel

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:

Attribute	Query String Name	Query String Value
Resolution	ms-scale	80, 100, 140 or 180
Language	ms-lang	BCP-47 code
Contrast Scheme [see note]	ms-contrast	standard black white

Here for instance is an HTTP request made for the redWide.png tile:

 GET https://win8apps.blob.core.windows.net/images/redWide.png?ms-scale=100
               &ms-contrast=standard&ms-lang=en-US HTTP/1.1
Accept: */*
Accept-Encoding: identity, peerdist
Range: bytes=0-2419
User-Agent: Microsoft BITS/7.6
X-P2P-PeerDist: Version=1.1
X-P2P-PeerDistEx: MinContentInformation=1.0, MaxContentInformation=2.0
Connection: Keep-Alive
Host: win8apps.blob.core.windows.net
  

How to: Use Windows Azure Storage for your notifications

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.

• The badge logo must be monochromatic.

• 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: standard, high, black, and white as follows:

  Contrast Setting in Control Panel	Applicable Resource Qualifiers	ms-contrast Query Parameter Value
  High Contrast White	contrast-high and contrast-white	white
  High Contrast Black	contrast-high and contrast-black	black
  High Contrast #1	contrast-high and contrast-black	black
  High Contrast #2	contrast-high and contrast-black	black
  none	contrast-standard	standard