Matt Gaunt on web.dev

Push notifications overview

2020-11-10T00:00:00Z

What are push notifications? #

Push messages enable you to bring information to the attention of your users even when they're not using your website. They're called push messages because you can "push" information to your users even when they're not active. Compare Push technology with Pull technology to understand this concept further.

Notifications present small chunks of information to a user. Websites can use notifications to tell users about important, time-sensitive events, or actions the user needs to take. The look and feel of notifications varies between platforms:

Examples of notifications on macOS and Android.

Push messages and notifications are two separate but complementary technologies. Push is the technology for sending messages from your server to users even when they're not actively using your website. Notifications is the technology for displaying the pushed information on the user's device. It's possible to use notifications without push messaging. One day it may also be possible to use push messages without user-facing notifications (silent push) but browsers currently don't allow that. In practice they're usually used together. A non-technical user probably won't understand the difference between push messages and notifications. In this collection when we say push notifications we mean the combination of pushing a message followed by displaying it as a notification. When we say push messages we are referring to push technology on its own. And when we say notifications we're referring to notification technology on its own.

Why use push notifications? #

For users, push notifications are a way to receive timely, relevant, and precise information.
For you (a website owner), push notifications are a way to increase user engagement.

How do push notifications work? #

At a high-level, the key steps for implementing push notifications are:

Adding client logic to ask the user for permission to send push notifications, and then sending client identifier information to your server for storage in a database.
Adding server logic to push messages to client devices.
Adding client logic to receive messages that have been pushed to the device and displaying them as notifications.

The rest of this page explains these steps in more detail.

Get permission to send push notifications #

First, your website needs to get the user's permission to send push notifications. This should be triggered by a user gesture, such as clicking a Yes button next to a Do you want to receive push notifications? prompt. After that confirmation, call Notification.requestPermission(). The operating system or browser on the user's device will probably present some kind of UI to formally confirm that the user wants to opt in to push notifications. This UI varies across platforms.

Subscribe the client to push notifications #

After you get permission, your website needs to initiate the process of subscribing the user to push notifications. This is done through JavaScript, using the Push API. You'll need to provide a public authentication key during the subscription process, which you'll learn more about later. After you kick off the subscription process, the browser makes a network request to a web service known as a push service, which you'll also learn more about later.

Assuming that the subscription was successful, the browser returns a PushSubscription object. You'll need to store this data long-term. Usually this is done by sending the information to a server that you control, and then having the server store it in a database.

Send a push message #

Your server doesn't actually send the push message directly to a client. A push service does that. A push service is a web service controlled by your user's browser vendor. When you want to send a push notification to a client you need to make a web service request to a push service. The web service request that you send to the push service is known as a web push protocol request. The web push protocol request should include:

What data to include in the message.
What client to send the message to.
Instructions on how the push service should deliver the message. For example, you can specify that the push service should stop attempting to send the message after 10 minutes.

Normally you make the web push protocol request through a server that you control. Of course, your server doesn't have to construct the raw web service request itself. There are libraries that can handle that for you, such as the web-push-libs. But the underlying mechanism is a web service request over HTTP.

The push service receives your request, authenticates it, and routes the push message to the appropriate client. If the client's browser is offline, the push service queues the push message until the browser comes online.

Each browser uses whatever push service it wants. You as a website developer have no control over that. This isn't a problem because the web push protocol request is standardized. In other words, you don't have to care which push service the browser vendor is using. You just need to make sure that your web push protocol request follows the spec. Among other things, the spec states that the request must include certain headers and the data must be sent as a stream of bytes.

You do, however, need to make sure that you're sending the web push protocol request to the correct push service. The PushSubscription data that the browser returned to you during the subscription process provides this information. A PushSubscription object looks like this:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/c1KrmpTuRm…",
  "expirationTime": null,
  "keys": {
    "p256dh": "BGyyVt9FFV…",
    "auth": "R9sidzkcdf…"
  }
}

The domain of the endpoint is essentially the push service. The path of the endpoint is client identifier information that helps the push service determine exactly which client to push the message to.

The keys are used for encryption, which is explained next.

Encrypt the push message #

The data that you send to a push service must be encrypted. This prevents the push service from being able to view the data you're sending to the client. Remember that the browser vendor decides what push service to use, and that push service could theoretically be unsafe or insecure. Your server must use the keys provided in the PushSubscription to encrypt its web push protocol requests.

Sign your web push protocol requests #

The push service provides a way to prevent anyone else from sending messages to your users. Technically you don't have to do this but the easiest implementation on Chrome requires it. It's optional on Firefox. Other browsers may require it in the future.

This workflow involves a private key and public key that are unique to your application. The authentication process roughly works like this:

You generate the private and public key as a one-off task. The combination of the private and public key is known as the application server keys. You might also see them called the VAPID keys. VAPID is the spec that defines this authentication process.
When you subscribe a client to push notifications from your JavaScript code, you provide your public key. When the push service generates an endpoint for the device, it associates the provided public key with the endpoint.
When you send a web push protocol request, you sign some JSON information with your private key.
When the push service receives your web push protocol request, it uses the stored public key to authenticate the signed information. If the signature is valid then the push service knows that the request came from a server with the matching private key.

Customize the delivery of the push message #

The web push protocol request spec also defines parameters that let you customize how the push service attempts to send the push message to the client. For example, you can customize:

The Time-To-Live (TTL) of a message, which defines how long the push service should attempt to deliver a message.
The urgency of the message, which is useful in case the push service is preserving the client's battery life by only delivering high-priority messages.
The topic of a message, which replaces any pending messages of the same topic with the latest message.

Receive and display the pushed messages as notifications #

Once you've sent the web push protocol request to the push service, the push service keeps your request queued until one of the following events happens:

The client comes online and the push service delivers the push message.
The message expires.

When a client browser receives a pushed message, it decrypts the push message data and dispatches a push event to your service worker. A service worker is basically JavaScript code that can run in the background, even when your website isn't open or the browser is closed. In your service worker's push event handler you call ServiceWorkerRegistration.showNotification() to display the information as a notification.

Where to go next #

Web Push Notification Overview
How Push Works
Subscribing a User
Permission UX
Sending Messages with Web Push Libraries
Web Push Protocol
Handling Push Events
Displaying a Notification
Notification Behavior
Common Notification Patterns
Push Notifications FAQ
Common Issues and Reporting Bugs

Code labs #

Common Issues and Reporting Bugs

2017-03-30T00:00:00Z

When you hit an issue with web push, it can be difficult to debug the issue or find help. This doc outlines some of the common issues and what you should do if you've found a bug in Chrome or Firefox.

Before we dive into debugging push, you may be hitting issues with debugging service workers themselves, the file not updating, failing to register or generally just unusual behavior. There is an awesome document on debugging service workers that I strongly recommend checking out if you are new to service worker development.

There are two distinct stages to check off when developing and testing web push, each with its own set of common issues / problems:

Sending a Message: Make sure that sending messages is successful. You should be getting a 201 HTTP code. If you aren't :
- Check for Authorization Errors: If you receive an authorization error message see the Authorization Issues section.
- Other API Errors: If you receive a non-201 status code response, see the HTTP Status Codes section for guidance on the cause of the issue.
Receiving a Message: If you're able to send a message successfully, but the message is not received on the browser:
- Check for Encryption Issues: See the Payload Encryption Issue Section.
- Check for Connection Issues: If the problem is on Chrome, it may be a connection. See Connection Issues section for more info.

If you aren't able to send and receive a push message and the relevant sections in this doc aren't helping debug the problem then you may have found a bug in the push mechanism itself. In this case, refer to the Raising Bug Reports section to file a good bug report with all the necessary information to expedite the bug fixing process.

One thing I'd like to call out before we start is that Firefox and the Mozilla AutoPush Service have great error messages. If you get stuck and are not sure what the problem is, then test in Firefox and see if you get a more helpful error message.

Authorization issues #

Authorization issues are one of the most common issues developers hit when starting out with web push. This is normally a problem with the configuration of a site's Application Server Keys (a.k.a. VAPID keys) .

The easiest way to support push in both Firefox and Chrome is to supply an applicationServerKey in the subscribe() call. The down side is that any discrepancy between your front end and server's keys will result in an authorization error.

On Chrome and FCM #

For Chrome, which uses FCM as a push service, you'll receive an UnauthorizedRegistration response from FCM for a range of different errors, all involving the application server keys.

You'll receive an UnauthorizedRegistration error in any of the following situations:

If you fail to define an Authorization header in the request to FCM.
Your application key used to subscribe the user doesn't match the key used to sign the Authorization header.
The expiration is invalid in your JWT, i.e. the expiration exceeds 24 hours or the JWT has expired.
The JWT is malformed or has invalid values.

The full error response looks like this:

<html>
  <head>
    <title>UnauthorizedRegistration</title>
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <h1>UnauthorizedRegistration</h1>

    <h2>Error 400</h2>
  </body>
</html>

If you receive this error message in Chrome, consider testing in Firefox to see if it'll provide more insight to the problem.

Firefox and Mozilla AutoPush #

Firefox and Mozilla AutoPush provide a friendly set of error messages for Authorization issues.

You'll also receive an Unauthorized error response from Mozilla AutoPush if the Authorization header is not included in your push request.

{
  "errno": 109,
  "message": "Request did not validate missing authorization header",
  "code": 401,
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "error": "Unauthorized"
}

If the expiration in your JWT has expired, you'll also receive an Unauthorized error with a message that explains that the token has expired.

{
  "code": 401,
  "errno": 109,
  "error": "Unauthorized",
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "message": "Request did not validate Invalid bearer token: Auth expired"
}

If the application server keys are different between when the user was subscribed and when the Authorization header was signed, a Not Found error will be returned:

{
  "errno": 102,
  "message": "Request did not validate invalid token",
  "code": 404,
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "error": "Not Found"
}

Lastly, if you have an invalid value in your JWT (for example if the "alg" value is an unexpected value), you'll receive the following error from Mozilla AutoPush:

{
  "code": 401,
  "errno": 109,
  "error": "Unauthorized",
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "message": "Request did not validate Invalid Authorization Header"
}

HTTP status codes #

There are a range of issues that can result in a non-201 response code from a push service. Below is a list of HTTP status codes and what they mean in relation to web push.

Status Code	Description
429	Too many requests. Your application server has reached a rate limit with a push service. The response from the service should include a 'Retry-After' header to indicate how long before another request can be made.
400	Invalid request. One of your headers is invalid or poorly formatted.
404	Not Found. In this case you should delete the PushSubscription from your back end and wait for an opportunity to resubscribe the user.
410	Gone. The subscription is no longer valid and should be removed from your back end. This can be reproduced by calling `unsubscribe()` on a `PushSubscription`.
413	Payload size too large. The minimum size payload a push service must support is 4096 bytes (or 4kb). Anything larger can result in this error.

If the HTTP status code is not in this list and the error message is not helpful, check the Web Push Protocol spec to see if the status code is referenced along with a scenario of when that status code can be used.

Payload encryption issue #

If you can successfully trigger a push message (i.e. send a message to a web push service and receive a 201 response code) but the push event never fires in your service worker, this normally indicates that the browser failed to decrypt the message it received.

If this is the case, you should see an error message in Firefox's DevTools console like so:

To check if this is the issue in Chrome, do the following:

Go to about://gcm-internals and click the "Start Recording" button.

Trigger a push message, and look under the "Message Decryption Failure Log".

If there is an issue with the decryption of the payload, you'll see an error similar to the one displayed above. (Notice the AES-GCM decryption failed message in the details column.)

There are a few tools which may help debug encryption if this is your issue:

Connection issue #

If you aren't receiving a push event in your service worker and you aren't seeing any decryption errors, then the browser may be failing to connect to a push service.

In Chrome, you can check whether the browser is receiving messages by examining the 'Receive Message Log' (sic) in about://gcm-internals.

If you aren't seeing the message arrive in a timely fashion, then make sure that the connection status of your browser is CONNECTED:

If it's not 'CONNECTED', you may need to delete your current profile and create a new one. If that still doesn't solve the issue, please raise a bug report as suggested below.

Raising bug reports #

If none of the above helps with your issue and there is no sign of what the problem could be, please raise an issue against the browser you are having an issue with:

For Chrome, you'd raise the issue here: https://bugs.chromium.org/p/chromium/issues/list For Firefox, you should raise the issue on: https://bugzilla.mozilla.org/

To provide a good bug report, you should provide the following details:

Browsers you've tested in (e.g. Chrome version 50, Chrome version 51, Firefox version 50, Firefox version 51).
An example PushSubscription that demonstrates the problem.
Include any example requests (i.e. content of network requests to a push service, including headers).
Include any example responses from network requests as well.

If you can provide a reproducible example, either source code or a hosted web site, it often speeds up diagnosing and solving the problem.

Where to go next #

Web Push Notification Overview
How Push Works
Subscribing a User
Permission UX
Sending Messages with Web Push Libraries
Web Push Protocol
Handling Push Events
Displaying a Notification
Notification Behavior
Common Notification Patterns
Push Notifications FAQ
Common Issues and Reporting Bugs

Code labs #

Displaying a Notification

2016-06-30T00:00:00Z

The notification options is split into two sections, one that deals with the visual aspects (this section) and one that explains the behavioral aspects of notifications (the next section).

You can play around with various notification options in various browsers on various platforms using Peter Beverloo's Notification Generator.

Visual Options #

The API for showing a notification is simple:

<ServiceWorkerRegistration>.showNotification(<title>, <options>);

Both arguments, title and options are optional.

The title is a string and options can be any of the following:

{
  "//": "Visual Options",
  "body": "<String>",
  "icon": "<URL String>",
  "image": "<URL String>",
  "badge": "<URL String>",
  "dir": "<String of 'auto' | 'ltr' | 'rtl'>",
  "timestamp": "<Long>"

  "//": "Both visual & behavioral options",
  "actions": "<Array of Strings>",
  "data": "<Anything>",

  "//": "Behavioral Options",
  "tag": "<String>",
  "requireInteraction": "<boolean>",
  "renotify": "<Boolean>",
  "vibrate": "<Array of Integers>",
  "sound": "<URL String>",
  "silent": "<Boolean>",
}

Let's look at the visual options:

Title and body options #

This is what a notification looks like without the title and options in Chrome on Windows:

As you can see, the browser name is used as the title and the "New notification" placeholder is used as the notification body.

If a progressive web application is installed on the device, the web app name will be used instead of the browser name:

If we ran the following code:

const title = 'Simple Title';

const options = {
  body: 'Simple piece of body text.\nSecond line of body text :)',
};

registration.showNotification(title, options);

we'd get this notification in Chrome on Linux:

In Firefox on Linux it would look like this:

This is what the notification with a lot of text in the title and body looks like in Chrome on Linux:

Firefox on Linux collapses the body text until you hover the notification, causing the notification to expand:

The same notifications in Firefox on Windows look like this:

As you can see, the same notification may look different in different browsers. It may also look different in the same browser on different platforms.

Chrome and Firefox use the system notifications and notification center on platforms where these are available.

For example, system notifications on macOS don't support images and actions (buttons and inline replies).

Chrome also has a custom notifications for all desktop platforms. You can enable it by setting the chrome://flags/#enable-system-notifications flag to the Disabled state.

Icon #

The icon option is essentially a small image you can show next to the title and body text.

In your code you need to provide a URL to the image you'd like to load:

const title = 'Icon Notification';

const options = {
  icon: '/images/demos/icon-512x512.png',
};

registration.showNotification(title, options);

You get this notification in Chrome on Linux:

and in Firefox on Linux:

Sadly there aren't any solid guidelines for what size image to use for an icon.

Android seems to want a 64dp image (which is 64px multiples by the device pixel ratio).

Assuming the highest pixel ratio for a device is 3, an icon size of 192px or more is a safe bet.

Badge #

The badge is a small monochrome icon that is used to portray a little more information to the user about where the notification is from:

const title = 'Badge Notification';

const options = {
  badge: '/images/demos/badge-128x128.png',
};

registration.showNotification(title, options);

At the time of writing the badge is only used in Chrome on Android.

On other browsers (or Chrome without the badge), you'll see an icon of the browser.

As with the icon option, there are no real guidelines on what size to use.

Digging through Android guidelines the recommended size is 24px multiplied by the device pixel ratio.

Meaning an image of 72px or more should be good (assuming a max device pixel ratio of 3).

Image #

The image option can be used to display a larger image to the user. This is particularly useful to display a preview image to the user.

const title = 'Image Notification';

const options = {
  image: '/images/demos/unsplash-farzad-nazifi-1600x1100.jpg',
};

registration.showNotification(title, options);

In Chrome on Linux the notification will look like this:

In Chrome on Android the cropping and ratio are different:

Given the differences in ratio between desktop and mobile, it's extremely hard to suggest guidelines.

Since Chrome on desktop doesn't fill the available space and has a ratio of 4:3, perhaps the best approach is to serve an image with this ratio and allow Android to crop the image. That being said, the image option may still change.

On Android, the only guideline is a width of 450dp.

Using this guideline, an image of width 1350px or more would be a good bet.

Actions (Buttons) #

You can define actions to display buttons with a notification:

const title = 'Actions Notification';

const options = {
  actions: [
    {
      action: 'coffee-action',
      type: 'button',
      title: 'Coffee',
      icon: '/images/demos/action-1-128x128.png',
    },
    {
      action: 'doughnut-action',
      type: 'button',
      title: 'Doughnut',
      icon: '/images/demos/action-2-128x128.png',
    },
    {
      action: 'gramophone-action',
      type: 'button',
      title: 'Gramophone',
      icon: '/images/demos/action-3-128x128.png',
    },
    {
      action: 'atom-action',
      type: 'button',
      title: 'Atom',
      icon: '/images/demos/action-4-128x128.png',
    },
  ],
};

registration.showNotification(title, options);

For each action you can define a title, an action (which is essentially an ID), an icon, and a type. The title and icon is what you can see in the notification. The ID is used when detecting that the action button had been clicked (more about this in the next section). The type can be omitted because 'button' is the default value.

At the time of writing only Chrome and Opera for Android support actions.

In the example above there are four actions defined to illustrate that you can define more actions than will be displayed. If you want to know the number of actions that will be displayed by the browser, you can check window.Notification?.maxActions:

const maxVisibleActions = window.Notification?.maxActions;

if (maxVisibleActions) {
  options.body = `Up to ${maxVisibleActions} notification actions can be displayed.`;
} else {
  options.body = 'Notification actions are not supported.';
}

On desktop, the action button icons display their colors (see the pink doughnut):

On Android 6 and earlier, the icons are colored to match the system color scheme:

On Android 7 and later, the action icons aren't shown at all.

Chrome will hopefully change it's behavior on desktop to match Android (i.e. apply the appropriate color scheme to make the icons match the system look and feel). In the meantime, you can match Chrome's text color by making your icons have a color of #333333.

It's also worth calling out that icons look crisp on Android but not on desktop.

The best size I could get to work on desktop Chrome was 24px x 24px. This sadly looks out of place on Android.

The best practice we can draw from these differences:

Stick to a consistent color scheme for your icons so at least all your icons are consistently displayed to the user.
Make sure they work in monochrome as some platforms may display them that way.
Test the size and see what works for you. 128px × 128px works well on Android for me but was poor quality on desktop.
Expect your action icons not to be displayed at all.

The Notification spec is exploring a way to define multiple sizes of icons, but it looks like it'll be some time before anything is agreed upon.

Actions (Inline Replies) #

You can add an inline reply to the notification by defining an action with the 'text' type:

const title = 'Alexey Rodionov';

const options = {
  body: 'How are you doing? )',
  image: '/images/demos/avatar-512x512.jpg',
  icon: '/images/demos/icon-512x512.png',
  badge: '/images/demos/badge-128x128.png',
  actions: [
    {
      action: 'reply',
      type: 'text',
      title: 'Reply',
      icon: '/images/demos/action-5-128x128.png',
    }
  ],
};

registration.showNotification(title, options);

This is what it will look like on Android:

Clicking on the action button opens a text input field:

You can customize the placeholder for the text input field:

const title = 'Alexey Rodionov';

const options = {
  body: 'How are you doing? )',
  icon: '/images/demos/avatar-512x512.jpg',
  badge: '/images/demos/badge-128x128.png',
  actions: [
    {
      action: 'reply',
      type: 'text',
      title: 'Reply',
      icon: '/images/demos/action-5-128x128.png',
      placeholder: 'Type text here',
    }
  ],
};

registration.showNotification(title, options);

In Chrome on Windows, the text input field is always visible without having to click the action button:

You can add more than one inline reply or combine buttons and inline replies:

const title = 'Poll';

const options = {
  body: 'Do you like this photo?',
  image: '/images/demos/cat-image.jpg',
  icon: '/images/demos/icon-512x512.png',
  badge: '/images/demos/badge-128x128.png',
  actions: [
    {
      action: 'yes',
      type: 'button',
      title: '👍 Yes',
    },
    {
      action: 'no',
      type: 'text',
      title: '👎 No (explain why)',
      placeholder: 'Type your explanation here',
    },
  ],
};

registration.showNotification(title, options);

Direction #

The dir parameter allows you to define which direction the text should be displayed, right-to-left or left-to-right.

In testing, it seemed that the direction was largely determined by the text rather than this parameter. According to the spec, this is intended to suggest to the browser how to layout options like actions, but I saw no difference.

Probably best to define if you can, otherwise the browser should do the right thing according to the text supplied.

The parameter should be set to either auto, ltr or rtl.

A right-to-left language used on Chrome on Linux looks like this:

In Firefox (while hovering over it) you'll get this:

Vibrate #

The vibrate option allows you to define a vibration pattern that'll run when a notification is displayed, assuming the user's current settings allow for vibrations (i.e. the device isn't in silent mode).

The format of the vibrate option should be an array of numbers that describe the number of milliseconds the device should vibrate, followed by the number of milliseconds the device should not vibrate.

const title = 'Vibrate Notification';

const options = {
  // Star Wars shamelessly taken from the awesome Peter Beverloo
  // https://tests.peter.sh/notification-generator/
  vibrate: [
    500, 110, 500, 110, 450, 110, 200, 110, 170, 40, 450, 110, 200, 110, 170,
    40, 500,
  ],
};

registration.showNotification(title, options);

This only affects devices that support vibration.

Sound #

The sound parameter allows you to define a sound to play when the notification is received.

At the time of writing, no browser has support for this option.

const title = 'Sound Notification';

const options = {
  sound: '/demos/notification-examples/audio/notification-sound.mp3',
};

registration.showNotification(title, options);

Timestamp #

Timestamp allows you to tell the platform the time when an event occurred that resulted in the push notification being sent.

The timestamp should be the number of milliseconds since 00:00:00 UTC, which is 1 January 1970 (which is the UNIX epoch).

const title = 'Timestamp Notification';

const options = {
  body: 'Timestamp is set to "01 Jan 2000 00:00:00".',
  timestamp: Date.parse('01 Jan 2000 00:00:00'),
};

registration.showNotification(title, options);

UX Best Practices #

The biggest UX failure I've seen with notifications is a lack of specificity in the information displayed by a notification.

You should consider why you sent the push message in the first place and make sure all of the notification options are used to help users understand why they are reading that notification.

To be honest, it's easy to see examples and think "I'll never make that mistake". But it's easier to fall into that trap than you might think.

Some common pitfalls to avoid:

Don't put your website in the title or the body. Browsers include your domain in the notification so don't duplicate it.
Use all the information that you have available. If you send a push message because someone sent a message to a user, rather than using a title of 'New Message' and body of 'Click here to read it.' use a title of 'John just sent a new message' and set the body of the notification to part of the message.

Browsers and feature detection #

At the time of writing, there is a pretty big disparity between Chrome and Firefox in terms of feature support for notifications.

Luckily, you can detect support for notification features by looking at the window.Notification prototype.

Let's say we wanted to know if a notification supports action buttons, we'd do the following:

if ('actions' in window.Notification?.prototype) {
  // Action buttons are supported.
} else {
  // Action buttons are NOT supported.
}

With this, we could change the notification we display to our users.

With the other options, just do the same as above, replacing 'actions' with the desired parameter name.

Where to go next #

Web Push Notification Overview
How Push Works
Subscribing a User
Permission UX
Sending Messages with Web Push Libraries
Web Push Protocol
Handling Push Events
Displaying a Notification
Notification Behavior
Common Notification Patterns
Push Notifications FAQ
Common Issues and Reporting Bugs

Code labs #

Notification behavior

2016-06-30T00:00:00Z

So far, we've looked at the options that alter the visual appearance of a notification. There are also options that alter the behavior of notifications.

By default, calling showNotification() with just visual options will have the following behaviors:

Clicking on the notification does nothing.
Each new notification is shown one after the other. The browser will not collapse the notifications in any way.
The platform may play a sound or vibrate the user's device (depending on the platform).
On some platforms, the notification will disappear after a short period of time while others will show the notification unless the user interacts with it. (For example, compare your notifications on Android and Desktop.)

In this section, we are going to look at how we can alter these default behaviors using options alone. These are relatively easy to implement and take advantage of.

Notification Click Event #

When a user clicks on a notification, the default behavior is for nothing to happen. It doesn't even close or remove the notification.

The common practice for a notification click is for it to close and perform some other logic (i.e. open a window or make some API call to the application).

To achieve this, you need to add a 'notificationclick' event listener to our service worker. This will be called whenever a notification is clicked.

self.addEventListener('notificationclick', (event) => {
  const clickedNotification = event.notification;
  clickedNotification.close();

  // Do something as the result of the notification click
  const promiseChain = doSomething();
  event.waitUntil(promiseChain);
});

As you can see in this example, the notification that was clicked can be accessed as event.notification. From this, you can access the notification's properties and methods. In this case, you call its close() method and perform additional work.

Actions #

Actions allow you to create another level of interaction with your users over just clicking the notification.

Buttons #

In the previous section, you saw how to define action buttons when calling showNotification():

const title = 'Actions Notification';

const options = {
  actions: [
    {
      action: 'coffee-action',
      title: 'Coffee',
      type: 'button',
      icon: '/images/demos/action-1-128x128.png',
    },
    {
      action: 'doughnut-action',
      type: 'button',
      title: 'Doughnut',
      icon: '/images/demos/action-2-128x128.png',
    },
    {
      action: 'gramophone-action',
      type: 'button',
      title: 'Gramophone',
      icon: '/images/demos/action-3-128x128.png',
    },
    {
      action: 'atom-action',
      type: 'button',
      title: 'Atom',
      icon: '/images/demos/action-4-128x128.png',
    },
  ],
};

registration.showNotification(title, options);

If the user clicks an action button, check the event.action value in the noticationclick event to tell which action button was clicked.

event.action will contain the action value set in the options. In the example above the event.action values would be one of the following: 'coffee-action', 'doughnut-action', 'gramophone-action' or 'atom-action'.

With this we would detect notification clicks or action clicks like so:

self.addEventListener('notificationclick', (event) => {
  if (!event.action) {
    // Was a normal notification click
    console.log('Notification Click.');
    return;
  }

  switch (event.action) {
    case 'coffee-action':
      console.log("User ❤️️'s coffee.");
      break;
    case 'doughnut-action':
      console.log("User ❤️️'s doughnuts.");
      break;
    case 'gramophone-action':
      console.log("User ❤️️'s music.");
      break;
    case 'atom-action':
      console.log("User ❤️️'s science.");
      break;
    default:
      console.log(`Unknown action clicked: '${event.action}'`);
      break;
  }
});

Inline Replies #

Also, in the previous section, you saw how to add an inline reply to the notification:

const title = 'Poll';

const options = {
  body: 'Do you like this photo?',
  image: '/images/demos/cat-image.jpg',
  icon: '/images/demos/icon-512x512.png',
  badge: '/images/demos/badge-128x128.png',
  actions: [
    {
      action: 'yes',
      type: 'button',
      title: '👍 Yes',
    },
    {
      action: 'no',
      type: 'text',
      title: '👎 No (explain why)',
      placeholder: 'Type your explanation here',
    },
  ],
};

registration.showNotification(title, options);

event.reply will contain the value typed by the user in the input field:

self.addEventListener('notificationclick', (event) => {
  const reply = event.reply;

  // Do something with the user's reply
  const promiseChain = doSomething(reply);
  event.waitUntil(promiseChain);
});

Tag #

The tag option is essentially a string ID that "groups" notifications together, providing an easy way to determine how multiple notifications are displayed to the user. This is easiest to explain with an example.

Let's display a notification and give it a tag, of 'message-group-1'. We'd display the notification with this code:

const title = 'Notification 1 of 3';

const options = {
  body: "With 'tag' of 'message-group-1'",
  tag: 'message-group-1',
};

registration.showNotification(title, options);

Which will show our first notification.

Let's display a second notification with a new tag of 'message-group-2', like so:

const title = 'Notification 2 of 3';

const options = {
  body: "With 'tag' of 'message-group-2'",
  tag: 'message-group-2',
};

registration.showNotification(title, options);

This will display a second notification to the user.

Now let's show a third notification but re-use the first tag of 'message-group-1'. Doing this will close the first notification and replace it with our new notification.

const title = 'Notification 3 of 3';

const options = {
  body: "With 'tag' of 'message-group-1'",
  tag: 'message-group-1',
};

registration.showNotification(title, options);

Now we have two notifications even though showNotification() was called three times.

The tag option is simply a way of grouping messages so that any old notifications that are currently displayed will be closed if they have the same tag as a new notification.

A subtlety to using tag is that when it replaces a notification, it will do so without a sound or vibration.

This is where the renotify option comes in.

Renotify #

This largely applies to mobile devices at the time of writing. Setting this option makes new notifications vibrate and play a system sound.

There are scenarios where you might want a replacing notification to notify the user rather than silently update. Chat applications are a good example. In this case, you should set tag and renotify to true.

const title = 'Notification 2 of 2';

const options = {
  tag: 'renotify',
  renotify: true,
};

registration.showNotification(title, options);

Silent #

This option allows you to show a new notification but prevents the default behavior of vibration, sound and turning on the device's display.

This is ideal if your notifications don't require immediate attention from the user.

const title = 'Silent Notification';

const options = {
  silent: true,
};

registration.showNotification(title, options);

Note: If you define both silent and renotify, silent will take precedence.

Requires interaction #

Chrome on desktop will show notifications for a set time period before hiding them. Chrome on Android doesn't have this behavior. Notifications are displayed until the user interacts with them.

To force a notification to stay visible until the user interacts with it, add the requireInteraction option. This will show the notification until the user dismisses or clicks your notification.

const title = 'Require Interaction Notification';

const options = {
  requireInteraction: true,
};

registration.showNotification(title, options);

Use this option with consideration. Showing a notification and forcing the user to stop what they are doing to dismiss your notification can be frustrating.

In the next section, we are going to look at some of the common patterns used on the web for managing notifications and performing actions such as opening pages when a notification is clicked.

Where to go next #

Code labs #

The Web Push Protocol

2016-06-30T00:00:00Z

We've seen how a library can be used to trigger push messages, but what exactly are these libraries doing?

Well, they're making network requests while ensuring such requests are the right format. The spec that defines this network request is the Web Push Protocol.

This section outlines how the server can identify itself with application server keys and how the encrypted payload and associated data is sent.

This isn't a pretty side of web push and I'm no expert at encryption, but let's look through each piece since it's handy to know what these libraries are doing under the hood.

Application server keys #

When we subscribe a user, we pass in an applicationServerKey. This key is passed to the push service and used to check that the application that subscribed the user is also the application that is triggering push messages.

When we trigger a push message, there are a set of headers that we send that allow the push service to authenticate the application. (This is defined by the VAPID spec.)

What does all this actually mean and what exactly happens? Well these are the steps taken for application server authentication:

The application server signs some JSON information with it's private application key.
This signed information is sent to the push service as a header in a POST request.
The push service uses the stored public key it received from pushManager.subscribe() to check the received information is signed by the private key relating to the public key. Remember: The public key is the applicationServerKey passed into the subscribe call.
If the signed information is valid the push service sends the push message to the user.

An example of this flow of information is below. (Note the legend in the bottom left to indicate public and private keys.)

The "signed information" added to a header in the request is a JSON Web Token.

JSON web token #

A JSON web token (or JWT for short) is a way of sending a message to a third party such that the receiver can validate who sent it.

When a third party receives a message, they need to get the senders public key and use it to validate the signature of the JWT. If the signature is valid then the JWT must have been signed with the matching private key so must be from the expected sender.

There are a host of libraries on https://jwt.io/ that can perform the signing for you and I'd recommend you do that where you can. For completeness, let's look at how to manually create a signed JWT.

Web push and signed JWTs #

A signed JWT is just a string, though it can be thought of as three strings joined by dots.

The first and second strings (The JWT info and JWT data) are pieces of JSON that have been base64 encoded, meaning it's publicly readable.

The first string is information about the JWT itself, indicating which algorithm was used to create the signature.

The JWT info for web push must contain the following information:

{
  "typ": "JWT",
  "alg": "ES256"
}

The second string is the JWT Data. This provides information about the sender of the JWT, who it's intended for and how long it's valid.

For web push, the data would have this format:

{
  "aud": "https://some-push-service.org",
  "exp": "1469618703",
  "sub": "mailto:example@web-push-book.org"
}

The aud value is the "audience", i.e. who the JWT is for. For web push the audience is the push service, so we set it to the origin of the push service.

The exp value is the expiration of the JWT, this prevent snoopers from being able to re-use a JWT if they intercept it. The expiration is a timestamp in seconds and must be no longer 24 hours.

In Node.js the expiration is set using:

Math.floor(Date.now() / 1000) + 12 * 60 * 60;

It's 12 hours rather than 24 hours to avoid any issues with clock differences between the sending application and the push service.

Finally, the sub value needs to be either a URL or a mailto email address. This is so that if a push service needed to reach out to sender, it can find contact information from the JWT. (This is why the web-push library needed an email address).

Just like the JWT Info, the JWT Data is encoded as a URL safe base64 string.

The third string, the signature, is the result of taking the first two strings (the JWT Info and JWT Data), joining them with a dot character, which we'll call the "unsigned token", and signing it.

The signing process requires encrypting the "unsigned token" using ES256. According to the JWT spec, ES256 is short for "ECDSA using the P-256 curve and the SHA-256 hash algorithm". Using web crypto you can create the signature like so:

// Utility function for UTF-8 encoding a string to an ArrayBuffer.
const utf8Encoder = new TextEncoder('utf-8');

// The unsigned token is the concatenation of the URL-safe base64 encoded
// header and body.
const unsignedToken = .....;

// Sign the |unsignedToken| using ES256 (SHA-256 over ECDSA).
const key = {
  kty: 'EC',
  crv: 'P-256',
  x: window.uint8ArrayToBase64Url(
    applicationServerKeys.publicKey.subarray(1, 33)),
  y: window.uint8ArrayToBase64Url(
    applicationServerKeys.publicKey.subarray(33, 65)),
  d: window.uint8ArrayToBase64Url(applicationServerKeys.privateKey),
};

// Sign the |unsignedToken| with the server's private key to generate
// the signature.
return crypto.subtle.importKey('jwk', key, {
  name: 'ECDSA', namedCurve: 'P-256',
}, true, ['sign'])
.then((key) => {
  return crypto.subtle.sign({
    name: 'ECDSA',
    hash: {
      name: 'SHA-256',
    },
  }, key, utf8Encoder.encode(unsignedToken));
})
.then((signature) => {
  console.log('Signature: ', signature);
});

A push service can validate a JWT using the public application server key to decrypt the signature and make sure the decrypted string is the same as the "unsigned token" (i.e. the first two strings in the JWT).

The signed JWT (i.e. all three strings joined by dots), is sent to the web push service as the Authorization header with WebPush prepended, like so:

Authorization: 'WebPush [JWT Info].[JWT Data].[Signature]';

The Web Push Protocol also states the public application server key must be sent in the Crypto-Key header as a URL safe base64 encoded string with p256ecdsa= prepended to it.

Crypto-Key: p256ecdsa=[URL Safe Base64 Public Application Server Key]

The Payload Encryption #

Next let's look at how we can send a payload with a push message so that when our web app receives a push message, it can access the data it receives.

A common question that arises from any who've used other push services is why does the web push payload need to be encrypted? With native apps, push messages can send data as plain text.

Part of the beauty of web push is that because all push services use the same API (the web push protocol), developers don't have to care who the push service is. We can make a request in the right format and expect a push message to be sent. The downside of this is that developers could conceivably send messages to a push service that isn't trustworthy. By encrypting the payload, a push service can't read the data that's sent. Only the browser can decrypt the information. This protects the user's data.

The encryption of the payload is defined in the Message Encryption spec.

Before we look at the specific steps to encrypt a push messages payload, we should cover some techniques that'll be used during the encryption process. (Massive hat tip to Mat Scales for his excellent article on push encryption.)

ECDH and HKDF #

Both ECDH and HKDF are used throughout the encryption process and offer benefits for the purpose of encrypting information.

ECDH: Elliptic Curve Diffie-Hellman key exchange #

Imagine you have two people who want to share information, Alice and Bob. Both Alice and Bob have their own public and private keys. Alice and Bob share their public keys with each other.

The useful property of keys generated with ECDH is that Alice can use her private key and Bob's public key to create secret value 'X'. Bob can do the same, taking his private key and Alice's public key to independently create the same value 'X'. This makes 'X' a shared secret and Alice and Bob only had to share their public key. Now Bob and Alice can use 'X' to encrypt and decrypt messages between them.

ECDH, to the best of my knowledge, defines the properties of curves which allow this "feature" of making a shared secret 'X'.

This is a high level explanation of ECDH, if you want to learn more I recommend checking out this video.

In terms of code; most languages / platforms come with libraries to make it easy to generate these keys.

In node we'd do the following:

const keyCurve = crypto.createECDH('prime256v1');
keyCurve.generateKeys();

const publicKey = keyCurve.getPublicKey();
const privateKey = keyCurve.getPrivateKey();

HKDF: HMAC based key derivation function #

Wikipedia has a succinct description of HKDF:

HKDF is an HMAC based key derivation function that transforms any weak key material into cryptographically strong key material. It can be used, for example, to convert Diffie Hellman exchanged shared secrets into key material suitable for use in encryption, integrity checking or authentication.

Essentially, HKDF will take input that is not particular secure and make it more secure.

The spec defining this encryption requires use of SHA-256 as our hash algorithm and the resulting keys for HKDF in web push should be no longer than 256 bits (32 bytes).

In node this could be implemented like so:

// Simplified HKDF, returning keys up to 32 bytes long
function hkdf(salt, ikm, info, length) {
  // Extract
  const keyHmac = crypto.createHmac('sha256', salt);
  keyHmac.update(ikm);
  const key = keyHmac.digest();

  // Expand
  const infoHmac = crypto.createHmac('sha256', key);
  infoHmac.update(info);

  // A one byte long buffer containing only 0x01
  const ONE_BUFFER = new Buffer(1).fill(1);
  infoHmac.update(ONE_BUFFER);

  return infoHmac.digest().slice(0, length);
}

Hat tip to Mat Scale's article for this example code.

This loosely covers ECDH and HKDF.

ECDH a secure way to share public keys and generate a shared secret. HKDF is a way to take insecure material and make it secure.

This will be used during the encryption of our payload. Next let's look at what we take as input and how that's encrypted.

Inputs #

When we want to send a push message to a user with a payload, there are three inputs we need:

The payload itself.
The auth secret from the PushSubscription.
The p256dh key from the PushSubscription.

We've seen the auth and p256dh values being retrieved from a PushSubscription but for a quick reminder, given a subscription we'd need these values:

subscription.toJSON().keys.auth;
subscription.toJSON().keys.p256dh;

subscription.getKey('auth');
subscription.getKey('p256dh');

The auth value should be treated as a secret and not shared outside of your application.

The p256dh key is a public key, this is sometimes referred to as the client public key. Here we'll refer to p256dh as the subscription public key. The subscription public key is generated by the browser. The browser will keep the private key secret and use it for decrypting the payload.

These three values, auth, p256dh and payload are needed as inputs and the result of the encryption process will be the encrypted payload, a salt value and a public key used just for encrypting the data.

Salt

The salt needs to be 16 bytes of random data. In NodeJS, we'd do the following to create a salt:

const salt = crypto.randomBytes(16);

Public / Private Keys

The public and private keys should be generated using a P-256 elliptic curve, which we'd do in Node like so:

const localKeysCurve = crypto.createECDH('prime256v1');
localKeysCurve.generateKeys();

const localPublicKey = localKeysCurve.getPublicKey();
const localPrivateKey = localKeysCurve.getPrivateKey();

We'll refer to these keys as "local keys". They are used just for encryption and have nothing to do with application server keys.

With the payload, auth secret and subscription public key as inputs and with a newly generated salt and set of local keys, we are ready to actually do some encryption.

Shared secret #

The first step is to create a shared secret using the subscription public key and our new private key (remember the ECDH explanation with Alice and Bob? Just like that).

const sharedSecret = localKeysCurve.computeSecret(
  subscription.keys.p256dh,
  'base64',
);

This is used in the next step to calculate the Pseudo Random Key (PRK).

Pseudo random key #

The Pseudo Random Key (PRK) is the combination of the push subscription's auth secret, and the shared secret we just created.

const authEncBuff = new Buffer('Content-Encoding: auth\0', 'utf8');
const prk = hkdf(subscription.keys.auth, sharedSecret, authEncBuff, 32);

You might be wondering what the Content-Encoding: auth\0 string is for. In short, it doesn't have a clear purpose, although browsers could decrypt an incoming message and look for the expected content-encoding. The \0 adds a byte with a value of 0 to end of the Buffer. This is expected by browsers decrypting the message who will expect so many bytes for the content encoding, followed a byte with value 0, followed by the encrypted data.

Our Pseudo Random Key is simply running the auth, shared secret and a piece of encoding info through HKDF (i.e. making it cryptographically stronger).

Context #

The "context" is a set of bytes that is used to calculate two values later on in the encryption browser. It's essentially an array of bytes containing the subscription public key and the local public key.

const keyLabel = new Buffer('P-256\0', 'utf8');

// Convert subscription public key into a buffer.
const subscriptionPubKey = new Buffer(subscription.keys.p256dh, 'base64');

const subscriptionPubKeyLength = new Uint8Array(2);
subscriptionPubKeyLength[0] = 0;
subscriptionPubKeyLength[1] = subscriptionPubKey.length;

const localPublicKeyLength = new Uint8Array(2);
subscriptionPubKeyLength[0] = 0;
subscriptionPubKeyLength[1] = localPublicKey.length;

const contextBuffer = Buffer.concat([
  keyLabel,
  subscriptionPubKeyLength.buffer,
  subscriptionPubKey,
  localPublicKeyLength.buffer,
  localPublicKey,
]);

The final context buffer is a label, the number of bytes in the subscription public key, followed by the key itself, then the number of bytes local public key, followed by the key itself.

With this context value we can use it in the creation of a nonce and a content encryption key (CEK).

Content encryption key and nonce #

A nonce is a value that prevents replay attacks as it should only be used once.

The content encryption key (CEK) is the key that will ultimately be used to encrypt our payload.

First we need to create the bytes of data for the nonce and CEK, which is simply a content encoding string followed by the context buffer we just calculated:

const nonceEncBuffer = new Buffer('Content-Encoding: nonce\0', 'utf8');
const nonceInfo = Buffer.concat([nonceEncBuffer, contextBuffer]);

const cekEncBuffer = new Buffer('Content-Encoding: aesgcm\0');
const cekInfo = Buffer.concat([cekEncBuffer, contextBuffer]);

This information is run through HKDF combining the salt and PRK with the nonceInfo and cekInfo:

// The nonce should be 12 bytes long
const nonce = hkdf(salt, prk, nonceInfo, 12);

// The CEK should be 16 bytes long
const contentEncryptionKey = hkdf(salt, prk, cekInfo, 16);

This gives us our nonce and content encryption key.

Perform the encryption #

Now that we have our content encryption key, we can encrypt the payload.

We create an AES128 cipher using the content encryption key as the key and the nonce is an initialization vector.

In Node this is done like so:

const cipher = crypto.createCipheriv(
  'id-aes128-GCM',
  contentEncryptionKey,
  nonce,
);

Before we encrypt our payload, we need to define how much padding we wish to add to the front of the payload. The reason we'd want to add padding is that it prevents the risk of eavesdroppers being able to determine "types" of messages based on the payload size.

You must add two bytes of padding to indicate the length of any additional padding.

For example, if you added no padding, you'd have two bytes with value 0, i.e. no padding exists, after these two bytes you'll be reading the payload. If you added 5 bytes of padding, the first two bytes will have a value of 5, so the consumer will then read an additional five bytes and then start reading the payload.

const padding = new Buffer(2 + paddingLength);
// The buffer must be only zeros, except the length
padding.fill(0);
padding.writeUInt16BE(paddingLength, 0);

We then run our padding and payload through this cipher.

const result = cipher.update(Buffer.concat(padding, payload));
cipher.final();

// Append the auth tag to the result -
// https://nodejs.org/api/crypto.html#crypto_cipher_getauthtag
const encryptedPayload = Buffer.concat([result, cipher.getAuthTag()]);

We now have our encrypted payload. Yay!

All that remains is to determine how this payload is sent to the push service.

Encrypted payload headers & body #

To send this encrypted payload to the push service we need to define a few different headers in our POST request.

Encryption header #

The 'Encryption' header must contain the salt used for encrypting the payload.

The 16 byte salt should be base64 URL safe encoded and added to the Encryption header, like so:

Encryption: salt=[URL Safe Base64 Encoded Salt]

Crypto-Key header #

We saw that the Crypto-Key header is used under the 'Application Server Keys' section to contain the public application server key.

This header is also used to share the local public key used to encrypt the payload.

The resulting header looks like this:

Crypto-Key: dh=[URL Safe Base64 Encoded Local Public Key String]; p256ecdsa=[URL Safe Base64 Encoded Public Application Server Key]

Content type, length & encoding headers #

The Content-Length header is the number of bytes in the encrypted payload. 'Content-Type' and 'Content-Encoding' headers are fixed values. This is shown below.

Content-Length: [Number of Bytes in Encrypted Payload]
Content-Type: 'application/octet-stream'
Content-Encoding: 'aesgcm'

With these headers set, we need to send the encrypted payload as the body of our request. Notice that the Content-Type is set to application/octet-stream. This is because the encrypted payload must be sent as a stream of bytes.

In NodeJS we would do this like so:

const pushRequest = https.request(httpsOptions, function(pushResponse) {
pushRequest.write(encryptedPayload);
pushRequest.end();

More headers? #

We've covered the headers used for JWT / Application Server Keys (i.e. how to identify the application with the push service) and we've covered the headers used to send an encrypted payload.

There are additional headers that push services use to alter the behavior of sent messages. Some of these headers are required, while others are optional.

TTL header #

Required

TTL (or time to live) is an integer specifying the number of seconds you want your push message to live on the push service before it's delivered. When the TTL expires, the message will be removed from the push service queue and it won't be delivered.

TTL: [Time to live in seconds]

If you set a TTL of zero, the push service will attempt to deliver the message immediately, but if the device can't be reached, your message will be immediately dropped from the push service queue.

Technically a push service can reduce the TTL of a push message if it wants. You can tell if this has happened by examining the TTL header in the response from a push service.

Topic #

Optional

Topics are strings that can be used to replace a pending messages with a new message if they have matching topic names.

This is useful in scenarios where multiple messages are sent while a device is offline, and you really only want a user to see the latest message when the device is turned on.

Urgency #

Optional

Urgency indicates to the push service how important a message is to the user. This can be used by the push service to help conserve the battery life of a user's device by only waking up for important messages when battery is low.

The header value is defined as shown below. The default value is normal.

Urgency: [very-low | low | normal | high]

Everything together #

If you have further questions about how this all works you can always see how libraries trigger push messages on the web-push-libs org.

Once you have an encrypted payload, and the headers above, you just need to make a POST request to the endpoint in a PushSubscription.

So what do we do with the response to this POST request?

Response from push service #

Once you've made a request to a push service, you need to check the status code of the response as that'll tell you whether the request was successful or not.

Status Code	Description
201	Created. The request to send a push message was received and accepted.
429	Too many requests. Meaning your application server has reached a rate limit with a push service. The push service should include a 'Retry-After' header to indicate how long before another request can be made.
400	Invalid request. This generally means one of your headers is invalid or improperly formatted.
404	Not Found. This is an indication that the subscription is expired and can't be used. In this case you should delete the `PushSubscription` and wait for the client to resubscribe the user.
410	Gone. The subscription is no longer valid and should be removed from application server. This can be reproduced by calling `unsubscribe()` on a `PushSubscription`.
413	Payload size too large. The minimum size payload a push service must support is 4096 bytes (or 4kb).

Where to go next #

Code labs #

Common notification patterns

2016-06-30T00:00:00Z

We're going to look at some common implementation patterns for web push.

This will involve using a few different APIs that are available in the service worker.

Notification close event #

In the last section we saw how we can listen for notificationclick events.

There is also a notificationclose event that is called if the user dismisses one of your notifications (i.e. rather than clicking the notification, the user clicks the cross or swipes the notification away).

This event is normally used for analytics to track user engagement with notifications.

self.addEventListener('notificationclose', function (event) {
  const dismissedNotification = event.notification;

  const promiseChain = notificationCloseAnalytics();
  event.waitUntil(promiseChain);
});

Adding data to a notification #

When a push message is received it's common to have data that is only useful if the user has clicked the notification. For example, the URL that should be opened when a notification is clicked.

The easiest way to take data from a push event and attach it to a notification is to add a data parameter to the options object passed into showNotification(), like so:

const options = {
  body:
    'This notification has data attached to it that is printed ' +
    "to the console when it's clicked.",
  tag: 'data-notification',
  data: {
    time: new Date(Date.now()).toString(),
    message: 'Hello, World!',
  },
};
registration.showNotification('Notification with Data', options);

Inside a click handler, the data can be accessed with event.notification.data.

const notificationData = event.notification.data;
console.log('');
console.log('The notification data has the following parameters:');
Object.keys(notificationData).forEach((key) => {
  console.log(`  ${key}: ${notificationData[key]}`);
});
console.log('');

Open a window #

One of the most common responses to a notification is to open a window / tab to a specific URL. We can do this with the clients.openWindow() API.

In our notificationclick event, we'd run some code like this:

const examplePage = '/demos/notification-examples/example-page.html';
const promiseChain = clients.openWindow(examplePage);
event.waitUntil(promiseChain);

In the next section, we'll look at how to check if the page we want to direct the user to is already open or not. This way, we can focus the open tab rather than opening new tabs.

Focus an existing window #

When it's possible, we should focus a window rather than open a new window every time the user clicks a notification.

Before we look at how to achieve this, it's worth highlighting that this is only possible for pages on your origin. This is because we can only see what pages are open that belong to our site. This prevents developers from being able to see all the sites their users are viewing.

Taking the previous example, we'll alter the code to see if /demos/notification-examples/example-page.html is already open.

const urlToOpen = new URL(examplePage, self.location.origin).href;

const promiseChain = clients
  .matchAll({
    type: 'window',
    includeUncontrolled: true,
  })
  .then((windowClients) => {
    let matchingClient = null;

    for (let i = 0; i < windowClients.length; i++) {
      const windowClient = windowClients[i];
      if (windowClient.url === urlToOpen) {
        matchingClient = windowClient;
        break;
      }
    }

    if (matchingClient) {
      return matchingClient.focus();
    } else {
      return clients.openWindow(urlToOpen);
    }
  });

event.waitUntil(promiseChain);

Let's step through the code.

First we parse our example page using the URL API. This is a neat trick I picked up from Jeff Posnick. Calling new URL() with the location object will return an absolute URL if the string passed in is relative (i.e. / will become https://example.com/).

We make the URL absolute so we can match it against window URL's later on.

const urlToOpen = new URL(examplePage, self.location.origin).href;

Then we get a list of the WindowClient objects, which is the list of the currently open tabs and windows. (Remember these are tabs for your origin only.)

const promiseChain = clients.matchAll({
  type: 'window',
  includeUncontrolled: true,
});

The options passed into matchAll inform the browser that we only want to search for "window" type clients (i.e. just look for tabs and windows and exclude web workers). includeUncontrolled allows us to search for all tabs from your origin that are not controlled by the current service worker, i.e. the service worker running this code. Generally, you'll always want includeUncontrolled to be true when calling matchAll().

We capture the returned promise as promiseChain so that we can pass it into event.waitUntil() later on, keeping our service worker alive.

When the matchAll() promise resolves, we iterate through the returned window clients and compare their URLs to the URL we want to open. If we find a match, we focus that client, which will bring that window to the users attention. Focusing is done with the matchingClient.focus() call.

If we can't find a matching client, we open a new window, same as in the previous section.

.then((windowClients) => {
  let matchingClient = null;

  for (let i = 0; i < windowClients.length; i++) {
    const windowClient = windowClients[i];
    if (windowClient.url === urlToOpen) {
      matchingClient = windowClient;
      break;
    }
  }

  if (matchingClient) {
    return matchingClient.focus();
  } else {
    return clients.openWindow(urlToOpen);
  }
});

Merging notifications #

We saw that adding a tag to a notification opts in to a behavior where any existing notification with the same tag is replaced.

You can however get more sophisticated with the collapsing of notifications using the Notifications API. Consider a chat app, where the developer might want a new notification to show a message similar to "You have two messages from Matt" rather than just showing the latest message.

You can do this, or manipulate current notifications in other ways, using the registration.getNotifications() API which gives you access to all the currently visible notifications for your web app.

Let's look at how we could use this API to implement the chat example.

In our chat app, let's assume each notification has some data which includes a username.

The first thing we'll want to do is find any open notifications for a user with a specific username. We'll get registration.getNotifications() and loop over them and check the notification.data for a specific username:

const promiseChain = registration.getNotifications().then((notifications) => {
  let currentNotification;

  for (let i = 0; i < notifications.length; i++) {
    if (notifications[i].data && notifications[i].data.userName === userName) {
      currentNotification = notifications[i];
    }
  }

  return currentNotification;
});

The next step is to replace this notification with a new notification.

In this fake message app, we'll track the number of new messages by adding a count to our new notification's data and increment it with each new notification.

.then((currentNotification) => {
  let notificationTitle;
  const options = {
    icon: userIcon,
  }

  if (currentNotification) {
    // We have an open notification, let's do something with it.
    const messageCount = currentNotification.data.newMessageCount + 1;

    options.body = `You have ${messageCount} new messages from ${userName}.`;
    options.data = {
      userName: userName,
      newMessageCount: messageCount
    };
    notificationTitle = `New Messages from ${userName}`;

    // Remember to close the old notification.
    currentNotification.close();
  } else {
    options.body = `"${userMessage}"`;
    options.data = {
      userName: userName,
      newMessageCount: 1
    };
    notificationTitle = `New Message from ${userName}`;
  }

  return registration.showNotification(
    notificationTitle,
    options
  );
});

If there is a notification currently displayed, we increment the message count and set the notification title and body message accordingly. If there are no notifications, we create a new notification with a newMessageCount of 1.

The result is that the first message would look like this:

A second notification would collapse the notifications into this:

The nice thing with this approach is that if your user witnesses the notifications appearing one over the other, it'll look and feel more cohesive than just replacing the notification with the latest message.

The exception to the rule #

I've been stating that you must show a notification when you receive a push and this is true most of the time. The one scenario where you don't have to show a notification is when the user has your site open and focused.

Inside your push event, you can check whether you need to show a notification or not by examining the window clients and looking for a focused window.

The code to getting all the windows and looking for a focused window looks like this:

function isClientFocused() {
  return clients
    .matchAll({
      type: 'window',
      includeUncontrolled: true,
    })
    .then((windowClients) => {
      let clientIsFocused = false;

      for (let i = 0; i < windowClients.length; i++) {
        const windowClient = windowClients[i];
        if (windowClient.focused) {
          clientIsFocused = true;
          break;
        }
      }

      return clientIsFocused;
    });
}

We use clients.matchAll() to get all of our window clients and then we loop over them checking the focused parameter.

Inside our push event, we'd use this function to decide if we need to show a notification:

const promiseChain = isClientFocused().then((clientIsFocused) => {
  if (clientIsFocused) {
    console.log("Don't need to show a notification.");
    return;
  }

  // Client isn't focused, we need to show a notification.
  return self.registration.showNotification('Had to show a notification.');
});

event.waitUntil(promiseChain);

Message a page from a push event #

We've seen that you can skip showing a notification if the user is currently on your site. But what if you still want to let the user know that an event has occurred, but a notification is too heavy handed?

One approach is to send a message from the service worker to the page, this way the web page can show a notification or an update to the user, informing them of the event. This is useful for situations when a subtle notification in the page is better and friendlier for the user.

Let's say we've received a push, checked that our web app is currently focused, then we can "post a message" to each open page, like so:

const promiseChain = isClientFocused().then((clientIsFocused) => {
  if (clientIsFocused) {
    windowClients.forEach((windowClient) => {
      windowClient.postMessage({
        message: 'Received a push message.',
        time: new Date().toString(),
      });
    });
  } else {
    return self.registration.showNotification('No focused windows', {
      body: 'Had to show a notification instead of messaging each page.',
    });
  }
});

event.waitUntil(promiseChain);

In each of the pages, we listen for messages by adding a message event listener:

navigator.serviceWorker.addEventListener('message', function (event) {
  console.log('Received a message from service worker: ', event.data);
});

In this message listener, you could do anything you want, show a custom UI on your page or completely ignore the message.

It's also worth noting that if you don't define a message listener in your web page, the messages from the service worker will not do anything.

Cache a page and open a window #

One scenario that is out of the scope of this guide but worth discussing is that you can improve the overall UX of your web app by caching web pages you expect users to visit after clicking on your notification.

This requires having your service worker set-up to handle fetch events, but if you implement a fetch event listener, make sure you take advantage of it in your push event by caching the page and assets you'll need before showing your notification.

Browser compatibility #

The `notificationclose` event #

Browser support

Chrome 50, Supported 50
Firefox 44, Supported 44
Edge 17, Supported 17
Safari 16, Supported 16

Source

`Clients.openWindow()` #

Browser support

Chrome 40, Supported 40
Firefox 44, Supported 44
Edge 17, Supported 17
Safari 11.1, Supported 11.1

Source

`ServiceWorkerRegistration.getNotifications()` #

Browser support

Chrome 40, Supported 40
Firefox 44, Supported 44
Edge 17, Supported 17
Safari 16, Supported 16

Source

`clients.matchAll()` #

Browser support

Chrome 42, Supported 42
Firefox 54, Supported 54
Edge 17, Supported 17
Safari 11.1, Supported 11.1

Source

For more information, check out this introduction to service workers post.

Where to go next #

Web Push Notification Overview
How Push Works
Subscribing a User
Permission UX
Sending Messages with Web Push Libraries
Web Push Protocol
Handling Push Events
Displaying a Notification
Notification Behavior
Common Notification Patterns
Push Notifications FAQ
Common Issues and Reporting Bugs

Code labs #

Push events

2016-06-30T00:00:00Z

By this point, we covered subscribing a user and sending a push message. The next step is to receive this push message on the user's device and display a notification (as well as do any other work we might want to do).

The Push Event #

When a message is received, it'll result in a push event being dispatched in your service worker.

The code for setting up a push event listener should be pretty similar to any other event listener you'd write in JavaScript:

self.addEventListener('push', function(event) {
    if (event.data) {
    console.log('This push event has data: ', event.data.text());
    } else {
    console.log('This push event has no data.');
    }
});

The weirdest bit of this code to most developers who are new to service workers is the self variable. self is commonly used in Web Workers, which a service worker is. self refers to the global scope, kind of like window in a web page. But for web workers and service workers, self refers to the worker itself.

In the example above, self.addEventListener() can be thought of as adding an event listener to the service worker itself.

Inside the push event example, we check if there is any data and print something to the console.

There are other ways you can parse data from a push event:

// Returns string
event.data.text()

// Parses data as JSON string and returns an Object
event.data.json()

// Returns blob of data
event.data.blob()

// Returns an arrayBuffer
event.data.arrayBuffer()

Most people use json() or text() depending on what they are expecting from their application.

This example demonstrates how to add a push event listener and how to access data, but it's missing two very important pieces of functionality. It's not showing a notification and it's not making use of event.waitUntil().

Wait Until #

One of the things to understand about service workers is that you have little control over when the service worker code is going to run. The browser decides when to wake it up and when to terminate it. The only way you can tell the browser, "Hey, I'm super busy doing important stuff", is to pass a promise into the event.waitUntil() method. With this, the browser will keep the service worker running until the promise you passed in has settled.

With push events, there is an additional requirement that you must display a notification before the promise you passed in has settled.

Here's a basic example of showing a notification:

self.addEventListener('push', function(event) {
    const promiseChain = self.registration.showNotification('Hello, World.');

    event.waitUntil(promiseChain);
});

Calling self.registration.showNotification() is the method that displays a notification to the user and it returns a promise that will resolve once the notification has been displayed.

For the sake of keeping this example as clear as possible, I've assigned this promise to a variable called promiseChain. This is then passed into event.waitUntil(). I know this is very verbose, but I've seen a number of issues that have culminated as a result of misunderstanding what should be passed into waitUntil() or as a result of broken promise chains.

A more complicated example with a network request for data and tracking the push event with analytics could look like this:

self.addEventListener('push', function(event) {
    const analyticsPromise = pushReceivedTracking();
    const pushInfoPromise = fetch('/api/get-more-data')
    .then(function(response) {
        return response.json();
    })
    .then(function(response) {
        const title = response.data.userName + ' says...';
        const message = response.data.message;

        return self.registration.showNotification(title, {
        body: message
        });
    });

    const promiseChain = Promise.all([
    analyticsPromise,
    pushInfoPromise
    ]);

    event.waitUntil(promiseChain);
});

Here we are calling a function that returns a promise pushReceivedTracking(), which, for the sake of the example, we can pretend will make a network request to our analytics provider. We are also making a network request, getting the response and showing a notification using the responses data for the title and message of the notification.

We can ensure the service worker is kept alive while both of these tasks are done by combining these promises with Promise.all(). The resulting promise is passed into event.waitUntil() meaning the browser will wait until both promises have finished before checking that a notification has been displayed and terminating the service worker.

The reason we should be concerned about waitUntil() and how to use it is that one of the most common issues developers face is that when the promise chain is incorrect / broken, Chrome will show this "default" notification:

Chrome will only show the "This site has been updated in the background." notification when a push message is received and the push event in the service worker does not show a notification after the promise passed to event.waitUntil() has finished.

The main reason developers get caught by this is that their code will often call self.registration.showNotification() but they aren't doing anything with the promise it returns. This intermittently results in the default notification being displayed. For example, we could remove the return for self.registration.showNotification() in the example above and we run the risk of seeing this notification.

self.addEventListener('push', function(event) {
    const analyticsPromise = pushReceivedTracking();
    const pushInfoPromise = fetch('/api/get-more-data')
    .then(function(response) {
        return response.json();
    })
    .then(function(response) {
        const title = response.data.userName + ' says...';
        const message = response.data.message;

        self.registration.showNotification(title, {
        body: message
        });
    });

    const promiseChain = Promise.all([
    analyticsPromise,
    pushInfoPromise
    ]);

    event.waitUntil(promiseChain);
});

You can see how it's an easy thing to miss.

Just remember - if you see that notification, check your promise chains and event.waitUntil().

In the next section, we're going to look at what we can do to style notifications and what content we can display.

Where to go next #

Code labs #

Permission UX

2016-06-30T00:00:00Z

The natural step after getting a PushSubscription and saving it our server is to trigger a push message, but there is one thing I flagrantly glossed over. The user experience when asking for permission from the user to send them push messages.

Sadly, very few sites give much consideration to how they ask their user for permission, so let's take a brief aside to look at both good and bad UX.

Common patterns #

There have been a few common patterns emerging that should guide and help you when deciding what is best for your users and use case.

Value proposition #

Ask users to subscribe to push at a time when the benefit is obvious.

For example, a user has just bought an item on an online store and finished the checkout flow. The site can then offer updates on the delivery status.

There are a range of situations where this approach works:

A particular item is out of stock, would you like to be notified when it's next available?
This breaking news story will be regularly updated, would you like to be notified as the story develops?
You're the highest bidder, would you like to be notified if you are outbid?

These are all points where the user has invested in your service and there is a clear value proposition for them to enable push notifications.

created a mock of a hypothetical airline website to demonstrate this approach.

After the user has booked a flight it asks if the user would like notifications of flight delays.

Note that this is a custom UI from the website.

Another nice touch to Owen's demo is that if the user clicks to enable notifications, the site adds a semi-transparent overlay on the entire page when it shows the permission prompt. This draws the users attention to the permission prompt.

The alternative to this example, the bad UX for asking permission, is to request permission as soon as a user lands on the airline's site.

This approach provides no context as to why notifications are needed or useful to the user. The user is also blocked from achieving their original task (i.e. book a flight) by this permission prompt.

Double Permission #

You may feel that your site has a clear use case for push messaging and as a result want to ask the user for permission as soon as possible.

For example instant messaging and email clients. Showing a message for a new message or email is an established user experience across a range of platforms.

For these category of apps, it's worth considering the double permission pattern.

First show a fake permission prompt that your website controls, consisting of buttons to allow or ignore the permission request. If the user clicks allow, request permission, triggering the real browser permission prompt.

With this approach you display a custom permission prompt in your web app which asks the user to enable notifications. By doing this the user can chose enable or disable without your website running the risk of being permanently blocked. If the user selects enable on the custom UI, display the actual permission prompt, otherwise hide your custom pop-up and ask some other time.

A good example of this is . They show a prompt at the top of their page once you've signed in asking if you'd like to enable notifications.

Settings Panel #

You can move notifications into a settings panel, giving users an easy way to enable and disable push messaging, without the need of cluttering your web app's UI.

A good example of this is . When you first load up the Google I/O site, you aren't asked to do anything, the user is left to explore the site.

After a few visits, clicking the menu item on the right reveals a settings panel allowing the user to set up and manage notifications.

Clicking on the checkbox displays the permission prompt. No hidden surprises.

After the permission has been granted, the checkbox is checked and the user is good to go. The great thing about this UI is that users can enable and disable notifications from one location on the website.

Passive approach #

One of the easiest ways to offer push to a user is to have a button or toggle switch that enables / disables push messages in a location on the page that is consistent throughout a site.

This doesn't drive users to enable push notifications, but offers a reliable and easy way for users to opt in and out of engaging with your website. For sites like blogs that might have some regular viewers as well as high bounce rates, this is a solid option as it targets regular viewers without annoying drive-by visitors.

On my personal site, I have a toggle switch for push messaging in the footer.

It's fairly out of the way, but for regular visitors it should get enough attention from readers wanting to get updates. One-time visitors are completely unaffected.

If the user subscribes to push messaging, the state of the toggle switch changes and maintains state throughout the site.

The bad UX #

Those are some of the common practices I've noticed on the web. Sadly, there is one very common bad practice.

The worst thing you can do is to show the permission dialog to users as soon as they land on your site.

They have zero context on why they are being asked for a permission, they may not even know what your website is for, what it does or what it offers. Blocking permissions at this point out of frustration is not uncommon, this pop-up is getting in the way of what they are trying to do.

Remember, if the user blocks the permission request, your web app can't ask for permission again. To get permission after being blocked, the user has to change the permission in the browser's UI and doing so is not easy, obvious or fun for the user.

No matter what, don't ask for permission as soon as the user opens your site, consider some other UI or approach that has an incentive for the user to grant permission.

Offer a way out #

In addition to considering the UX to subscribe a user to push, please consider how a user should unsubscribe or opt out of push messaging.

The number of sites that ask for permission as soon as the page loads and then offer no UI for disabling push notifications is astounding.

Your site should explain to your users how they can disable push. If you don't, users are likely to take the nuclear option and block permission permanently.

Where to go next #

Code labs #

Sending messages with web push libraries

2016-06-30T00:00:00Z

One of the pain points when working with web push is that triggering a push message is extremely "fiddly". To trigger a push message an application needs to make a POST request to a push service following the web push protocol. To use push across all browsers you need to use VAPID (a.k.a. application server keys) which basically requires setting a header with a value proving your application can message a user. To send data with a push message, the data needs to be encrypted and specific headers need to be added so the browser can decrypt the message correctly.

The main issue with triggering push is that if you hit a problem, it's difficult to diagnose the issue. This is improving with time and wider browser support but it's far from easy. For this reason, I strongly recommend using a library to handle the encryption, formatting and triggering of your push message.

If you really want to learn about what the libraries are doing, we'll cover it in the next section. For now, we are going to look at managing subscriptions and using an existing web push library to make the push requests.

In this section we'll be using the web-push Node library. Other languages will have differences, but they won't be too dissimilar. We are looking at Node since it's JavaScript and should be the most accessible for readers.

We'll go through the following steps:

Send a subscription to our backend and save it.
Retrieve saved subscriptions and trigger a push message.

Saving subscriptions #

Saving and querying PushSubscription's from a database will vary depending on your server side language and database choice, but it might be useful to see an example of how it could be done.

In the demo web page, the PushSubscription is sent to our backend by making a simple POST request:

function sendSubscriptionToBackEnd(subscription) {
  return fetch('/api/save-subscription/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(subscription),
  })
    .then(function (response) {
      if (!response.ok) {
        throw new Error('Bad status code from server.');
      }

      return response.json();
    })
    .then(function (responseData) {
      if (!(responseData.data && responseData.data.success)) {
        throw new Error('Bad response from server.');
      }
    });
}

The Express server in our demo has a matching request listener for the /api/save-subscription/ endpoint:

app.post('/api/save-subscription/', function (req, res) {

In this route we validate the subscription just to make sure the request is OK and not full of garbage:

const isValidSaveRequest = (req, res) => {
  // Check the request body has at least an endpoint.
  if (!req.body || !req.body.endpoint) {
    // Not a valid subscription.
    res.status(400);
    res.setHeader('Content-Type', 'application/json');
    res.send(
      JSON.stringify({
        error: {
          id: 'no-endpoint',
          message: 'Subscription must have an endpoint.',
        },
      }),
    );
    return false;
  }
  return true;
};

If the subscription is valid, we need to save it and return an appropriate JSON response:

return saveSubscriptionToDatabase(req.body)
  .then(function (subscriptionId) {
    res.setHeader('Content-Type', 'application/json');
    res.send(JSON.stringify({data: {success: true}}));
  })
  .catch(function (err) {
    res.status(500);
    res.setHeader('Content-Type', 'application/json');
    res.send(
      JSON.stringify({
        error: {
          id: 'unable-to-save-subscription',
          message:
            'The subscription was received but we were unable to save it to our database.',
        },
      }),
    );
  });

This demo uses nedb to store the subscriptions, it's a simple file based database, but you could use any database of your choice. We are only using this as it requires zero set-up. For production you'd want to use something more reliable. (I tend to stick with good old MySQL.)

function saveSubscriptionToDatabase(subscription) {
  return new Promise(function (resolve, reject) {
    db.insert(subscription, function (err, newDoc) {
      if (err) {
        reject(err);
        return;
      }

      resolve(newDoc._id);
    });
  });
}

Sending push messages #

When it comes to sending a push message, we ultimately need some event to trigger the process of sending a message to users. A common approach is creating an admin page that let's you configure and trigger the push message. But you could create a program to run locally or any other approach that allows accessing the list of PushSubscription's and running the code to trigger the push message.

Our demo has an "admin like" page that lets you trigger a push. Since it's just a demo it's a public page.

I'm going to go through each step involved in getting the demo working. These will be baby steps so everyone can follow along, including anyone who is new to Node.

When we discussed subscribing a user, we covered adding an applicationServerKey to the subscribe() options. It's on the back end that we'll need this private key.

In the demo, these values are added to our Node app like so (boring code I know, but just want you to know there is no magic):

const vapidKeys = {
  publicKey:
    'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
  privateKey: 'UUxI4O8-FbRouAevSmBQ6o18hgE4nSG3qwvJTfKc-ls',
};

Next we need to install the web-push module for our Node server:

npm install web-push --save

Then, in our Node script we require the web-push module like so:

const webpush = require('web-push');

Now we can start to use the web-push module. First we need to tell the web-push module about our application server keys. (Remember they are also known as VAPID keys because that's the name of the spec.)

const vapidKeys = {
  publicKey:
    'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
  privateKey: 'UUxI4O8-FbRouAevSmBQ6o18hgE4nSG3qwvJTfKc-ls',
};

webpush.setVapidDetails(
  'mailto:web-push-book@gauntface.com',
  vapidKeys.publicKey,
  vapidKeys.privateKey,
);

Note that we also included a "mailto:" string. This string needs to be either a URL or a mailto email address. This piece of information will actually be sent to the web push service as part of the request to trigger a push. The reason this is done is so that if a web push service needs to get in touch with the sender, they have some information that will enable them to.

With this, the web-push module is ready to use, the next step is to trigger a push message.

The demo uses the pretend admin panel to trigger push messages.

Clicking the "Trigger Push Message" button will make a POST request to /api/trigger-push-msg/, which is the signal for our backend to send push messages, so we create the route in express for this endpoint:

app.post('/api/trigger-push-msg/', function (req, res) {

When this request is received, we grab the subscriptions from the database and for each one, we trigger a push message.

return getSubscriptionsFromDatabase().then(function (subscriptions) {
  let promiseChain = Promise.resolve();

  for (let i = 0; i < subscriptions.length; i++) {
    const subscription = subscriptions[i];
    promiseChain = promiseChain.then(() => {
      return triggerPushMsg(subscription, dataToSend);
    });
  }

  return promiseChain;
});

The function triggerPushMsg() can then use the web-push library to send a message to the provided subscription.

const triggerPushMsg = function (subscription, dataToSend) {
  return webpush.sendNotification(subscription, dataToSend).catch((err) => {
    if (err.statusCode === 404 || err.statusCode === 410) {
      console.log('Subscription has expired or is no longer valid: ', err);
      return deleteSubscriptionFromDatabase(subscription._id);
    } else {
      throw err;
    }
  });
};

The call to webpush.sendNotification() will return a promise. If the message was sent successfully the promise will resolve and there is nothing we need to do. If the promise rejects, you need to examine the error as it'll inform you as to whether the PushSubscription is still valid or not.

To determine the type of error from a push service it's best to look at the status code. Error messages vary between push services and some are more helpful than others.

In this example, it checks for status codes 404 and 410, which are the HTTP status codes for 'Not Found' and 'Gone'. If we receive one of these, it means the subscription has expired or is no longer valid. In these scenarios, we need to remove the subscriptions from our database.

In case of some other error, we just throw err, which will make the promise returned by triggerPushMsg() reject.

We'll cover some of the other status codes in the next section when we look at the web push protocol in more detail.

After looping through the subscriptions, we need to return a JSON response.

.then(() => {
res.setHeader('Content-Type', 'application/json');
    res.send(JSON.stringify({ data: { success: true } }));
})
.catch(function(err) {
res.status(500);
res.setHeader('Content-Type', 'application/json');
res.send(JSON.stringify({
    error: {
    id: 'unable-to-send-messages',
    message: `We were unable to send messages to all subscriptions : ` +
        `'${err.message}'`
    }
}));
});

We've gone over the major implementation steps:

Create an API to send subscriptions from our web page to our back-end so it can save them to a database.
Create an API to trigger the sending of push messages (in this case, an API called from the pretended admin panel).
Retrieve all the subscriptions from our backend and send a message to each subscription with one of the web-push libraries.

Regardless of your backend (Node, PHP, Python, …), the steps for implementing push are going to be the same.

Next up, what exactly are these web-push libraries doing for us?

Where to go next #

Web Push Notification Overview
How Push Works
Subscribing a User
Permission UX
Sending Messages with Web Push Libraries
Web Push Protocol
Handling Push Events
Displaying a Notification
Notification Behavior
Common Notification Patterns
Push Notifications FAQ
Common Issues and Reporting Bugs

Code labs #

Subscribing a User

2016-06-30T00:00:00Z

The first step is to get permission from the user to send them push messages and then we can get our hands on a PushSubscription.

The JavaScript API to do this is reasonably straight forward, so let's step through the logic flow.

Feature detection #

First we need to check if the current browser actually supports push messaging. We can check if push is supported with two simple checks.

Check for serviceWorker on navigator.
Check for PushManager on window.

if (!('serviceWorker' in navigator)) {
  // Service Worker isn't supported on this browser, disable or hide UI.
  return;
}

if (!('PushManager' in window)) {
  // Push isn't supported on this browser, disable or hide UI.
  return;
}

While browser support is growing quickly for both service worker and push messaging, it's always a good idea to feature detect for both and progressively enhance.

Register a service worker #

With the feature detect we know that both service workers and Push are supported. The next step is to "register" our service worker.

When we register a service worker, we are telling the browser where our service worker file is. The file is still just JavaScript, but the browser will "give it access" to the service worker APIs, including push. To be more exact, the browser runs the file in a service worker environment.

To register a service worker, call navigator.serviceWorker.register(), passing in the path to our file. Like so:

function registerServiceWorker() {
  return navigator.serviceWorker
    .register('/service-worker.js')
    .then(function (registration) {
      console.log('Service worker successfully registered.');
      return registration;
    })
    .catch(function (err) {
      console.error('Unable to register service worker.', err);
    });
}

This function tells the browser that we have a service worker file and where it's located. In this case, the service worker file is at /service-worker.js. Behind the scenes the browser will take the following steps after calling register():

Download the service worker file.
Run the JavaScript.
If everything runs correctly and there are no errors, the promise returned by register() will resolve. If there are errors of any kind, the promise will reject.

If register() does reject, double check your JavaScript for typos / errors in Chrome DevTools.

When register() does resolve, it returns a ServiceWorkerRegistration. We'll use this registration to access the PushManager API.

PushManager API browser compatibility #

Browser support

Chrome 42, Supported 42
Firefox 44, Supported 44
Edge 17, Supported 17
Safari 16, Supported 16

Source

Requesting permission #

We've registered our service worker and are ready to subscribe the user, the next step is to get permission from the user to send them push messages.

The API for getting permission is relatively simple, the downside is that the API recently changed from taking a callback to returning a Promise. The problem with this, is that we can't tell what version of the API is implemented by the current browser, so you have to implement both and handle both.

function askPermission() {
  return new Promise(function (resolve, reject) {
    const permissionResult = Notification.requestPermission(function (result) {
      resolve(result);
    });

    if (permissionResult) {
      permissionResult.then(resolve, reject);
    }
  }).then(function (permissionResult) {
    if (permissionResult !== 'granted') {
      throw new Error("We weren't granted permission.");
    }
  });
}

In the above code, the important snippet of code is the call to Notification.requestPermission(). This method will display a prompt to the user:

Once the user interacted with the permission prompt by pressing Allow, Block, or just closing it, we'll be given the result as a string: 'granted', 'default' or 'denied'.

In the sample code above, the promise returned by askPermission() resolves if the permission is granted, otherwise we throw an error making the promise reject.

One edge case that you need to handle is if the user clicks the 'Block' button. If this happens, your web app will not be able to ask the user for permission again. They'll have to manually "unblock" your app by changing its permission state, which is buried in a settings panel. Think carefully about how and when you ask the user for permission, because if they click block, it's not an easy way to reverse that decision.

The good news is that most users are happy to give permission as long as they know why the permission is being asked.

We'll look at how some popular sites ask for permission later on.

Once we have our service worker registered and we've got permission, we can subscribe a user by calling registration.pushManager.subscribe().

function subscribeUserToPush() {
  return navigator.serviceWorker
    .register('/service-worker.js')
    .then(function (registration) {
      const subscribeOptions = {
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(
          'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
        ),
      };

      return registration.pushManager.subscribe(subscribeOptions);
    })
    .then(function (pushSubscription) {
      console.log(
        'Received PushSubscription: ',
        JSON.stringify(pushSubscription),
      );
      return pushSubscription;
    });
}

When calling the subscribe() method, we pass in an options object, which consists of both required and optional parameters.

Lets look at all the options we can pass in.

userVisibleOnly options #

When push was first added to browsers, there was uncertainty about whether developers should be able to send a push message and not show a notification. This is commonly referred to as silent push, due to the user not knowing that something had happened in the background.

The concern was that developers could do nasty things like track a user's location on an ongoing basis without the user knowing.

To avoid this scenario and to give spec authors time to consider how best to support this feature, the userVisibleOnly option was added and passing in a value of true is a symbolic agreement with the browser that the web app will show a notification every time a push is received (i.e. no silent push).

At the moment you must pass in a value of true. If you don't include the userVisibleOnly key or pass in false you'll get the following error:

Chrome currently only supports the Push API for subscriptions that will result in user-visible messages. You can indicate this by calling pushManager.subscribe({userVisibleOnly: true}) instead. See https://goo.gl/yqv4Q4 for more details.

It's currently looking like blanket silent push will never be implemented in Chrome. Instead, spec authors are exploring the notion of a budget API which will allow web apps a certain number of silent push messages based on the usage of a web app.

applicationServerKey option #

We briefly mentioned "application server keys" in the previous section. "Application server keys" are used by a push service to identify the application subscribing a user and ensure that the same application is messaging that user.

Application server keys are a public and private key pair that are unique to your application. The private key should be kept a secret to your application and the public key can be shared freely.

The applicationServerKey option passed into the subscribe() call is the application's public key. The browser passes this onto a push service when subscribing the user, meaning the push service can tie your application's public key to the user's PushSubscription.

The diagram below illustrates these steps.

Your web app is loaded in a browser and you call subscribe(), passing in your public application server key.
The browser then makes a network request to a push service who will generate an endpoint, associate this endpoint with the applications public key and return the endpoint to the browser.
The browser will add this endpoint to the PushSubscription, which is returned via the subscribe() promise.

When you later want to send a push message, you'll need to create an Authorization header which will contain information signed with your application server's private key. When the push service receives a request to send a push message, it can validate this signed Authorization header by looking up the public key linked to the endpoint receiving the request. If the signature is valid the push service knows that it must have come from the application server with the matching private key. It's basically a security measure that prevents anyone else sending messages to an application's users.

Technically, the applicationServerKey is optional. However, the easiest implementation on Chrome requires it, and other browsers may require it in the future. It's optional on Firefox.

The specification that defines what the application server key should be is the VAPID spec. Whenever you read something referring to "application server keys" or "VAPID keys", just remember that they are the same thing.

How to create application server keys #

You can create a public and private set of application server keys by visiting web-push-codelab.glitch.me or you can use the web-push command line to generate keys by doing the following:

    $ npm install -g web-push
    $ web-push generate-vapid-keys

You only need to create these keys once for your application, just make sure you keep the private key private. (Yeah, I just said that.)

There is one side effect of calling subscribe(). If your web app doesn't have permissions for showing notifications at the time of calling subscribe(), the browser will request the permissions for you. This is useful if your UI works with this flow, but if you want more control (and I think most developers will), stick to the Notification.requestPermission() API that we used earlier.

What is a PushSubscription? #

We call subscribe(), pass in some options, and in return we get a promise that resolves to a PushSubscription resulting in some code like so:

function subscribeUserToPush() {
  return navigator.serviceWorker
    .register('/service-worker.js')
    .then(function (registration) {
      const subscribeOptions = {
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(
          'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
        ),
      };

      return registration.pushManager.subscribe(subscribeOptions);
    })
    .then(function (pushSubscription) {
      console.log(
        'Received PushSubscription: ',
        JSON.stringify(pushSubscription),
      );
      return pushSubscription;
    });
}

The PushSubscription object contains all the required information needed to send a push messages to that user. If you print out the contents using JSON.stringify(), you'll see the following:

    {
      "endpoint": "https://some.pushservice.com/something-unique",
      "keys": {
        "p256dh":
    "BIPUL12DLfytvTajnryr2PRdAgXS3HGKiLqndGcJGabyhHheJYlNGCeXl1dn18gSJ1WAkAPIxr4gK0_dQds4yiI=",
        "auth":"FPssNDTKnInHVndSTdbKFw=="
      }
    }

The endpoint is the push services URL. To trigger a push message, make a POST request to this URL.

The keys object contains the values used to encrypt message data sent with a push message (which we'll discuss later on in this section).

Send a subscription to Your Server #

Once you have a push subscription you'll want to send it to your server. It's up to you how you do that but a tiny tip is to use JSON.stringify() to get all the necessary data out of the subscription object. Alternatively you can piece together the same result manually like so:

const subscriptionObject = {
  endpoint: pushSubscription.endpoint,
  keys: {
    p256dh: pushSubscription.getKeys('p256dh'),
    auth: pushSubscription.getKeys('auth'),
  },
};

// The above is the same output as:

const subscriptionObjectToo = JSON.stringify(pushSubscription);

Sending the subscription is done in the web page like so:

function sendSubscriptionToBackEnd(subscription) {
  return fetch('/api/save-subscription/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(subscription),
  })
    .then(function (response) {
      if (!response.ok) {
        throw new Error('Bad status code from server.');
      }

      return response.json();
    })
    .then(function (responseData) {
      if (!(responseData.data && responseData.data.success)) {
        throw new Error('Bad response from server.');
      }
    });
}

The node server receives this request and saves the data to a database for use later on.

app.post('/api/save-subscription/', function (req, res) {
  if (!isValidSaveRequest(req, res)) {
    return;
  }

  return saveSubscriptionToDatabase(req.body)
    .then(function (subscriptionId) {
      res.setHeader('Content-Type', 'application/json');
      res.send(JSON.stringify({data: {success: true}}));
    })
    .catch(function (err) {
      res.status(500);
      res.setHeader('Content-Type', 'application/json');
      res.send(
        JSON.stringify({
          error: {
            id: 'unable-to-save-subscription',
            message:
              'The subscription was received but we were unable to save it to our database.',
          },
        }),
      );
    });
});

With the PushSubscription details on our server we are good to send our user a message whenever we want.

FAQs #

A few common questions people have asked at this point:

Can I change the push service a browser uses? #

No. The push service is selected by the browser and as we saw with the subscribe() call, the browser will make network requests to the push service to retrieve the details that make up the PushSubscription.

Each browser uses a different Push Service, don't they have different API's? #

All push services will expect the same API.

This common API is called the Web Push Protocol and describes the network request your application will need to make to trigger a push message.

Unfortunately not. A user must register for push on each browser they wish to receive messages on. It's also worth noting that this will require the user granting permission on each device.

Where to go next #

Code labs #

How push works

2016-06-30T00:00:00Z

Before getting into the API, let's look at push from a high level, start to finish. Then as we step through individual topics or APIs later on, you'll have an idea of how and why it's important.

The three key steps to implementing push are:

Adding the client side logic to subscribe a user to push (i.e. the JavaScript and UI in your web app that registers a user to push messages).
The API call from your back-end / application that triggers a push message to a user's device.
The service worker JavaScript file that will receive a "push event" when the push arrives on the device. It's in this JavaScript that you'll be able to show a notification.

Let's look at what each of these steps entails in a little more detail.

Step 1: Client Side #

The first step is to "subscribe" a user to push messaging.

Subscribing a user requires two things. First, getting permission from the user to send them push messages. Second, getting a PushSubscription from the browser.

A PushSubscription contains all the information we need to send a push message to that user. You can "kind of" think of this as an ID for that user's device.

This is all done in JavaScript with the Push API.

Browser support

Chrome 42, Supported 42
Firefox 44, Supported 44
Edge 17, Supported 17
Safari 16, Supported 16

Source

Before subscribing a user you'll need to generate a set of "application server keys", which we'll cover later on.

The application server keys, also known as VAPID keys, are unique to your server. They allow a push service to know which application server subscribed a user and ensure that it's the same server triggering the push messages to that user.

Once you've subscribed the user and have a PushSubscription, you'll need to send the PushSubscription details to your backend / server. On your server, you'll save this subscription to a database and use it to send a push message to that user.

Step 2: Send a push message #

When you want to send a push message to your users you need to make an API call to a push service. This API call would include what data to send, who to send the message to and any criteria about how to send the message. Normally this API call is done from your server.

Some questions you might be asking yourself:

Who and what is the push service?
What does the API look like? Is it JSON, XML, something else?
What can the API do?

Who and what is the push service? #

A push service receives a network request, validates it and delivers a push message to the appropriate browser. If the browser is offline, the message is queued until the browser comes online.

Each browser can use any push service they want, it's something developers have no control over. This isn't a problem because every push service expects the same API call. Meaning you don't have to care who the push service is. You just need to make sure that your API call is valid.

To get the appropriate URL to trigger a push message (i.e. the URL for the push service) you just need to look at the endpoint value in a PushSubscription.

Below is an example of the values you'll get from a PushSubscription:

{
  "endpoint": "https://random-push-service.com/some-kind-of-unique-id-1234/v2/",
  "keys": {
    "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM=",
    "auth": "tBHItJI5svbpez7KI4CCXg=="
  }
}

The endpoint in this case is [https://random-push-service.com/some-kind-of-unique-id-1234/v2/]. The push service would be 'random-push-service.com' and each endpoint is unique to a user, indicated with 'some-kind-of-unique-id-1234'. As you start working with push you'll notice this pattern.

The keys in the subscription will be covered later on.

What does the API look like? #

I mentioned that every web push service expects the same API call. That API is the Web Push Protocol. It's an IETF standard that defines how you make an API call to a push service.

The API call requires certain headers to be set and the data to be a stream of bytes. We'll look at libraries that can perform this API call for us as well as how to do it ourselves.

What can the API do? #

The API provides a way to send a message to a user, with / without data, and provides instructions of how to send the message.

The data you send with a push message must be encrypted. The reason for this is that it prevents push services, who could be anyone, from being able to view the data sent with the push message. This is important given that it's the browser who decides which push service to use, which could open the door to browsers using a push service that isn't safe or secure.

When you trigger a push message, the push service will receive the API call and queue the message. This message will remain queued until the user's device comes online and the push service can deliver the messages. The instructions you can give to the push service define how the push message is queued.

The instructions include details like:

The time-to-live for a push message. This defines how long a message should be queued before it's removed and not delivered.
Define the urgency of the message. This is useful in case the push service is preserving the users battery life by only delivering high priority messages.
Give a push message a "topic" name which will replace any pending message with this new message.

Step 3: Push event on the user's device #

Once we've sent a push message, the push service will keep your message on its server until one of following events occurs:

The device comes online and the push service delivers the message.
The message expires. If this occurs the push service removes the message from its queue and it'll never be delivered.

When the push service does deliver a message, the browser will receive the message, decrypt any data and dispatch a push event in your service worker.

A service worker is a "special" JavaScript file. The browser can execute this JavaScript without your page being open. It can even execute this JavaScript when the browser is closed. A service worker also has API's, like push, that aren't available in the web page (i.e. API's that aren't available out of a service worker script).

It's inside the service worker's 'push' event that you can perform any background tasks. You can make analytics calls, cache pages offline and show notifications.

That's the whole flow for push messaging.

Where to go next #

Code labs #

Enabling HTTPS on your servers

2015-03-27T00:00:00Z

Steps covered in this article #

Create a 2048-bit RSA public/private key pair.
Generate a certificate signing request (CSR) that embeds your public key.
Share your CSR with your Certificate Authority (CA) to receive a final certificate or a certificate chain.
Install your final certificate in a non-web-accessible place such as /etc/ssl (Linux and Unix) or wherever IIS requires it (Windows).

Generating keys and certificate signing requests #

This section uses the openssl command-line program, which comes with most Linux, BSD, and Mac OS X systems, to generate private/public keys and a CSR.

Generate a public/private key pair #

Let's start by generating a 2,048-bit RSA key pair. A smaller key, such as 1,024 bits, is insufficiently resistant to brute-force guessing attacks. A larger key, such as 4,096 bits, is overkill. Over time, key sizes increase as computer processing gets cheaper. 2,048 is currently the sweet spot.

The command to generate the RSA key pair is:

openssl genrsa -out www.example.com.key 2048

This gives the following output:

Generating RSA private key, 2048 bit long modulus
.+++
.......................................................................................+++
e is 65537 (0x10001)

Generate a certificate signing request #

In this step, you embed your public key and information about your organization and your website into a certificate signing request or CSR. The openssl command interactively asks you for the required metadata.

Running the following command:

openssl req -new -sha256 -key www.example.com.key -out www.example.com.csr

Outputs the following:

You are about to be asked to enter information that will be incorporated
into your certificate request

What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:CA
State or Province Name (full name) [Some-State]:California
Locality Name (for example, city) []:Mountain View
Organization Name (for example, company) [Internet Widgits Pty Ltd]:Example, Inc.
Organizational Unit Name (for example, section) []:Webmaster Help Center Example
Team
Common Name (e.g. server FQDN or YOUR name) []:www.example.com
Email Address []:webmaster@example.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

To ensure the validity of the CSR, run this command:

openssl req -text -in www.example.com.csr -noout

And the response should look like this:

Certificate Request:
    Data:
        Version: 0 (0x0)
        Subject: C=CA, ST=California, L=Mountain View, O=Google, Inc.,
OU=Webmaster Help Center Example Team,
CN=www.example.com/emailAddress=webmaster@example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:ad:fc:58:e0:da:f2:0b:73:51:93:29:a5:d3:9e:
                    f8:f1:14:13:64:cc:e0:bc:be:26:5d:04:e1:58:dc:
                    ...
                Exponent: 65537 (0x10001)
        Attributes:
            a0:00
    Signature Algorithm: sha256WithRSAEncryption
         5f:05:f3:71:d5:f7:b7:b6:dc:17:cc:88:03:b8:87:29:f6:87:
         2f:7f:00:49:08:0a:20:41:0b:70:03:04:7d:94:af:69:3d:f4:
         ...

Submit your CSR to a certificate authority #

Different certificate authorities (CAs) require different methods for sending them your CSRs. Methods may include using a form on their website, sending the CSR by email, or something else. Some CAs (or their resellers) may even automate some or all of the process (including, in some cases, key pair and CSR generation).

Send the CSR to your CA, and follow their instructions to receive your final certificate or certificate chain.

Different CAs charge different amounts of money for the service of vouching for your public key.

There are also options for mapping your key to more than one DNS name, including several distinct names (e.g. all of example.com, www.example.com, example.net, and www.example.net) or "wildcard" names such as *.example.com.

For example, one CA currently offers these prices:

Standard: $16/year, valid for example.com and www.example.com.
Wildcard: $150/year, valid for example.com and *.example.com.

At these prices, wildcard certificates are economical when you have more than 9 subdomains; otherwise, you can just buy one or more single-name certificates. (If you have more than, say, five subdomains, you might find a wildcard certificate more convenient when you come to enable HTTPS on your servers.)

Copy the certificates to all your front-end servers in a non-web-accessible place such as /etc/ssl (Linux and Unix) or wherever IIS (Windows) requires them.

Enable HTTPS on your servers #

Enabling HTTPS on your servers is a critical step in providing security for your web pages.

Use Mozilla's Server Configuration tool to set up your server for HTTPS support.
Regularly test your site with the Qualys' handy SSL Server Test and ensure you get at least an A or A+.

At this point, you must make a crucial operations decision. Choose one of the following:

Dedicate a distinct IP address to each hostname your web server serves content from.
Use name-based virtual hosting.

If you have been using distinct IP addresses for each hostname, you can easily support both HTTP and HTTPS for all clients.

However, most site operators use name-based virtual hosting to conserve IP addresses and because it's more convenient in general. The problem with IE on Windows XP and Android earlier than 2.3 is that they do not understand Server Name Indication (SNI), which is crucial for HTTPS name-based virtual hosting.

Someday—hopefully soon—clients that don't support SNI will be replaced with modern software. Monitor the user agent string in your request logs to know when enough of your user population has migrated to modern software. (You can decide what your threshold is; perhaps less than 5%, or less then 1%.)

If you don't already have HTTPS service available on your servers, enable it now (without redirecting HTTP to HTTPS; see below). Configure your web server to use the certificates you bought and installed. You might find Mozilla's handy configuration generator useful.

If you have many hostnames or subdomains, they each need to use the right certificate.

Now, and throughout your site's lifetime, check your HTTPS configuration with Qualys' handy SSL Server Test. Your site should score an A or A+; treat anything that causes a lower grade as a bug. (Today's A is tomorrow's B, because attacks against algorithms and protocols are always improving!)

Make intrasite URLs relative #

Now that you are serving your site on both HTTP and HTTPS, things need to work as smoothly as possible, regardless of protocol. An important factor is using relative URLs for intrasite links.

Make sure intrasite URLs and external URLs are agnostic to protocol; that is, make sure you use relative paths or leave out the protocol like //example.com/something.js.

A problem arises when you serve a page via HTTPS that includes HTTP resources, known as mixed content. Browsers warn users that the full strength of HTTPS has been lost. In fact, in the case of active mixed content (script, plug-ins, CSS, iframes), browsers often simply won't load or execute the content at all, resulting in a broken page. And remember, it's perfectly OK to include HTTPS resources in an HTTP page.

Additionally, when you link to other pages in your site, users could get downgraded from HTTPS to HTTP.

These problems happen when your pages include fully-qualified, intrasite URLs that use the http:// scheme.

Don't

<h1>Welcome To Example.com</h1>
<script src="http://example.com/jquery.js"></script>
<link rel="stylesheet" href="http://assets.example.com/style.css"/>
<img src="http://img.example.com/logo.png"/>;
<p>A <a href="http://example.com/2014/12/24/">new post on cats!</a></p>

Avoid using fully qualified intrasite URLs.

In other words, make intrasite URLs as relative as possible: either protocol-relative (lacking a protocol, starting with //example.com) or host-relative (starting with just the path, like /jquery.js).

<h1>Welcome To Example.com</h1>
<script src="/jquery.js"></script>
<link rel="stylesheet" href="/assets/style.css"/>
<img src="/images/logo.png"/>;
<p>A <a href="/2014/12/24/">new post on cats!</a></p>

Use relative intrasite URLs.

<h1>Welcome To Example.com</h1>
<script src="//example.com/jquery.js"></script>
<link rel="stylesheet" href="//assets.example.com/style.css"/>
<img src="//img.example.com/logo.png"/>;
<p>A <a href="//example.com/2014/12/24/">new post on cats!</a></p>

Or, use protocol-relative intrasite URLs.

<h1>Welcome To Example.com</h1>
<script src="/jquery.js"></script>
<link rel="stylesheet" href="/assets/style.css"/>
<img src="/images/logo.png"/>;
<p>A <a href="/2014/12/24/">new post on cats!</a></p>
&lt;p>Check out this <a href="<b>https://foo.com/</b>">other cool site.</a></p>

Use HTTPS URLs for intersite URLs (where possible).

Do this with a script, not by hand. If your site's content is in a database, test your script on a development copy of your database. If your site's content consists of simple files, test your script on a development copy of the files. Push the changes to production only after the changes pass QA, as normal. You can use Bram van Damme's script or something similar to detect mixed content in your site.

When linking to other sites (as opposed to including resources from them), don't change the protocol since you don't have control over how those sites operate.

To make migration smoother for large sites, we recommend protocol-relative URLs. If you are not sure whether you can fully deploy HTTPS yet, forcing your site to use HTTPS for all sub-resources may backfire. There is likely to be a period of time in which HTTPS is new and weird for you, and the HTTP site must still work as well as ever. Over time, you'll complete the migration and lock in HTTPS (see the next two sections).

If your site depends on scripts, images, or other resources served from a third party, such as a CDN or jquery.com, you have two options:

Use protocol-relative URLs for these resources. If the third party does not serve HTTPS, ask them to. Most already do, including jquery.com.
Serve the resources from a server that you control, and which offers both HTTP and HTTPS. This is often a good idea anyway, because then you have better control over your site's appearance, performance, and security. In addition, you don't have to trust a third party, which is always nice.

Redirect HTTP to HTTPS #

You need to put a canonical link at the head of your page to tell search engines that HTTPS is the best way to get to your site.

Set <link rel="canonical" href="https://…"/> tags in your pages. This helps search engines determine the best way to get to your site.

Turn on Strict Transport Security and secure cookies #

At this point, you are ready to "lock in" the use of HTTPS.

Use HTTP Strict Transport Security (HSTS) to avoid the cost of the 301 redirect.
Always set the Secure flag on cookies.

First, use Strict Transport Security to tell clients that they should always connect to your server via HTTPS, even when following an http:// reference. This defeats attacks such as SSL Stripping, and also avoids the round-trip cost of the 301 redirect that we enabled in Redirect HTTP to HTTPS.

Turn on HTTP Strict Transport Security (HSTS) by setting the Strict-Transport-Security header. OWASP's HSTS page has links to instructions for various server software.

Most web servers offer a similar ability to add custom headers.

It is also important to make sure that clients never send cookies (such as for authentication or site preferences) over HTTP. For example, if a user's authentication cookie were to be exposed in plain text, the security guarantee of their entire session would be destroyed—even if you have done everything else right!

Therefore, change your web application to always set the Secure flag on cookies that it sets. This OWASP page explains how to set the Secure flag in several application frameworks. Every application framework has a way to set the flag.

Most web servers offer a simple redirect feature. Use 301 (Moved Permanently) to indicate to search engines and browsers that the HTTPS version is canonical, and redirect your users to the HTTPS version of your site from HTTP.

Search ranking #

Google uses HTTPS as a positive search quality indicator. Google also publishes a guide for how to transfer, move, or migrate your site while maintaining its search rank. Bing also publishes guidelines for webmasters.

Performance #

When the content and application layers are well-tuned (see Steve Souders' books for great advice), the remaining TLS performance concerns are generally small, relative to the overall cost of the application. Additionally, you can reduce and amortize those costs. (For great advice on TLS optimization and generally, see High Performance Browser Networking by Ilya Grigorik.) See also Ivan Ristic's OpenSSL Cookbook and Bulletproof SSL And TLS.

In some cases, TLS can improve performance, mostly as a result of making HTTP/2 possible. Chris Palmer gave a talk on HTTPS and HTTP/2 performance at Chrome Dev Summit 2014.

Referer headers #

When users follow links from your HTTPS site to other HTTP sites, user agents don't send the Referer header. If this is a problem, there are several ways to solve it:

The other sites should migrate to HTTPS. If referee sites can complete the Enable HTTPS on your servers section of this guide, you can change links in your site to theirs from http:// to https://, or you can use protocol-relative links.
To work around a variety of problems with Referer headers, use the new Referrer Policy standard.

Because search engines are migrating to HTTPS, in the future, you are likely to see more Referer headers when you migrate to HTTPS.

Ad revenue #

Site operators that monetize their site by showing ads want to make sure that migrating to HTTPS does not reduce ad impressions. But due to mixed content security concerns, an HTTP <iframe> doesn't work in an HTTPS page. There is a tricky collective action problem here: until advertisers publish over HTTPS, site operators cannot migrate to HTTPS without losing ad revenue; but until site operators migrate to HTTPS, advertisers have little motivation to publish HTTPS.

Advertisers should at least offer ad service via HTTPS (such as by completing the "Enable HTTPS on your servers" section on this page). Many already do. You should ask advertisers that do not serve HTTPS at all to at least start. You may wish to defer completing Make IntraSite URLs relative until enough advertisers interoperate properly.

Important Security Terminology

2015-03-27T00:00:00Z

Summary #

Used public/private keys to sign and decrypt messages between the browser and the server.
A certificate authority (CA) is an organization that vouches for the mapping between the public keys and public DNS names (such as "www.foobar.com").
A certificate signing request (CSR) is a data format that bundles a public key together with some metadata about the entity that owns the key

What are the public and private key pairs? #

A public/private key pair is a pair of very large numbers that are used as encryption and decryption keys, and that share a special mathematical relationship. A common system for key pairs is the RSA cryptosystem. The public key is used to encrypt messages, and the messages can only be feasibly decrypted with the corresponding private key. Your web server advertises its public key to the world, and clients (such as web browsers) use that to bootstrap a secure channel to your server.

What is a certificate authority? #

A certification authority (CA) is an organization that vouches for the mapping between public keys and public DNS names (such as "www.foobar.com"). For example, how is a client to know if a particular public key is the true public key for www.foobar.com? A priori, there is no way to know. A CA vouches for a particular key as being the true one for a particular site by using its own private key to cryptographically sign the website's public key. This signature is computationally infeasible to forge. Browsers (and other clients) maintain trust anchor stores containing the public keys owned by the well-known CAs, and they use those public keys to cryptographically verify the CA's signatures.

An X.509 certificate is a data format that bundles a public key together with some metadata about the entity that owns the key. In the case of the web, the owner of the key is the site operator, and the important metadata is the DNS name of the web server. When a client connects to an HTTPS web server, the web server presents its certificate for the client to verify. The client verifies that the certificate has not expired, that the DNS name matches the name of the server the client is trying to connect to, and that a known trust anchor CA has signed the certificate. In most cases, CAs do not directly sign web server certificates; usually, there is a chain of certificates linking a trust anchor to an intermediate signer or signers, and finally to the web server's own certificate (the end entity).

What is a certificate signing request? #

A certificate signing request (CSR) is a data format which, like a certificate, bundles a public key together with some metadata about the entity that owns the key. However, clients do not interpret CSRs; CAs do. When you seek to have a CA vouch for your web server's public key, you send the CA a CSR. The CA validates the information in the CSR and uses it to generate a certificate. The CA then sends you the final certificate, and you install that certificate (or, more likely, a certificate chain) and your private key on your web server.

Introduction to fetch()

2015-03-10T00:00:00Z

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.

Browser support

Chrome 42, Supported 42
Firefox 39, Supported 39
Edge 14, Supported 14
Safari 10.1, Supported 10.1

Source

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 Introduction to JavaScript Promises.

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.

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.

Push notifications FAQ

2014-10-07T00:00:00Z

Why doesn't push work when the browser is closed? #

This question crops up quite a bit, largely because there are a few scenarios that make it difficult to reason with and understand.

Let's start with Android. The Android OS is designed to listen for push messages and upon receiving one, wake up the appropriate Android app to handle the push message, regardless of whether the app is closed or not.

This is exactly the same with any browser on Android, the browser will be woken up when a push message is received and the browser will then wake up your service worker and dispatch the push event.

On desktop OS's, it's more nuanced and it's easiest to explain on Mac OS X because there is a visual indicator to help explain the different scenarios.

On Mac OS X, you can tell if a program is running or not by a marking under the app icon in the dock.

If you compare the two Chrome icons in the following dock, the one on the left is running, as illustrated by the marking under the icon, whereas the Chrome on the right is not running, hence the lack of the marking underneath.

In the context of receiving push messages on desktop, you will receive messages when the browser is running, i.e. has the marking underneath the icon.

This means the browser can have no windows open, and you'll still receive the push message in your service worker, because the browser in running in the background.

The only time a push won't be received is when the browser is completely closed, i.e. not running at all (no marking). The same applies for Windows, although it's a little trickier to determine whether or not Chrome is running in the background.

How do I make my home screen web app open fullscreen from a push? #

On Chrome for Android, a web app can be added to the home screen and when the web app is opened from the home screen, it can launch in fullscreen mode without the URL bar, as shown below.

To keep this experience consistent, developers want their clicked notifications to open their web app in fullscreen as well.

Chrome "sort of" implemented this, although you may find it unreliable and difficult to reason with. The relevant implementation details are:

What this means is that unless your user is visiting your site through the home screen icon fairly regularly, your notifications will open in the normal browser UI.

This issue will be worked on further.

Why is this any better than web sockets? #

A service worker can be brought to life when the browser window is closed. A web socket will only live as long as the browser and web page is kept open.

What is the deal with GCM, FCM, Web Push and Chrome? #

This question has a number of facets to it and the easiest way to explain is to step through the history of web push and Chrome. (Don't worry, it's short.)

December 2014 #

When Chrome first implemented web push, Chrome used Google Cloud Messaging (GCM) to power the sending of push messages from the server to the browser.

This was not web push. There are a few reasons this early set-up of Chrome and GCM wasn't "real" web push.

GCM requires developers to set up an account on the Google Developers Console.
Chrome and GCM needed a special sender ID to be shared by a web app to be able to set up messaging correctly.
GCM's servers accepted a custom API request that wasn't a web standard.

July 2016 #

In July a new feature in web push landed - Application Server Keys (or VAPID, as the spec is known). When Chrome added support for this new API, it used Firebase Cloud Messaging (also known as FCM) instead of GCM as a messaging service. This is important for a few reasons:

Chrome and Application Sever Keys do not need any kind of project to be set up with Google or Firebase. It'll just work.
FCM supports the web push protocol, which is the API that all web push services will support. This means that regardless of what push service a browser uses, you just make the same kind of request and it'll send the message.

Why is it confusing today? #

There is a large amount of confusion now that content has been written on the topic of web push, much of which references GCM or FCM. If content references GCM, you should probably treat it as a sign that it's either old content OR it's focusing too much on Chrome. (I'm guilty of doing this in a number of old posts.)

Instead, think of web push as consisting of a browser, which uses a push service to manage sending and receiving messages, where the push service will accept a "web push protocol" request. If you think in these terms, you can ignore which browser and which push service it's using and get to work.

This guide has been written to focus on the standards approach of web push and purposefully ignores anything else.

Firebase has a JavaScript SDK. What and Why? #

For those of you who have found the Firebase web SDK and noticed it has a messaging API for JavaScript, you may be wondering how it differs from web push.

The messaging SDK (known as Firebase Cloud Messaging JS SDK) does a few tricks behind the scenes to make it easier to implement web push.

Instead of worrying about a PushSubscription and its various fields, you only need to worry about an FCM Token (a string).
Using the tokens for each user, you can use the proprietary FCM API to trigger push messages. This API doesn't require encrypting payloads. You can send a plain text payload in a POST request body.
FCM's proprietary API supports custom features, for example FCM Topics (It works on the web too, though it's poorly documented).
Finally, FCM supports Android, iOS and web, so for some teams it is easier to work with in existing projects.

This uses web push behind the scenes, but its goal is to abstract it away.

Like I said in the previous question, if you consider web push as just a browser and a push service, then you can consider the Messaging SDK in Firebase as a library to simplify implementing web push.

Where to go next #

Code labs #

Add touch to your site

2014-01-01T00:00:00Z

Touchscreens are available on more and more devices, ranging from phones to desktop screens. When your users choose to interact with your UI, your app should respond to their touch in intuitive ways.

Respond to element states #

Have you ever touched or clicked an element on a web page and questioned whether the site actually detected it?

Simply altering the color of an element as users touch or interact with parts of your UI gives a basic reassurance that your site is working. Not only does this alleviate frustration, it can also give a snappy and responsive feel.

DOM elements can inherit any of the following states: default, focus, hover and active. To change our UI for each of these states, we need to apply styles to the following pseudo classes :hover, :focus and :active as shown below:

.btn {
  background-color: #4285f4;
}

.btn:hover {
  background-color: #296cdb;
}

.btn:focus {
  background-color: #0f52c1;

  /* The outline parameter suppresses the border
  color / outline when focused */
  outline: 0;
}

.btn:active {
  background-color: #0039a8;
}

Try it

On most mobile browsers hover and/or focus states will apply to an element after it's been tapped.

Consider carefully what styles you set and how they will look to the user after they finish their touch.

Suppressing default browser styles #

Once you add styles for the different states, you'll notice that most browsers implement their own styles in response to a user’s touch. This is largely because when mobile devices first launched, a number of sites didn’t have styling for the :active state. As a result, many browsers added additional highlight color or style to give the user feedback.

Most browsers use the outline CSS property to display a ring around an element when an element is focused. You can suppress it with:

.btn:focus {
    outline: 0;

    /* Add replacement focus styling here (i.e. border) */
}

Safari and Chrome add a tap highlight color which can be prevented with the -webkit-tap-highlight-color CSS property:

/* Webkit / Chrome Specific CSS to remove tap
highlight color */
.btn {
  -webkit-tap-highlight-color: transparent;
}

Try it

Internet Explorer on Windows Phone has a similar behavior, but is suppressed via a meta tag:

<meta name="msapplication-tap-highlight" content="no">

Firefox has two side effects to handle.

The -moz-focus-inner pseudo class, which adds an outline on touchable elements, you can remove by setting border: 0.

If you are using a <button> element on Firefox, you get a gradient applied, which you can remove by setting background-image: none.

/* Firefox Specific CSS to remove button
differences and focus ring */
.btn {
  background-image: none;
}

.btn::-moz-focus-inner {
  border: 0;
}

Try it

Disabling user-select #

When you're creating your UI there may be scenarios where you want users to interact with your elements but you want to suppress the default behavior of selecting text on long press or dragging a mouse over your UI.

You can do this with the user-select CSS property, but beware that doing this on content can be extremely infuriating for users if they want to select the text in the element. So make sure you use it with caution and sparingly.

/* Example: Disable selecting text on a paragraph element: */
p.disable-text-selection {
  user-select: none;
}

Implement custom gestures #

If you have an idea for custom interactions and gestures for your site, there are two topics to keep in mind:

How to support all browsers.
How to keep your frame rate high.

In this article, we'll look at exactly these topics covering the API's we need to support to hit all browsers and then cover how we use these events efficiently.

Depending on what you would like your gesture to do, you likely want the user to interact with one element at a time or you'll want them to be able to interact with multiple elements at the same time.

We are going to look at two examples in this article, both demonstrating support for all browsers and how to keep the frame rate high.

The first example will allow the user to interact with one element. In this case you might want all touch events to be given to that one element, as long as the gesture initially started on the element itself. For example, moving a finger off the swipe-able element can still control the element.

This is useful as it provides a great deal of flexibility for the user, but enforces a restriction on how the user can interact with your UI.

If, however, you expect users to interact with multiple elements at the same time (using multi-touch), you should restrict the touch to the specific element.

This is more flexible for users, but complicates the logic for manipulating the UI and is less resilient to user error.

Add event listeners #

In Chrome (version 55 and later), Internet Explorer & Edge, PointerEvents are the recommended approach for implementing custom gestures.

In other browsers TouchEvents and MouseEvents are the correct approach.

The great feature of PointerEvents is that it merges multiple types of input, including mouse, touch and pen events, into one set of callbacks. The events to listen for are pointerdown, pointermove, pointerup and pointercancel.

The equivalents in other browsers are touchstart, touchmove, touchend and touchcancel for touch events and if you wanted to implement the same gesture for mouse input you'd need to implement mousedown, mousemove, and mouseup.

If you have questions about which events to use, check out this table of Touch, mouse and pointer events).

Using these events requires calling the addEventListener() method on a DOM element, along with the name of an event, a callback function and a boolean. The boolean determines whether you should catch the event before or after other elements have had the opportunity to catch and interpret the events. (true means you want the event before other elements.)

Here's an example of listening for the start of an interaction.

// Check if pointer events are supported.
if (window.PointerEvent) {
  // Add Pointer Event Listener
  swipeFrontElement.addEventListener('pointerdown', this.handleGestureStart, true);
  swipeFrontElement.addEventListener('pointermove', this.handleGestureMove, true);
  swipeFrontElement.addEventListener('pointerup', this.handleGestureEnd, true);
  swipeFrontElement.addEventListener('pointercancel', this.handleGestureEnd, true);
} else {
  // Add Touch Listener
  swipeFrontElement.addEventListener('touchstart', this.handleGestureStart, true);
  swipeFrontElement.addEventListener('touchmove', this.handleGestureMove, true);
  swipeFrontElement.addEventListener('touchend', this.handleGestureEnd, true);
  swipeFrontElement.addEventListener('touchcancel', this.handleGestureEnd, true);

  // Add Mouse Listener
  swipeFrontElement.addEventListener('mousedown', this.handleGestureStart, true);
}

Try it

Handle single-element interaction #

In the short snippet of code above we only added the starting event listener for mouse events. The reason for this is that mouse events will only trigger when the cursor is hovering over the element the event listener is added to.

TouchEvents will track a gesture after it's started regardless of where the touch occurs and PointerEvents will track events regardless of where the touch occurs after we call setPointerCapture on a DOM element.

For mouse move and end events we add the event listeners in the gesture start method and add the listeners to the document, meaning it can track the cursor until the gesture is complete.

The steps taken to implement this are:

Add all TouchEvent and PointerEvent listeners. For MouseEvents add only the start event.
Inside the start gesture callback, bind the mouse move and end events to the document. This way all mouse events are received regardless of whether the event occurs on the original element or not. For PointerEvents we need to call setPointerCapture() on our original element to receive all further events. Then handle the start of the gesture.
Handle the move events.
On the end event, remove the mouse move and end listeners from the document and end the gesture.

Below is a snippet of our handleGestureStart() method which adds the move and end events to the document:

// Handle the start of gestures
this.handleGestureStart = function(evt) {
  evt.preventDefault();

  if(evt.touches && evt.touches.length > 1) {
    return;
  }

  // Add the move and end listeners
  if (window.PointerEvent) {
    evt.target.setPointerCapture(evt.pointerId);
  } else {
    // Add Mouse Listeners
    document.addEventListener('mousemove', this.handleGestureMove, true);
    document.addEventListener('mouseup', this.handleGestureEnd, true);
  }

  initialTouchPos = getGesturePointFromEvent(evt);

  swipeFrontElement.style.transition = 'initial';
}.bind(this);

Try it

The end callback we add is handleGestureEnd(), which removes the move and end event listeners from the document and releases the pointer capture when the gesture has finished like so:

// Handle end gestures
this.handleGestureEnd = function(evt) {
  evt.preventDefault();

  if (evt.touches && evt.touches.length > 0) {
    return;
  }

  rafPending = false;

  // Remove Event Listeners
  if (window.PointerEvent) {
    evt.target.releasePointerCapture(evt.pointerId);
  } else {
    // Remove Mouse Listeners
    document.removeEventListener('mousemove', this.handleGestureMove, true);
    document.removeEventListener('mouseup', this.handleGestureEnd, true);
  }

  updateSwipeRestPosition();

  initialTouchPos = null;
}.bind(this);

Try it

By following this pattern of adding the move event to the document, if the user starts interacting with an element and moves their gesture outside of the element, we'll continue to get mouse movements regardless of where they are on the page, because the events are being received from the document.

This diagram shows what the touch events are doing as we add the move and end events to the document once a gesture begins.

Responding to touch efficiently #

Now that we have the start and end events taken care of we can actually respond to the touch events.

For any of the start and move events, you can easily extract x and y from an event.

The following example checks whether the event is from a TouchEvent by checking if targetTouches exists. If it does, then it extracts the clientX and clientY from the first touch. If the event is a PointerEvent or MouseEvent it extracts clientX and clientY directly from the event itself.

function getGesturePointFromEvent(evt) {
    var point = {};

    if (evt.targetTouches) {
      // Prefer Touch Events
      point.x = evt.targetTouches[0].clientX;
      point.y = evt.targetTouches[0].clientY;
    } else {
      // Either Mouse event or Pointer Event
      point.x = evt.clientX;
      point.y = evt.clientY;
    }

    return point;
  }

Try it

A TouchEvent has three lists containing touch data:

touches: list of all current touches on the screen, regardless of DOM element they are on.
targetTouches: list of touches currently on the DOM element the event is bound to.
changedTouches: list of touches which changed resulting in the event being fired.

In most cases, targetTouches gives you everything you need and want. (For more info on these lists see Touch lists).

Use requestAnimationFrame #

Since the event callbacks are fired on the main thread, we want to run as little code as possible in the callbacks for our events, keeping our frame rate high and preventing jank.

Using requestAnimationFrame() we have an opportunity to update the UI just before the browser is intending to draw a frame and will help us move some work out of our event callbacks.

If you are unfamiliar with requestAnimationFrame(), you can learn more here.

A typical implementation is to save the x and y coordinates from the start and move events and request an animation frame inside the move event callback.

In our demo, we store the initial touch position in handleGestureStart() (look for initialTouchPos):

// Handle the start of gestures
this.handleGestureStart = function(evt) {
  evt.preventDefault();

  if (evt.touches && evt.touches.length > 1) {
    return;
  }

  // Add the move and end listeners
  if (window.PointerEvent) {
    evt.target.setPointerCapture(evt.pointerId);
  } else {
    // Add Mouse Listeners
    document.addEventListener('mousemove', this.handleGestureMove, true);
    document.addEventListener('mouseup', this.handleGestureEnd, true);
  }

  initialTouchPos = getGesturePointFromEvent(evt);

  swipeFrontElement.style.transition = 'initial';
}.bind(this);

The handleGestureMove() method stores the position of it's event before requesting an animation frame if we need to, passing in our onAnimFrame() function as the callback:

this.handleGestureMove = function (evt) {
  evt.preventDefault();

  if (!initialTouchPos) {
    return;
  }

  lastTouchPos = getGesturePointFromEvent(evt);

  if (rafPending) {
    return;
  }

  rafPending = true;

  window.requestAnimFrame(onAnimFrame);
}.bind(this);

The onAnimFrame value is a function that when called, changes our UI to move it around. By passing this function into requestAnimationFrame(), we tell the browser to call it just before it's about to update the page (i.e. paint any changes to the page).

In the handleGestureMove() callback we initially check if rafPending is false, which indicates if onAnimFrame() has been called by requestAnimationFrame() since the last move event. This means we only have one requestAnimationFrame() waiting to run at any one time.

When our onAnimFrame() callback is executed, we set the transform on any elements we want to move before updating rafPending to false, allowing the the next touch event to request a new animation frame.

function onAnimFrame() {
  if (!rafPending) {
    return;
  }

  var differenceInX = initialTouchPos.x - lastTouchPos.x;
  var newXTransform = (currentXPosition - differenceInX)+'px';
  var transformStyle = 'translateX('+newXTransform+')';

  swipeFrontElement.style.webkitTransform = transformStyle;
  swipeFrontElement.style.MozTransform = transformStyle;
  swipeFrontElement.style.msTransform = transformStyle;
  swipeFrontElement.style.transform = transformStyle;

  rafPending = false;
}

Control gestures using touch actions #

The CSS property touch-action allows you to control the default touch behavior of an element. In our examples, we use touch-action: none to prevent the browser from doing anything with a users' touch, allowing us to intercept all of the touch events.

/* Pass all touches to javascript: */
button.custom-touch-logic {
  touch-action: none;
}

Using touch-action: none is somewhat a nuclear option as it prevents all the default browser behaviors. In many cases one of the options below is a better solution.

touch-action allows you to disable gestures implemented by a browser. For example, IE10+ supports a double-tap to zoom gesture. By setting a touch-action of manipulation you prevent the default double-tap behavior.

This allows you to implement a double-tap gesture yourself.

Below is a list of commonly used touch-action values:

Touch Action Parameters
`touch-action: none`	No touch interactions will be handled by the browser.
`touch-action: pinch-zoom`	Disables all browser interactions like `touch-action: none` apart from `pinch-zoom`, which is still handled by the browser.
`touch-action: pan-y pinch-zoom`	Handle horizontal scrolls in JavaScript without disabling vertical scrolling or pinch-zooming (eg. image carousels).
`touch-action: manipulation`	Disables double-tap gesture which avoids any click delay by the browser. Leaves scrolling and pinch-zoom up to the browser.

Supporting older versions of IE #

If you want to support IE10, you'll need to handle vendor prefixed versions of PointerEvents.

To check for support of PointerEvents you'd typically look for window.PointerEvent, but in IE10, you'd look for window.navigator.msPointerEnabled.

The event names with vendor prefixes are: 'MSPointerDown', 'MSPointerUp' and 'MSPointerMove'.

The example below shows you how to check for support and switch the event names.

var pointerDownName = 'pointerdown';
var pointerUpName = 'pointerup';
var pointerMoveName = 'pointermove';

if (window.navigator.msPointerEnabled) {
  pointerDownName = 'MSPointerDown';
  pointerUpName = 'MSPointerUp';
  pointerMoveName = 'MSPointerMove';
}

// Simple way to check if some form of pointerevents is enabled or not
window.PointerEventsSupport = false;
if (window.PointerEvent || window.navigator.msPointerEnabled) {
  window.PointerEventsSupport = true;
}

For more information, checkout this updates article from Microsoft.

Reference #

Pseudo classes for touch states #

Class	Example	Description
:hover		Entered when a cursor is placed over an element. Changes in the UI on hover are helpful to encourage users to interact with elements.
:focus		Entered when the user tabs through elements on a page. The focus state allows the user to know what element they are currently interacting with; also allows users to navigate your UI easily using a keyboard.
:active		Entered when an element is being selected, for example, when a user is clicking or touching an element.

The definitive touch events reference can be found here: W3C Touch Events.

Touch, mouse, and pointer events #

These events are the building blocks for adding new gestures into your application:

Touch, Mouse, Pointer Events
`touchstart`, `mousedown`, `pointerdown`	This is called when a finger first touches an element or when the user clicks down on the mouse.
`touchmove`, `mousemove`, `pointermove`	This is called when the user moves their finger across the screen or drags with the mouse.
`touchend`, `mouseup`, `pointerup`	This is called when the user lifts their finger off of the screen or releases the mouse.
`touchcancel` `pointercancel`	This is called when the browser cancels the touch gestures. For example, a user touch a web app and then change tabs.

Touch lists #

Each touch event includes three list attributes:

Touch Event Attributes
`touches`	List of all current touches on the screen, regardless of elements being touched.
`targetTouches`	List of touches that started on the element that is the target of the current event. For example, if you bind to a `<button>`, you'll only get touches currently on that button. If you bind to the document, you'll get all touches currently on the document.
`changedTouches`	List of touches which changed resulting in the event being fired: For the `touchstart` event-- list of the touch points that just became active with the current event. For the `touchmove` event-- list of the touch points that have moved since the last event. For the `touchend` and `touchcancel` events-- list of the touch points that have just been removed from the surface.

Enabling active state support on iOS #

Unfortunately, Safari on iOS does not apply the active state by default, to get it working you need to add a touchstart event listener to the document body or to each element.

You should do this behind a user agent test so it's only run on iOS devices.

Adding a touch start to the body has the advantage of applying to all elements in the DOM, however this may have performance issues when scrolling the page.

window.onload = function() {
  if (/iP(hone|ad)/.test(window.navigator.userAgent)) {
    document.body.addEventListener('touchstart', function() {}, false);
  }
};

The alternative is to add the touch start listeners to all the interactable elements in the page, alleviating some of the performance concerns.

window.onload = function() {
  if (/iP(hone|ad)/.test(window.navigator.userAgent)) {
    var elements = document.querySelectorAll('button');
    var emptyFunction = function() {};

    for (var i = 0; i < elements.length; i++) {
        elements[i].addEventListener('touchstart', emptyFunction, false);
    }
  }
};