win-notify

Simple notifications API for JavaScript Windows Store apps.

Compatible with Windows 8 and 8.1 APIs.

Why?

Short version: because native WinRT notifications API (Windows.UI.Notifications) isn't JavaScript friendly(to put it mildly - see example below).

Longer version: Everyone who builds Windows Store apps knows that live tiles and toasts notifications are great way to engage users. WinRT API provides way to utilize those features, unfortunately it requires messing with XML (yeah XML - see example below) and work with API which is more designed for C#/C++ devs. I was a bit frustrated by the current state of affairs, so written this lib. It's not too abstracted from native WinRT API, but provides much simpler way of working with notifications from Javascript (at least I hope so).

Installation

$ npm install win-notify

$ bower install win-notify

or simply copy file win-notify.js file to your project.

Examples

Tile notifications

Let's say we want to update tile with text and image when it's displayed on start screen as wide tile and text only when it's displayed as medium tile:

 

##### using `win-notify`: ```js winNotify.viaTileUpdate({ tileWide310x150SmallImageAndText04: { image1: 'http://uifaces.com/faces/_twitter/cacestgang_73.jpg', text1: 'Hello', text2: 'World' }, tileSquareText02: { text1: 'Hello', text2: 'World' } } ); ```

using native WinRT notifications API:

var Notifications = Windows.UI.Notifications;
var Imaging = Windows.Graphics.Imaging;
 
var tileXml = Notifications.TileUpdateManager.getTemplateContent(
  Notifications.TileTemplateType.tileWide310x150SmallImageAndText04);
 
var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello"));
tileTextAttributes[1].appendChild(tileXml.createTextNode("World"));
 
var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "http://uifaces.com/faces/_twitter/cacestgang_73.jpg");
 
var squareTileXml = Notifications.TileUpdateManager.getTemplateContent(
  Notifications.TileTemplateType.tileSquareText02);
 
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello"));
squareTileTextAttributes[1].appendChild(squareTileXml.createTextNode("World"));
 
var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);
 
var tileNotification = new Notifications.TileNotification(tileXml);
 
var tileUpdater = Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication();
tileUpdater.update(tileNotification);

Hope you see now which API is simpler and why it's worth using win-notify in your project. Check out API section to learn more about details.

Toast notifications

Let's say we want to show toast notification with text and image:

using win-notify:

winNotify.viaToast({
  toastImageAndText02: {
    text1: 'Hello',
    text2: 'World',
    image1: 'http://uifaces.com/faces/_twitter/cacestgang_73.jpg',
  }
});

using native WinRT notifications API:

var notifications = Windows.UI.Notifications;
 
var template = notifications.ToastTemplateType.toastImageAndText02;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);
 
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].innerText = "Hello";
toastTextElements[1].innerText = "World"; 
 
var toastImageElements = toastXml.getElementsByTagName("image");
toastImageElements[0].setAttribute("src", "http://uifaces.com/faces/_twitter/cacestgang_73.jpg");
 
var toast = new notifications.ToastNotification(toastXml);
var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
toastNotifier.show(toast);

Again, win-notify is much simpler to use than native WinRT notifications API. Check out API section to learn more about details.

API

Tile updates

winNotify.viaTileUpdate(templatesDefinitions, [optional] options)

Updates live tile with new content defined in templates definitions.

templatesDefinitions

It's an object which contains template definition objects and has following structure:

{
  'templateDefinition': {
     ... template paremeters
  },
  'TemplateDefinition' : {
    ... template parameters
  }
}

Every single templateDefinition object needs to named after template name from tile templates catalog (for example tileSquare150x150Text04). Both camelCase and PascalCase naming conventions are supported (both tileSquare150x150Text04 and TileSquare150x150Text04 will work). If you want to send update only for one tile type, specify only one template definition, if you want to handle more tile types(medium, wide, large etc) specify template definition for each of them (it's best practise to send updates to all handled by app tile types, so if your app supports wide and medium tiles send update for both).

When you know which template definition from catalog you want to use, templateDefinition object needs to contain properties which are template's parameters and those can be of text or image type.

• image - can be simple string or object with src, alt and addImageQuery properties - see MSDN for more details
• text - can be simple string or object with lang and text properties - see MSDN for more details

Let's say we want to use template TileSquare150x150PeekImageAndText02:

It has following xml definition:

<tile>
  <visual version="2">
    <binding template="TileSquare150x150PeekImageAndText02" fallback="TileSquarePeekImageAndText02">
      <image id="1" src="image1" alt="alt text"/>
      <text id="1">Text Field 1 (larger text)</text>
      <text id="2">Text Field 2</text>
    </binding>  
  </visual>
</tile>

Templatedefinition object for such template looks like:

tileSquare150x150PeekImageAndText02: {
      image1: {
        src:'image1',
        alt:'alt text'
      },
      text1: 'Text Field 1 (larger text)',
      text2: 'Text Field 2'
    }

Notice that image and text properites have proper suffixes which match id of element in template xml (text1 for text with id=1 etc).

options

It's an object with following properties (all optional): addImageQuery, baseUri, branding, contentId, lang, version Read more about each of them on MSDN.

Additionalally options object can contain following properties:

• tag - gets or sets a string that Windows can use to prevent duplicate notification content from appearing in the queue.
• expirationTime - gets or sets the time (DateTime) that Windows will remove the notification from the tile.
• tileId - if not specified tile update will update application tile, if specified it will update secondary tile if secondary tile with tileId exists
• deliveryTime - gets the time (DateTime) at which the tile is scheduled to be updated (applies only to scheduled tile updates).
• id - gets or sets the unique ID that is used to identify the scheduled tile in the schedule (applies only to scheduled tile updates).
• debug - if set to true will console.log xml output for debugging purposes

winNotify.viaScheduledTileUpdate(templatesDefinitions, [optional] options)

Schedules update to live tile with new content defined in templates definition. Both TemplatesDefinitions and options objects are the same as for winNotify.viaTileUpdate method.

winNotify.clearTile([optional] options)

Removes all updates and causes the tile to display its default content as declared in the app's manifest. Optional options object can contain tileId property which allows to clear content of secondary tile.

Toasts notifications

winNotify.viaToast(templatesDefinitions, [optional] options)

Raises a toast notification.

Templatesdefinitions object has the same structure as one from winNotify.viaTileUpdate method. Only template names are changes, and need to match ones from toasts template catalog.

Let's say we want to use template ToastImageAndText04:

It has following xml definition:

<toast>
    <visual>
        <binding template="ToastImageAndText04">
            <image id="1" src="image1" alt="image1"/>
            <text id="1">headlineText</text>
            <text id="2">bodyText1</text>
            <text id="3">bodyText2</text>
        </binding>  
    </visual>
</toast>

Templatedefinition object for such template looks like:

toastImageAndText04: {
      image1: {
        src:'image1',
        alt:'alt text'
      },
      text1: 'headlineText',
      text2: 'bodyText1',
      text3: 'bodyText2'
    }

options

Options from winNotify.viaTileUpdate apply here as well, additionally you can specify following properties:

• onactivated,ondismissed, onfailed (MSDN reference)
• launch, duration (MSDN reference)
• loop, silent src (MSDN reference)

winNotify.viaScheduledToast(templatesDefinitions, [optional] options)

Schedule toast notification that will display at the scheduled time. Both TemplatesDefinitions and options objects are the same as for winNotify.viaToast method.

Badge updates

winNotify.viaBadgeUpdate(value, [optional] options)

Updates a badge overlay tile.

Value is a string and defines badge value (MSDN referene).

Options object can contain tileId property, so badge update will update badge of secondary tile, not main app tile.

winNotify.clearBadge([optional] options)

Removes the badge from the tile. Optional options object can contain tileId property which allows to remove badge of secondary tile.

Credits

Thanks Kraig Brockschmidt for images (hope he don't mind) and presentation Alive with Activity explaining notifications concepts in clear way and Microsoft for MSDN docs.

License

WTFPL