Computer Coding
Home |  ColdFusion |  IBM |  Java |  JavaScript |  Spring |  Misc |  Sign in



HTML5Rocks


Push Notifications on the Open Web

If you ask a room of developers what mobile device features are missing from the web, push notifications are always high on the list.

Push notifications allow your users to opt-in to timely updates from sites they love and allow you to effectively re-engage them with customized, engaging content.

As of Chrome version 42, the Push API and Notification API are available to developers.

The Push API in Chrome relies on a few different pieces of technology, including Web App Manifests and Service Workers. In this post we?ll look at each of these technologies, but only the bare minimum to get push messaging up and running. To get a better understanding of some of the other features of manifests and the offline capabilities of service workers, please check out the links above.

We will also look at what will be added to the API in future versions of Chrome, and finally we?ll have an FAQ.

Implementing Push Messaging for Chrome

This section describes each step you need to complete in order to support push messaging in your web app.

Register a Service Worker

There is a dependency of having a service worker to implement push messages for the web. The reason for this is that when a push message is received, the browser can start up a service worker, which runs in the background without a page being open, and dispatch an event so that you can decide how to handle that push message.

Below is an example of how you register a service worker in your web app. When the registration has completed successfully we call initialiseState(), which we?ll cover shortly.

var isPushEnabled = false;

?

window.addEventListener('load', function() {  
  var pushButton = document.querySelector('.js-push-button');  
  pushButton.addEventListener('click', function() {  
    if (isPushEnabled) {  
      unsubscribe();  
    } else {  
      subscribe();  
    }  
  });

  // Check that service workers are supported, if so, progressively  
  // enhance and add push messaging support, otherwise continue without it.  
  if ('serviceWorker' in navigator) {  
    navigator.serviceWorker.register('/service-worker.js')  
    .then(initialiseState);  
  } else {  
    console.warn('Service workers aren\'t supported in this browser.');  
  }  
});

The button click handler subscribes or unsubscribes the user to push messages. isPushEnabled is a global variable which simply tracks whether push messaging is currently subscribed or not. These will be referenced throughout the code snippets.

We then check that service workers are supported before registering the service-worker.js file which has the logic for handling a push message. Here we are simply telling the browser that this JavaScript file is the service worker for our site.

Set Up the Initial State

Example of enabled and disabled push messaging UX in Chrome

Once the service worker is registered, we need to set up our UI?s state.

Users will expect a simple UI to enable or disable push messages for your site, and they?ll expect it to keep up to date with any changes that occur. In other words, if they enable push messages for your site, then leave and come back a week later, your UI should show that push messages are already enabled.

You can find some UX guidelines in this doc, in this article we?ll be focusing on the technical aspects.

At this point you may be thinking there are only two states to deal with, enabled or disabled. There are however some other states surrounding notifications which you need to take into account.

A diagram highlighting the different considerations and state of push in Chrome

There are a number of things we need to check before we enable our button, and if everything is supported, we can enable our UI and set the initial state to indicate whether push messaging is subscribed or not.

Since the majority of these checks result in our UI being disabled, you should set the initial state to disabled. This also avoids any confusion should there be an issue with your page?s JavaScript, for example the JS file can?t be downloaded or the user has disabled JavaScript.

<button class="js-push-button" disabled> 
  Enable Push Messages  
</button>

With this initial state, we can perform the checks outlined above in the initialiseState() method, i.e. after our service worker is registered.

// Once the service worker is registered set the initial state  
function initialiseState() {  
  // Are Notifications supported in the service worker?  
  if (!('showNotification' in ServiceWorkerRegistration.prototype)) {  
    console.warn('Notifications aren\'t supported.');  
    return;  
  }

  // Check the current Notification permission.  
  // If its denied, it's a permanent block until the  
  // user changes the permission  
  if (Notification.permission === 'denied') {  
    console.warn('The user has blocked notifications.');  
    return;  
  }

  // Check if push messaging is supported  
  if (!('PushManager' in window)) {  
    console.warn('Push messaging isn\'t supported.');  
    return;  
  }

  // We need the service worker registration to check for a subscription  
  navigator.serviceWorker.ready.then(function(serviceWorkerRegistration) {  
    // Do we already have a push message subscription?  
    serviceWorkerRegistration.pushManager.getSubscription()  
      .then(function(subscription) {  
        // Enable any UI which subscribes / unsubscribes from  
        // push messages.  
        var pushButton = document.querySelector('.js-push-button');  
        pushButton.disabled = false;

        if (!subscription) {  
          // We aren't subscribed to push, so set UI  
          // to allow the user to enable push  
          return;  
        }
        
        // Keep your server in sync with the latest subscriptionId
        sendSubscriptionToServer(subscription);

        // Set your UI to show they have subscribed for  
        // push messages  
        pushButton.textContent = 'Disable Push Messages';  
        isPushEnabled = true;  
      })  
      .catch(function(err) {  
        console.warn('Error during getSubscription()', err);  
      });  
  });  
}

A brief overview of these steps:

  • We check that showNotification is available in the ServiceWorkerRegistration prototype. Without it we won?t be able to show a notification from our service worker when a push message is received.
  • We check what the current Notification.permission is to ensure it?s not ?denied?. A denied permission means that you can?t show notifications until the user manually changes the permission in the browser.
  • To check if push messaging is supported we check that PushManager is available in the window object.
  • Finally, we used pushManager.getSubscription() to check whether we already have a subscription or not. If we do, we send the subscription details to our server to ensure we have the right information and set our UI to indicate that push messaging is already enabled or not. We?ll look at what details exist in the subscription object later in this article.

We wait until navigator.serviceWorker.ready is resolved to check for a subscription and to enable the push button because it?s only after the service worker is active that you can actually subscribe to push messages.

The next step is to handle when the user wants to enable push messages, but before we can do this, we need to set up a Google Developer Console project and add some parameters to our manifest to use Google Cloud Messaging (GCM).

Make a Project on the Google Developer Console

Chrome uses GCM to handle the sending and delivery of push messages, however, to use the GCM API, you need to set up a project on the Google Developer Console. Follow the instructions in the getting started guide, making sure you enable both ?Google Cloud Messaging for Android? and ?Google Cloud Messaging for Chrome?, and make a note of the project number and API key as you?ll need to use them later on.

This step is specific to Chrome since it relies on GCM for handling push messages. We?ll discuss how this would work in other browsers later on in the article.

Below are screenshots highlighting where the project number and API keys are.

Highlighting where the project number is in the Google Developer Console

Highlighting where the API key is in the Google Developer Console

The project number will be used in the Web App Manifest (see the next section) as the gcm_sender_id parameter, and the API Key will be needed on your server when you use GCM?s restful API.

Add a Web App Manifest

For push, we need to add a manifest file with two fields, gcm_sender_id and gcm_user_visible_only, to get the push subscription to succeed. These parameters are only required by Chrome to use GCM.

The gcm_sender_id (i.e. the project number) is used by Chrome when establishing a subscription with GCM. This means that GCM can link a subscriptionId to a corresponding project number which has has a corresponding API key. This ensures that your server is permitted to send messages to the client web app by validating these three pieces of information against the projects whitelisted IP Addresses.

The gcm_user_visible_only parameter is used to indicate that you promise to show a notification whenever you receive a push. Not including this parameter or having a value of false will prevent you from subscribing to push messages.

Below is a super-simple manifest file:

{  
  "name": "Push Demo",  
  "short_name": "Push Demo",  
  "icons": [{  
        "src": "images/icon-192x192.png",  
        "sizes": "192x192",
        "type": "image/png" 
      }],  
  "start_url": "/index.html?homescreen=1",  
  "display": "standalone",  
  "gcm_sender_id": "123456789012",  
  "gcm_user_visible_only": true  
}

You?ll need to swap out the gcm_sender_id with your project number from the Google Developer Console mentioned in the previous step.

Once you have saved your manifest file in your project (manifest.json is a good name), reference it from your HTML with the following tag in the head of your page.

<link rel="manifest" href="manifest.json">

If you don?t add a web manifest with these parameters you?ll get an exception when you attempt to subscribe the user to push messages, with the error ?Registration failed - no sender id provided? or ?Registration failed - permission denied?.

Subscribe to Push Messaging

To subscribe, we just have to call the subscribe() method on the PushManager object, which you access through the ServiceWorkerRegistration object.

This will ask the user to give your origin permission to send push notifications. Without this permission, you will not be able to successfully subscribe.

If the promise returned by the subscribe() method resolves, you?ll be given a PushSubscription object which will contain a subscriptionId and an endpoint.

The subscriptionId is used to identify the user to GCM and the endpoint will be the URL of the GCM API endpoint to use.

Both the subscriptionId and endpoint should be saved on your server for each user, since you?ll need them to send push messages at a later date.

The following code subscribes the user for push messaging:

function subscribe() {  
  // Disable the button so it can't be changed while  
  // we process the permission request  
  var pushButton = document.querySelector('.js-push-button');  
  pushButton.disabled = true;

  navigator.serviceWorker.ready.then(function(serviceWorkerRegistration) {  
    serviceWorkerRegistration.pushManager.subscribe()  
      .then(function(subscription) {  
        // The subscription was successful  
        isPushEnabled = true;  
        pushButton.textContent = 'Disable Push Messages';  
        pushButton.disabled = false;      
          
        // TODO: Send the subscription.subscriptionId and   
        // subscription.endpoint to your server  
        // and save it to send a push message at a later date   
        return sendSubscriptionToServer(subscription);  
      })  
      .catch(function(e) {  
        if (Notification.permission === 'denied') {  
          // The user denied the notification permission which  
          // means we failed to subscribe and the user will need  
          // to manually change the notification permission to  
          // subscribe to push messages  
          console.warn('Permission for Notifications was denied');  
          pushButton.disabled = true;  
        } else {  
          // A problem occurred with the subscription; common reasons  
          // include network errors, and lacking gcm_sender_id and/or  
          // gcm_user_visible_only in the manifest.  
          console.error('Unable to subscribe to push.', e);  
          pushButton.disabled = false;  
          pushButton.textContent = 'Enable Push Messages';  
        }  
      });  
  });  
}

At this point your web app is ready to receive a push message, although nothing will happen until we add a push event listener to our service worker file.

Service Worker Push Event Listener

When a push message is received (we?ll talk more about how to send a push message from your server in the next section), a push event will be dispatched in your service worker, at which point you?ll need to display a notification.

self.addEventListener('push', function(event) {  
  console.log('Received a push message', event);

  var title = 'Yay a message.';  
  var body = 'We have received a push message.';  
  var icon = '/images/icon-192x192.png';  
  var tag = 'simple-push-demo-notification-tag';

  event.waitUntil(  
    self.registration.showNotification(title, {  
      body: body,  
      icon: icon,  
      tag: tag  
    })  
  );  
});

This code registers a push event listener and displays a notification with a predefined title, body text, icon and a notification tag.
One subtlety to highlight with this example is the event.waitUntil() method. This method takes a promise and extends the lifetime of an event handler until the promise is settled; In this case, until the promise returned from showNotification() is resolved.

The notification tag identifies unique notifications. If we sent two push messages to the same subscriptionId, with a short delay between them, and displayed a notification with the same tag for both, the browser will display the first notification and replace it with the second notification when the push message is received.

If you want to show multiple notifications at once then use a different tag, or no tag at all.
We?ll look at a more complete example of showing a notification later on in this post. For now, let?s keep things simple and see if sending a push message shows this notification.

Sending a Push Message

We?ve subscribed to push messages and our service worker is ready to show a notification, so it?s time to send a push message through GCM.

GCM has some great docs on what you need to do to send a message. The key aspects of their API are:

  • An Authorization header with a value of key=<YOUR_API_KEY>, where <YOUR_API_KEY> is the API key from the Google Developer Console.
    • The API key is used by GCM to find the appropriate project number, match it with the subscriptionId?s project number, which you are trying to send a message too and finally ensuring that the server?s IP address is whitelisted for that project.
  • An appropriate Content-Type header of application/json or application/x-www-form-urlencoded;charset=UTF-8 depending on whether you send the data as JSON or form data.
  • An array of registration_ids - these are just the subscriptionId?s you?d have for the users you would like to send a push message to.

Please do check out the docs about how to send push messages from your server, but for a quick sanity check of your service worker you can use cURL to send a push message to your browser (as long as you whitelisted your IP address on the Google Developer Console).

Swap out the <YOUR_API_KEY> and <YOUR_SUBSCRIPTION_ID> in this cURL command, run it from a terminal and you should see a glorious notification:

curl --header "Authorization: key=<YOUR_API_KEY>" --header 
"Content-Type: application/json" https://android.googleapis.com/gcm/send -d 
"{\"registration_ids\":[\"<YOUR_SUBSCRIPTION_ID>\"]}"

Example of a push message from Chrome for Android

When developing your backend logic, remember that the Authorization header and format of the POST body are specific to the GCM endpoint, so detect when the endpoint is for GCM and conditionally add the header and format the POST body.

A downside to the current implementation of the Push API in Chrome is that you can?t send any data with a push message. Nope, nothing. The reason for this is that in a future implementation, payload data will have to be encrypted on your server before it?s sent to a push messaging endpoint. This way the endpoint, whatever push provider it is, will not be able to easily view the content of the push message. This also protects against other vulnerabilities like poor validation of HTTPS certificates and man-in-the-middle attacks between your server and the push provider. However, this encryption isn?t supported yet, so in the meantime you?ll need to perform a fetch to get information needed to populate a notification.

A More Complete Push Event Example

The notification we?ve seen so far is pretty basic and as far as samples go, it?s pretty poor at covering a real world use case.

Realistically, most people will want to get some information from their server before displaying the notification. This may be data to populate the notification title and message with something specific, or going a step further and caching some pages or data so that when the user clicks on the notification, everything is immediately available when the browser is opened?even if the network isn?t available at that time.

In the following code we fetch some data from an API, convert the response to an object and use it to populate our notification.

self.addEventListener('push', function(event) {  
  // Since there is no payload data with the first version  
  // of push messages, we'll grab some data from  
  // an API and use it to populate a notification  
  event.waitUntil(  
    fetch(SOME_API_ENDPOINT).then(function(response) {  
      if (response.status !== 200) {  
        // Either show a message to the user explaining the error  
        // or enter a generic message and handle the   
        // onnotificationclick event to direct the user to a web page  
        console.log('Looks like there was a problem. Status Code: ' + response.status);  
      throw new Error();  
      }

      // Examine the text in the response  
      return response.json().then(function(data) {  
        if (data.error || !data.notification) {  
          console.error('The API returned an error.', data.error);  
          throw new Error();  
        }  
          
        var title = data.notification.title;  
        var message = data.notification.message;  
        var icon = data.notification.icon;  
        var notificationTag = data.notification.tag;

        return self.registration.showNotification(title, {  
          body: message,  
          icon: icon,  
          tag: notificationTag  
        });  
      });  
    }).catch(function(err) {  
      console.error('Unable to retrieve data', err);

      var title = 'An error occurred';
      var message = 'We were unable to get the information for this push message';  
      var icon = URL_TO_DEFAULT_ICON;  
      var notificationTag = 'notification-error';  
      return self.registration.showNotification(title, {  
          body: message,  
          icon: icon,  
          tag: notificationTag  
        });  
    })  
  );  
});

It?s worth, once again, highlighting that the event.waitUntil() takes a promise which results in the promise returned by showNotification(), meaning that our event listener won?t exit until the asynchronous fetch() call is complete, and the notification is shown.

You?ll notice that we show a notification even when there is an error, that is because if we don?t, Chrome will show it?s own generic notification.

Opening a URL when the User Clicks a Notification

When the user clicks a notification, a notificationclick event is dispatched in your service worker. Within your handler, you can take appropriate action, like focusing a tab or opening a window with a particular URL:

self.addEventListener('notificationclick', function(event) {  
  console.log('On notification click: ', event.notification.tag);  
  // Android doesn't close the notification when you click on it  
  // See: http://crbug.com/463146  
  event.notification.close();

  // This looks to see if the current is already open and  
  // focuses if it is  
  event.waitUntil(
    clients.matchAll({  
      type: "window"  
    })
    .then(function(clientList) {  
      for (var i = 0; i < clientList.length; i++) {  
        var client = clientList[i];  
        if (client.url == '/' && 'focus' in client)  
          return client.focus();  
      }  
      if (clients.openWindow) {
        return clients.openWindow('/');  
      }
    })
  );
});

This example opens the browser to the root of the site?s origin, by focusing an existing same-origin tab if one exists, and otherwise opening a new one.

There are two parts of today?s implementation of Notifications which require some unpleasant work arounds:

  1. There is no easy way to stash data with the notification (i.e. what URL to open when a particular notification is clicked). There is a data attribute in the Notification spec, but it?s not implemented yet.
  2. You can only open a URL which is on the same origin as your service worker (This will hopefully be addressed soon).

But don?t worry, there are ways to overcome these issues.

To get around not being able to tie data to your notification, you can use IndexedDB to save a URL for a particular notification tag, this way you can look it up in the notificationclick event and open the window to that particular URL.

An alternative approach (albeit somewhat unconventional) would be to use a fragment identifier on the end of your icon URL. This way it won?t affect the image?s cachability while giving you access to a short URL. (H/T to Casey at Roost for this idea.)

The simplest way to overcome the temporary issue of only being able to open URLs on the same origin, is to have a page on your domain which performs a redirect.

Unsubscribe a User?s Device

You?ve subscribed a user?s device and they?re receiving push messages, but how can you
unsubscribe them?

The main things required to unsubscribe a users device is to call the unsubscribe() method on the PushSubscription object and to remove the subscriptionId from your servers (just so you aren?t sending push messages which you know won?t be received). The code below does exactly this:

function unsubscribe() {  
  var pushButton = document.querySelector('.js-push-button');  
  pushButton.disabled = true;

  navigator.serviceWorker.ready.then(function(serviceWorkerRegistration) {  
    // To unsubscribe from push messaging, you need get the  
    // subscription object, which you can call unsubscribe() on.  
    serviceWorkerRegistration.pushManager.getSubscription().then(  
      function(pushSubscription) {  
        // Check we have a subscription to unsubscribe  
        if (!pushSubscription) {  
          // No subscription object, so set the state  
          // to allow the user to subscribe to push  
          isPushEnabled = false;  
          pushButton.disabled = false;  
          pushButton.textContent = 'Enable Push Messages';  
          return;  
        }  
          
        var subscriptionId = pushSubscription.subscriptionId;  
        // TODO: Make a request to your server to remove  
        // the subscriptionId from your data store so you   
        // don't attempt to send them push messages anymore

        // We have a subscription, so call unsubscribe on it  
        pushSubscription.unsubscribe().then(function(successful) {  
          pushButton.disabled = false;  
          pushButton.textContent = 'Enable Push Messages';  
          isPushEnabled = false;  
        }).catch(function(e) {  
          // We failed to unsubscribe, this can lead to  
          // an unusual state, so may be best to remove   
          // the users data from your data store and   
          // inform the user that you have done so

          console.log('Unsubscription error: ', e);  
          pushButton.disabled = false;
          pushButton.textContent = 'Enable Push Messages'; 
        });  
      }).catch(function(e) {  
        console.error('Error thrown while unsubscribing from push messaging.', e);  
      });  
  });  
}

Keeping the Subscription Up to Date

Subscriptions may get out of sync between GCM and your server. Make sure your server parses the response body of the GCM API?s send POST, looking for error:NotRegistered and canonical_id results, as explained in the GCM documentation.

Subscriptions may also get out of sync between the service worker and your server. For example, after subscribing/unsubscribing successfully, a flaky network connection may prevent you from updating your server; or a user might revoke notifications permission, which triggers an automatic unsubscribe. Handle such cases by checking the result of serviceWorkerRegistration.pushManager.getSubscription() periodically (e.g. on page load) and synchronizing it with the server. You may also wish to re-subscribe automatically if you no longer have a subscription and Notification.permission == ?granted?.

In sendSubscriptionToServer() you will need to consider how you handle failed network requests when updating the subscriptionId. One solution is to track the state of the subscriptionId and endpoint in a cookie to determine whether your server needs the latest details or not.

All of the above steps results in a full implementation of push messaging on the web in Chrome 42. There are still spec?d features that will make things easier (like notifications having data tied to them), but this release enables you to start building push messaging into your web apps today.

How to Debug Your Web App

While implementing push messages, bugs will live in one of two places: your page or your service worker.

Bugs in the page can be debugged using DevTools. To debug service worker issues, you have two options:

  1. Go to chrome://inspect > Service workers. This view doesn?t provide much information other than the currently running service workers.
  2. Go to chrome://serviceworker-internals and from here you can view the state of service workers, and see errors, if there are any. This page is temporary until DevTools has a similar feature set.

One of the best tips I can give to anyone who is new to service workers is make use of the checkbox called ?Open DevTools window and pause JavaScript execution on Service Worker startup for debugging.? This checkbox will add a breakpoint at the start of your service worker and pause execution, this allows you to resume or step through your service worker script and see if you hit any problems.

Screenshot showing where the pause execution checkbox is on serviceworker-internals

If there seems to be an issue between GCM and your service worker?s push event, then there isn?t much you can do to debug the problem since there is no way for you to see whether Chrome received anything. The key thing to ensure is that the response from GCM is successful when your server makes an API call. It?ll look something like:

{"multicast_id":1234567890,"success":1,"failure":0,"canonical_ids":0,"results":[{"message_id":"0:1234567890"}]}

Notice the ?success?: 1 response. If you see a failure instead, then that suggests that something isn?t right with the GCM subscription and the push message isn?t getting sent to Chrome.

Debugging Service Workers on Chrome for Android

At the moment debugging service workers on Chrome for Android is not obvious. You need to navigate to chrome://inspect, find your device and look for a list item with the name ?Worker pid:?.? which has the URL of your service worker.

Screenshot showing where service workers live in chrome inspect

UX for Push Notifications

The Chrome team has been putting together a document of best practices for push notifications UX as well as a document covering some of the edge cases when working with push notifications.

Future of Push Messaging on Chrome and the Open Web

This section goes into a little bit of detail surrounding some of the Chrome specific parts of this implementation that you should be aware of and how it will differ from other browser implementations.

Web Push Protocol and Endpoints

The beauty of the Push API standard is that you should be able to take the subscriptionId and endpoint, pass them to your server and send push messages by implementing the Web Push Protocol.

The Web Push Protocol is a new standard which push providers can implement, allowing developers to not have to worry about who the push provider is. The idea is that this avoids the need to sign up for API keys and send specially formatted data, like we have to with GCM.

At the moment Chrome is the only implementation of the Push API and GCM does not support the Web Push Protocol, which is the reason why Chrome requires the gcm_sender_id and you need to use the restful API for GCM with a specific format for the body of the request and the Authorization header.

The end goal is to move away from requiring these steps and to move to using the Web Push Protocol with Chrome and GCM.

Until then, you need to detect the endpoint ?https://android.googleapis.com/gcm/send? and handle it separately from other endpoints, i.e. format the payload data in a specific way and add the Authorization key.

How to Implement the Web Push Protocol?

At the moment there is no push service which implements the Web Push Protocol meaning there is no sample to give on how to send a push message on your server for anything other than GCM.

FAQs

Where are the specs?

https://slightlyoff.github.io/ServiceWorker/spec/service_worker/
https://w3c.github.io/push-api/
https://notifications.spec.whatwg.org/

Can I prevent duplicate notifications if my web presence has multiple origins, or if I have both a web and native presence?

There isn?t a solution to this at the moment, but you can follow progress on Chromium.

The ideal scenario would be to have some kind of ID for a users device and then on the server side match up the native app and web app subscription ID?s and decide which one to send a push message to. You could do this via screen size, device model, sharing a generated key between the web app and native app, but each approach has pro?s and con?s.

Why do I need a gcm_sender_id?

This is required so that Chrome can make use of the Google Cloud Messaging (GCM) API. The goal is to use the Web Push Protocol when the standard is finalised and GCM can support it.

Why not use Web Sockets or Server-Sent Events (EventSource)?

The advantage of using push messages is that even if your page is closed, your service worker will be woken up and be able to show a notification. Web Sockets and EventSource have their connection closed when the page or browser is closed.

What if I don?t need background event delivery?

If you don?t need background delivery then Web Sockets are a great option.

When can I use push without showing notifications (i.e. silent background push)?

There is no timeline for when this will be available yet, but there is an intent to implement background sync and while it?s not decided or spec?d, there is some discussion of enabling silent push with background sync.

Why does this require HTTPS? How do I work around this during development?

Service workers require secure origins to ensure that the service worker script is from the intended origin and hasn?t come about from a man-in-the-middle attack. Currently, that means using HTTPS on live sites, though localhost will work during development.

What does browser support look like?

At the moment Chrome is the only browser to implement this standard, but Mozilla have begun work on implementing the Push API and you can track their Notification implementation here.

Can I remove a notification after a certain time period?

At the moment this isn?t possible but we are planning on adding support to get a list of currently visible notifications. If you have a use case to set an expiration for notification after it?s displayed created, we?d love to know what that is, so please add a comment and we?ll pass it back to the Chrome team.

If you only need to stop a push notification from being sent to the user after a certain time period, and don?t care how long the notification stays visible, then you can use GCM?s time to live (ttl) parameter, learn more here.

What are the limitations of push messaging in Chrome 42?

There are a few limitations outlined in this post:

  • Data can?t be sent in a push message.
  • Chrome?s usage of GCM as a push service creates a number of proprietary requirements. We?re working together to see if some of these can be lifted in the future.
  • You have to show a notification when you receive a push message.
  • There is no way to add data to a notification. The data parameter isn?t implemented in Chrome yet, but is in the spec.
  • Chrome on desktop has the caveat that if Chrome isn?t running, push messages won?t be received. This differs from Chrome OS and Android where push messages will always be received. This is something we hope to resolve in the future.

Shouldn?t we be using the Permissions API?

The Permission API is still being spec?d and isn?t implemented in Chrome yet. When it is available in Chrome, you should move away from using Notifications.permission and use the Permissions API instead.

Why doesn?t Chrome open up the previous tab when I click a notification?

This issue only affects pages which aren?t currently controlled by a service worker. You can learn more here.

What if a notification is out of date by the time the users device received the push?

You always have to show a notification when you receive a push message. In the scenario where you want to send a notification but it?s only useful for a certain period time, you can use the ?time_to_live? parameter on GCM so that GCM won?t send the push message if it passes the expiry time.

More details can be found here.

What happens if I send 10 push messages but only want the device to receive one?

GCM has a ?collapse_key? parameter you can use to tell GCM to replace any pending message which has the same ?collapse_key?, with the new message.

More details can be found here.


Introduction to fetch()

So long XMLHttpRequest

fetch() allows you to make network requests similar to XMLHttpRequest (XHR). The main difference is that the Fetch API uses Promises, which enables a simpler and cleaner API, avoiding callback hell and having to remember the complex API of XMLHttpRequest.

The Fetch API has been available in the Service Worker global scope since Chrome 40, but it?ll be enabled in the window scope in Chrome 42. There is also a rather fetching polyfill by GitHub that you can use today.

If you?ve never used Promises before, check out this great article by Jake Archibald.

Basic Fetch Request

Let?s start by comparing a simple example implemented with an XMLHttpRequest and then with fetch. We just want to request a URL, get a response and parse it as JSON.

XMLHttpRequest

An XMLHttpRequest would need two listeners to be set to handle the success and error cases and a call to open() and send(). Example from MDN docs.

function reqListener() {  
  var data = JSON.parse(this.responseText);  
  console.log(data);  
}

function reqError(err) {  
  console.log('Fetch Error :-S', err);  
}

var oReq = new XMLHttpRequest();  
oReq.onload = reqListener;  
oReq.onerror = reqError;  
oReq.open('get', './api/some.json', true);  
oReq.send();

Fetch

Our fetch request looks a little like this:

fetch('./api/some.json')  
  .then(  
    function(response) {  
      if (response.status !== 200) {  
        console.log('Looks like there was a problem. Status Code: ' +  
          response.status);  
        return;  
      }

      // Examine the text in the response  
      response.json().then(function(data) {  
        console.log(data);  
      });  
    }  
  )  
  .catch(function(err) {  
    console.log('Fetch Error :-S', err);  
  });

We start by checking that the response status is 200 before parsing the response as JSON.

The response of a fetch() request is a Stream object, which means that when we call the json() method, a Promise is returned since the reading of the stream will happen asynchronously.

Response Metadata

In the previous example we looked at the status of the Response object as well as how to parse the response as JSON. Other metadata we may want to access, like headers, are illustrated below.

fetch('users.json').then(function(response) {  
    console.log(response.headers.get('Content-Type'));  
    console.log(response.headers.get('Date'));

    console.log(response.status);  
    console.log(response.statusText);  
    console.log(response.type);  
    console.log(response.url);  
});

Response Types

When we make a fetch request, the response will be given a response.type of ?basic?, ?cors? or ?opaque?. These ?types? indicate where the resource has come from and can be used to inform how you should treat the response object.

When a request is made for a resource on the same origin, the response will have a ?basic? type and there aren?t any restrictions on what you can view from the response.

If a request is made for a resource on another origin which returns the CORs headers, then the type is ?cors?. ?cors? and ?basic? responses are almost identical except that a ?cors? response restricts the headers you can view to `Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, and `Pragma`.

An ?opaque? response is for a request made for a resource on a different origin that doesn?t return CORS headers. With an opaque response we won?t be able to read the data returned or view the status of the request, meaning we can?t check if the request was successful or not. With the current fetch() implementation it?s not possible to make requests for resources on a different origin from the window global scope. Find out why here, it should be added when the Cache API is available in the window object.

You can define a mode for a fetch request such that only certain requests will resolve. The modes you can set are as follows:

  • ?same-origin? only succeeds for requests for assets on the same origin, all other requests will reject.
  • ?cors? will allow requests for assets on the same-origin and other origins which return the appropriate CORs headers.
  • ?cors-with-forced-preflight? will always perform a preflight check before making the actual request.
  • ?no-cors? is intended to make requests to other origins that do not have CORS headers and result in an opaque response, but as stated, this isn?t possible in the window global scope at the moment.

To define the mode, add an options object as the second parameter in the fetch request and define the mode in that object:

fetch('http://some-site.com/cors-enabled/some.json', {mode: 'cors'})  
  .then(function(response) {  
    return response.text();  
  })  
  .then(function(text) {  
    console.log('Request successful', text);  
  })  
  .catch(function(error) {  
    log('Request failed', error)  
  });

Chaining Promises

One of the great features of promises is the ability to chain them together. For fetch, this allows you to share logic across fetch requests.

If you are working with a JSON API, you?ll need to check the status and parse the JSON for each response. You can simplify your code by defining the status and JSON parsing in separate functions which return promises, freeing you to only worry about handling the final data and the error case.

function status(response) {  
  if (response.status >= 200 && response.status < 300) {  
    return Promise.resolve(response)  
  } else {  
    return Promise.reject(new Error(response.statusText))  
  }  
}

function json(response) {  
  return response.json()  
}

fetch('users.json')  
  .then(status)  
  .then(json)  
  .then(function(data) {  
    console.log('Request succeeded with JSON response', data);  
  }).catch(function(error) {  
    console.log('Request failed', error);  
  });

We define the status function which checks the response.status and returns the result of Promise.resolve() or Promise.reject(), which return a resolved or rejected Promise. This is the first method called in our fetch() chain, if it resolves, we then call our json() method which again returns a Promise from the response.json() call. After this we have an object of the parsed JSON. If the parsing fails the Promise is rejected and the catch statement executes.

The great thing with this is that you can share the logic across all of your fetch requests, making code easier to maintain, read and test.

POST Request

It?s not uncommon for web apps to want to call an API with a POST method and supply some parameters in the body of the request.

To do this we can set the method and body parameters in the fetch() options.

fetch(url, {  
    method: 'post',  
    headers: {  
      "Content-type": "application/x-www-form-urlencoded; charset=UTF-8"  
    },  
    body: 'foo=bar&lorem=ipsum'  
  })
  .then(json)  
  .then(function (data) {  
    console.log('Request succeeded with JSON response', data);  
  })  
  .catch(function (error) {  
    console.log('Request failed', error);  
  });

Sending Credentials with a Fetch Request

Should you want to make a fetch request with credentials such as cookies, you should set the credentials of the request to ?include?.

fetch(url, {  
  credentials: 'include'  
})

FAQ

How do I cancel a fetch() request?

At the moment there is no way to cancel a fetch, but this is being discussed on GitHub . H/T @jaffathecake for this link.

Is there a polyfill?

GitHub has a polyfill for fetch. H/T @Nexii for pointing this out.

Why is ?no-cors? supported in service workers but not the window?

This is due to a security concern, you can learn more here.


Increasing engagement with Web App install banners

We recently enhanced the Add to Homescreen function in Chrome which allows users to add your Web App to their home screen with the addition of the standards-based ?web app manifest?. The manifest gives you extra control over the Add to Homescreen experience, allowing you to tell the browser what to launch, how to launch your app (fullscreen or in a browser window) and how it should appear to users on the home screen.

This improved things for users, but the ability to Add to Homescreen is still hidden behind a menu, meaning that your apps still aren?t as discoverable as they should be. To increase the chance of a user adding their app to the home screen a developer would have to try and guess if the site was already running as an Added to Homescreen app and if not, then tactically decide to give them an overlay that asked them to work around our poor UX. This isn?t great for users, and it is not good for developers.

In Chrome 42 (M42 - that is now in Beta) we are introducing ?App Install Banners?. App Install Banners give you the ability to have your users quickly and seamlessly install your Web App as per the images below.

IO Site with install banner

?This looks great, I want it on my site? I hear you shout. ?Please tell me how to add it!?. The good news is if you meet the following criteria Chrome will manage the prompting of users:

  • You have a web app manifest file
    • The manifest defines how your app appears on the user?s system and how it should be launched - and you are required to have a `short_name` and a `144x144` png icon
    • Your icon declartion?s should include a mime type of image/png
  • You have a service worker registered on your site. We recommend a simple custom offline page service worker
  • Your site is served over HTTPS (you need a service worker after all)
  • The user has visited your site twice over two separate days during the course of two weeks.

A sample manifest is provided in our samples and one here for quick reference:

{
  "short_name": "Kinlan's Amaze App",
  "name": "Kinlan's Amazing Application ++",
  "icons": [
    {
      "src": "launcher-icon-3x.png",
      "sizes": "144x144",
      "type": "image/png"
    }
  ],
  "start_url": "index.html",
  "display": "standalone"
}

If you are interested in the implementation, check out crbug 452825. If you are interested in tracking what other things we are working on in this space, follow the Cr-UI-Browser-AppShortcuts label.

Frequently Asked Questions

My app meets all the criteria, but I don?t want the banner to display. Can I control this?
Not right now. We are working on ways to give developers the ability to cancel the display of the prompt. Follow our ?Intent to Implement? on blink-dev mailing list.

Can I detect if a user tapped ?Add? at the prompt and added to home screen?
Not right now. We are working on ways to give developers the ability to understand whether the user has gestured Install or Cancel.

If a user dismisses the banner, will it appear again?
No. Not unless the user clears their history. We want to make sure users have a good experience. We will likely be changing all the heuristics over time.

Can I decide when to prompt the user?
No, we are not letting developers actively prompt the user to Add to Homescreen.

You said that I will only get the banner if I visit the site on two different days. How on earth do I test it?
Yeah, we had the same problem when we were building this. Enable chrome://flags/#bypass-app-banner-engagement-checks and you will see it as long as you have a manifest (configured correctly) and are on HTTPS and have a service worker.

Why do I need a service worker?
We believe that when you add to the user?s home screen you should be providing an app-like experience. A service worker, especially one that supports push messaging or offline, is a strong indicator that you are developing a first class device experience. We recommend the following simple Service Worker as a starting point.

Why do I need SSL?
Because you need a service worker.

Are there any good examples of this in action?
Yes, Glad you asked:

Examples are great, but do you have anything I can just copy and paste?
Yes. We have made a minimal app install banner example that you can copy, paste and change.


Creating semantic sites with Web Components and JSON-LD

With the rising popularity of web components and supporting libraries like Polymer, custom elements become an attractive way to build UI features. The default encapsulation of custom elements makes them especially useful for creating independent widgets.

While some of the widgets are self-contained, many of them rely on external data to present the content to the user - e.g., the current forecast for a weather widget or the address of a company for a map widget.

In Polymer, custom elements are declarative, which means once they are imported into a project, it is very easy to include and configure them in HTML, e.g. by passing the data to populate the widget through an attribute.

It would be great if we could avoid repetition and ensure data consistency, by reusing the same data snippets to populate different widgets as well as inform search engines and other consumers about the content of our page. We can achieve this by using the schema.org standard and the JSON-LD format for our data.

Populating the components with structured data

Typically, JSON is a convenient way to inject data into a particular widget. With the rising support for JSON-LD, we can reuse the same data structures to inform the UI as well as the search engines and other consumers of structured data about the exact meaning of the page?s content.

By combining web components with JSON-LD, we create a well-defined architecture for an application:

  • schema.org and JSON-LD represent the data layer, with schema.org providing the vocabulary for the data and JSON-LD constituting the format and transport for the data;
  • custom elements represent the presentation layer, configurable and separated from the data itself.

Example

Let?s consider a following example - a page that lists a couple of Google Office locations: http://polymerlabs.github.io/structured-data-web-components/demo/combined-demo.html

It contains two widgets: a map with a pin for every office and a dropdown with the list of locations. It is important that both widgets present the same data to the user and that the page is readable to search engines.

Web Components and JSON-LD demo page

In this demo we are using LocalBusiness entities to express the meaning of our data, which is the geographical location of some of the Google Offices.

The best way to check how Google is reading and indexing this page is though the new improved Structured Data Testing Tool. Submit the demo?s URL in the Fetch URL section and click Fetch and validate. The section on the right will show you parsed data retrieved from the page along with any errors that may occur. It is a very convenient way to check if your JSON-LD markup is correct and processable by Google.

Structured Data Testing Tool UI

You can read more about the tool and the improvements it introduced in the Webmaster Central blog post.

Linking components to a structured data source

The code for the demo and for the web components used to build it is on Github. Let?s look at the combined-demo.html page source code.

As a first step, we embed the data in the page using a JSON-LD script:

<script type="application/ld+json">
{...}
</script>

This way we ensure that the data is easily accessible to other consumers supporting schema.org standard and the JSON-LD format, e.g. search engines.

As a second step, we use two web components to display the data:

  • address-dropdown-jsonld - This element creates a dropdown with all the locations passed in a ?jsonld? attribute.
  • google-map-jsonld - This element creates a google map with a pin for every location passed in a ?jsonld? attribute.

In order to do so, we import them to our page using HTML imports.

<link rel="import" href="bower_components/google-map-jsonld/google-map-jsonld.html">
<link rel="import" href="bower_components/address-dropdown-jsonld/address-dropdown-jsonld.html">

Once they are imported, we can use them on our page:

<address-dropdown-jsonld jsonld=""></address-dropdown-jsonld>
<google-map-jsonld jsonld=""></google-map-jsonld>

Finally, we hook the JSON-LD data and the elements together. We do so in a polymer-ready callback (it is an event that triggers when the components are ready to use). Because the elements can be configured via attributes, it is enough to assign our JSON-LD data to the appropriate attribute of the component:

document.addEventListener('polymer-ready', function() {
    var jsonld = JSON.parse(
        document.querySelector(
            'script[type="application/ld+json"]').innerText);
    document.querySelector('google-map-jsonld').jsonld = jsonld['@graph'];
    document.querySelector('address-dropdown-jsonld').jsonld = jsonld['@graph'];
  });

JSON-LD, the powerful brother of JSON

As you probably noticed, this works very similarly to using plain, old JSON to pass data around. JSON-LD has a few advantages though, that are directly derived from its schema.org compatibility:

  • The data is structured in an unambiguous way using the schema.org standard. It is a non-trivial advantage, because it ensures you can provide a meaningful and consistent input to any JSON-LD enabled web component.
  • The data can be efficiently consumed by search engines, which improves indexing of the page, and may result in rich snippets to be shown in search results.
  • If you?re writing web components in this way, there is no need to learn or devise a new structure (and documentation) for the data the components expect - schema.org is already doing all the heavy lifting and consensus-building for you. It also makes it easier to build a whole ecosystem of compatible components.

To sum up, JSON-LD and schema.org combined with the web components technology enable building reusable, encapsulated pieces of UI that are developer and search engine friendly.

Create your own components

You can try out the examples on Github or read the Polymer?s guide on creating reusable components to start writing your own. Check the Structured Data documentation on developers.google.com to get inspired about various entities you can mark up with JSON-LD.

Consider submitting your shiny new elements to customelements.io for others to enjoy and give us a shout at @polymer or +Polymer community to show off the awesomeness!


Offline-first, fast, with the sw-precache module

You can?t read about service workers without getting excited?they?re the behind-the-scenes infrastructure that make it possible for web pages to act more like web applications. Upcoming web platform features like background sync and push notifications will rely on service workers, and following the release of Chrome 40, service worker-based caching is available to use today. If you?ve wanted to add service worker-powered offline support to your sites, but weren?t sure how to get started, the sw-precache module is for you! sw-precache hooks into your existing node-based build process (e.g. Gulp or Grunt) and generates a list of versioned resources, along with the service worker code needed to precache them. Your site can start working offline and load faster even while online, by virtue of caching.

The service worker generated by sw-precache will cache and serve the resources that you configure as part of your build process. For smaller, mostly static sites, you can have it precache every image, HTML, JavaScript, and CSS file that makes up your site. Everything will both work offline, and load fast on subsequent visits without any extra effort. For sites with lots of dynamic content, or many large images that aren?t always needed, precaching a ?skeleton? subset of your site often makes the most sense. You can combine sw-precache with one of the service worker ?recipes? or techniques outlined in the offline cookbook to provide a robust offline experience with sensible fallbacks?e.g. when a large, uncached image is requested offline, serve up a smaller, cached placeholder image instead.

Because sw-precache integrates into your site?s build process, you can use wildcards to precache all of the resources that match a pattern?there?s no list of files or URLs that you have to manually keep up to date. What?s more, the module automatically versions all your cached resources based on a hash of each file?s contents. When a change to any file is detected as part of your build process, the generated service worker knows to expire the old version and fetch the new version of the resource. All of the cache entries that remain the same are left untouched.

Here?s a basic example of using sw-precache as part of a gulp build:

gulp.task('generate-service-worker', function(callback) {
  var fs = require('fs');
  var path = require('path');
  var swPrecache = require('sw-precache');
  var rootDir = 'app';

  swPrecache({
    staticFileGlobs: [rootDir + '/**/*.{js,html,css,png,jpg,gif}'],
    stripPrefix: rootDir
  }, function(error, swFileContents) {
    if (error) {
      return callback(error);
    }
    fs.writeFile(path.join(rootDir, 'service-worker.js'), swFileContents, callback);
  });
});

You?ll see information about which resources will be precached, as well as the total precache size as part of the task output:

Starting 'generate-service-worker'...
Caching static resource 'app/css/main.css' (65 B)
Caching static resource 'app/images/one.png' (593 B)
Caching static resource 'app/images/two.png' (641 B)
Caching static resource 'app/index.html' (2.09 kB)
Caching static resource 'app/js/a.js' (7 B)
Caching static resource 'app/js/b.js' (7 B)
Caching static resource 'app/js/service-worker-registration.js' (3.37 kB)
Total precache size is about 6.77 kB for 7 resources.
Finished 'generate-service-worker' after 14 ms

There?s a lot more information at the GitHub project page, including a demo project with gulpfile.js and Gruntfile.js samples, and a script you can use to register the generated service worker. If you?d like to see it in action, just check out the recently launched Google I/O 2015 web app?thanks (in part) to sw-precache, you can browse it at your leisure, online or off.


Introduction to Service Worker: How to use Service Worker

Service Worker will revolutionize the way we build for the web. Learn about what it is, why it is important and how to use it.


The Hobbit Experience 2014: Adding WebRTC gameplay to the Hobbit Experience

Learn how North Kingdom built an immersive multimedia experience optimized for modern mobile browsers using Web RTC


Getting Started with CSS Shapes: Wrapping content around custom paths

Using CSS Shapes we can create experiences that we have never been able to create on the web before.


Built-in Browser Support for Responsive Images

Take advantage of the new element and new features of in your next responsive website.


DevTools Digest - Chrome 35: Updates to the Developer Tools in Chrome 35

Updates to the Chrome Developer Tools: CSS property quick search, memory stats for heap snapshots, CodeMirror upgrade and more.



@2014 CompCoding.com