Kayce Basques on web.dev

Agrofy: A 70% improvement in LCP correlated to a 76% reduction in load abandonment

2021-03-01T00:00:00Z

Agrofy is an online marketplace for Latin America's agribusiness market. They match up buyers and sellers of farm machines, land, equipment, and financial services. In Q3 2020 a 4-person development team at Agrofy spent a month optimizing their website because they hypothesized that improved performance would lead to reduced bounce rates. They specifically focused on improving LCP, which is one of the Core Web Vitals. These performance optimizations led to a 70% improvement in LCP, which correlated to a 76% reduction in load abandonment (from 3.8% to 0.9%).

70_%

Lower LCP

76_%

Lower load abandonment

Problem #

While studying their business metrics, a development team at Agrofy noticed that their bounce rates seemed higher than industry benchmarks. Technical debt was also increasing in the website codebase.

Solution #

The Agrofy team pitched their executives and got buy-in to:

Migrate from an older, deprecated framework to a newer, actively supported one.
Optimize the load performance of the new codebase.

The migration took 2 months. Aside from the 4-person development team mentioned earlier, this migration also involved product and UX specialists and a software architect. The optimization project took the 4-person development team 1 month. They focused on LCP, CLS (another Core Web Vitals metric), and FCP. Specific optimizations included:

Lazy loading all non-visible elements with the Intersection Observer API.
Delivering static resources faster with a content delivery network.
Lazy loading images with loading="lazy".
Server-side rendering of critical rendering path content.
Preloading and preconnecting critical resources to minimize handshake times.
Using real user monitoring (RUM) tools to identify which product detail pages were experiencing lots of layout shifts and then make adjustments to the codebase's architecture.

Check out the Agrofy engineering blog post for more technical details.

After enabling the new codebase on 20% of traffic, they launched the new site to all visitors in early September 2020.

Results #

The development team's optimizations led to measurable improvements in many different metrics:

LCP improved 70%.
CLS improved 72%.
Blocking JS requests reduced 100% and blocking CSS requests 80%.
Long tasks reduced 72%.
First CPU Idle improved 25%.

Over the same time frame, real user monitoring data (also known as field data) showed that the load abandonment rate on product detail pages dropped 76%, from 3.8% to 0.9%:

Load abandonment rate trend on product detail page.

Case study guidelines

2021-01-26T00:00:00Z

The goal of this guide is to help you write effective case studies.

web.dev's goal for case studies #

Our goal is to persuade web developers to make a change. The best way to do that is to focus on how the reader's life will get better if they make the change.

We understand that the partner's motivation is usually to increase awareness of their company or product. We believe that it's in the partner's best interest to not focus on themselves too much. By focusing on what's in it for web developers (the people who are most likely to read our case studies), we maximize the odds that people actually read and share the case study.

Find a compelling correlation #

A very effective approach for case study messaging is to highlight a correlation between the changes that the web developers made and a business metric improvement. Examples:

The reason this is important is because web development teams often need to persuade business stakeholders before they can make any significant changes to their website or processes. Business stakeholders won't agree to these changes unless there is evidence that the ROI is worthwhile.

Organize the beginning of your content as an inverted pyramid #

The inverted pyramid is a journalism best practice. Organize your content so that the most important information is at the top, and the least important at the bottom.

Think about it this way: 100K people might see a link to your case study on social media. 50K of those people actually open the link. And only 5K actually read through the whole thing.

Title #

The title is the single most important part of your case study because it's what the greatest amount of people see. It should be focused around your compelling correlation.

In other words, most case study titles should have these 3 parts:

The name of the company
The web development change(s) they made
The business metric improvement correlated to the change(s)

Subtitle #

The subtitle (or subhead) is the text that appears below the title. See subhead for an example. It also shows up on the blog homepage and is the text that we suggest to search engines to present on Search Engine Results Pages. Therefore this is the second most important part of your case study (because it's the second-most-seen text).

The subtitle is a good place to share other noteworthy correlations (example). Or, you can elaborate on the story that you began to tell in the title (example).

Introduction #

The reader, especially business executives, expect the first paragraphs of the content to provide a summary of the most important information. A good way to ensure that you provide all important information is to systemetically answer the Five Ws and How.

Avoid the urge to talk too much about the partner. It's OK to share some context (1-3 sentences) so that the readers understand what the company/product does. If it gets too long, though, it begins to sound like a sales pitch.

General organization #

After you have optimized your title, subtitle, and introduction, we can give you more flexibility around how you organize the rest of your ideas. In other words, you don't need to strictly follow an inverted pyramid approach throughout the entire case study.

The Scale on web case studies use the following pattern:

Highlighting the opportunity
The tools they used
Overall business results

The BookMyShow case study demonstrates another common organization:

Challenge
Solution

Hero images #

A well-designed hero image is a good way to make your case study look attractive and professional. In general, the web.dev team doesn't have resources to create custom hero images for you. See Hero images for dimension requirements.

Cross-posting #

If your case study has already been published on another site and you'd like to mirror it on web.dev, then whether your case study gets published here becomes more complicated.

In particular, requesting to cross-post articles that have already been posted on self-publishing outlets such as personal blogs are problematic, as the web.dev editorial team has a rigorous editorial process. This means that the final version of your proposed case study will likely be significantly different than what you have already published.

There is also the concern of what version is canonical. While the web.dev team wants to publish compelling case studies, canonicity is important, as it can raise issues when it comes to how your article is indexed if you don't take care to mark which version is canonical.

Generally speaking, you should avoid proposing case studies which have already been published elsewhere. While there may be exceptions to this rule, they are few and far between, and must be cases in which the original version has not been self-published, and is already marked as the canonical version.

Examples #

The Scale on web case studies case studies are the best case studies we've produced to date, in terms of aligning with the case study guidelines.

You can check out all of our case studies for more ideas, but be aware that they may not follow the case study guidelines as closely as the Scale on web case studies do.

Deliverables #

When submitting the first draft of your case study, please submit it as a Google Doc. This helps to ensure that editorial feedback is communicated in a consistent way in a format that is familiar for Googlers.

While not strictly necessary, it helps to streamline the process if source files for figures can be provided. However, if the person responsible for writing the case study doesn't have domain knowledge in using image editors, the technical writing team is capable of extracting images from Google Docs if necessary.

Codelab: Build a push notification client

2020-11-11T00:00:00Z

This codelab shows you, step-by-step, how to build a push notification client. By the end of the codelab you'll have a client that:

Subscribes the user to push notifications.
Receives push messages and displays them as notifications.
Unsubscribes the user from push notifications.

This codelab is focused on helping you learn by doing and doesn't talk about concepts much. Check out How do push notifications work? to learn about push notification concepts.

The server code of this codelab is already complete. You'll only be implementing the client in this codelab. To learn how to implement a push notification server, check out Codelab: Build a push notification server.

Check out push-notifications-client-codelab-complete (source) to see the complete code.

Browser compatibility #

This codelab is known to work with the following operating system and browser combinations:

Windows: Chrome, Edge
macOS: Chrome, Firefox
Android: Chrome, Firefox

This codelab is known to not work with the following operating systems (or operating system and browser combinations):

macOS: Brave, Edge, Safari
iOS

Setup #

Get an editable copy of the code #

The code editor that you see to the right of these instructions will be called the Glitch UI throughout this codelab.

Click Remix to Edit to make the project editable.

Set up authentication #

Before you can get push notifications working, you need to set up your server and client with authentication keys. See Sign your web push protocol requests to learn why.

In the Glitch UI click Tools and then click Terminal to open the Glitch Terminal.
In the Glitch Terminal, run npx web-push generate-vapid-keys. Copy the private key and public key values.
In the Glitch UI open .env and update VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY. Set VAPID_SUBJECT to mailto:test@test.test. All of these values should be wrapped in double quotes. After making your updates, your .env file should look similar to this:

VAPID_PUBLIC_KEY="BKiwTvD9HA…"
VAPID_PRIVATE_KEY="4mXG9jBUaU…"
VAPID_SUBJECT="mailto:test@test.test"

Close the Glitch Terminal.

Open public/index.js.
Replace VAPID_PUBLIC_KEY_VALUE_HERE with the value of your public key.

Register a service worker #

Your client will eventually need a service worker to receive and display notifications. It's best to register the service worker as early as possible. See Receive and display the pushed messages as notifications for more context.

Replace the // TODO add startup logic here comment with the following code:

// TODO add startup logic here
if ('serviceWorker' in navigator && 'PushManager' in window) {
  navigator.serviceWorker.register('./service-worker.js').then(serviceWorkerRegistration => {
    console.info('Service worker was registered.');
    console.info({serviceWorkerRegistration});
  }).catch(error => {
    console.error('An error occurred while registering the service worker.');
    console.error(error);
  });
  subscribeButton.disabled = false;
} else {
  console.error('Browser does not support service workers or push messages.');
}

subscribeButton.addEventListener('click', subscribeButtonHandler);
unsubscribeButton.addEventListener('click', unsubscribeButtonHandler);

To preview the site, press View App. Then press Fullscreen .

Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.
Click the Console tab. You should see the message Service worker was registered. logged to the Console.

Request push notification permission #

You should never request permission to send push notifications on page load. Instead, your UI should ask the user if they want to receive push notifications. Once they explicitly confirm (with a button click, for example) then you can start the formal process for getting push notification permission from the browser.

In the Glitch UI click View Source to return to your code.
In public/index.js replace the // TODO comment in subscribeButtonHandler() with the following code:

// TODO
// Prevent the user from clicking the subscribe button multiple times.
subscribeButton.disabled = true;
const result = await Notification.requestPermission();
if (result === 'denied') {
  console.error('The user explicitly denied the permission request.');
  return;
}
if (result === 'granted') {
  console.info('The user accepted the permission request.');
}

Go back to the app tab and click Subscribe to push. Your browser or operating system will probably ask you if you want to let the website send you push notifications. Click Allow (or whatever equivalent phrase your browser/OS uses). In the Console you should see a message indicating whether the request was accepted or denied.

The subscription process involves interacting with a web service controlled by the browser vendor that's called a push service. Once you get the push notification subscription information you need to send it to a server and have the server store it in a database long-term. See Subscribe the client to push notifications for more context about the subscription process.

Add the following highlighted code to subscribeButtonHandler():

subscribeButton.disabled = true;
const result = await Notification.requestPermission();
if (result === 'denied') {
  console.error('The user explicitly denied the permission request.');
  return;
}
if (result === 'granted') {
  console.info('The user accepted the permission request.');
}
const registration = await navigator.serviceWorker.getRegistration();
const subscribed = await registration.pushManager.getSubscription();
if (subscribed) {
  console.info('User is already subscribed.');
  notifyMeButton.disabled = false;
  unsubscribeButton.disabled = false;
  return;
}
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlB64ToUint8Array(VAPID_PUBLIC_KEY)
});
notifyMeButton.disabled = false;
fetch('/add-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(subscription)
});

The userVisibleOnly option must be true. It may one day be possible to push messages without displaying user-visible notifications (silent pushes) but browsers currently don't allow that capability because of privacy concerns.

The applicationServerKey value relies on a utility function that converts a base64 string to a Uint8Array. This value is used for authentication between your server and the push service.

Unsubscribe from push notifications #

After a user has subscribed to push notifications, your UI needs to provide a way to unsubscribe in case the user changes their mind and no longer wants to receive push notifications.

Replace the // TODO comment in unsubscribeButtonHandler() with the following code:

// TODO
const registration = await navigator.serviceWorker.getRegistration();
const subscription = await registration.pushManager.getSubscription();
fetch('/remove-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({endpoint: subscription.endpoint})
});
const unsubscribed = await subscription.unsubscribe();
if (unsubscribed) {
  console.info('Successfully unsubscribed from push notifications.');
  unsubscribeButton.disabled = true;
  subscribeButton.disabled = false;
  notifyMeButton.disabled = true;
}

Receive a push message and display it as a notification #

As mentioned before, you need a service worker to handle the receiving and displaying of messages that were pushed to the client from your server. See Receive and display the pushed messages as notifications for more detail.

Open public/service-worker.js and replace the // TODO comment in the service worker's push event handler with the following code:

// TODO
let data = event.data.json();
const image = 'https://cdn.glitch.com/614286c9-b4fc-4303-a6a9-a4cef0601b74%2Flogo.png?v=1605150951230';
const options = {
  body: data.options.body,
  icon: image
}
self.registration.showNotification(
  data.title, 
  options
);

Go back to the app tab.
Click Notify me. You should receive a push notification.
Try opening the URL of your app tab on other browsers (or even other devices), going through the subscription workflow, and then clicking Notify all. You should receive the same push notification on all of the browsers that you subscribed. Refer back to Browser compatibility to see a list of browser/OS combinations that are known to work or not work.

You can customize the notification in lots of ways. See the parameters of ServiceWorkerRegistration.showNotification() to learn more.

Open a URL when a user clicks a notification #

In the real-world, you'll probably use the notification as a way to re-engage your user and prompt them to visit your site. To do that, you need to configure your service worker a bit more.

Replace the // TODO comment in the service worker's notificationclick event handler with the following code:

// TODO
event.notification.close();
event.waitUntil(self.clients.openWindow('https://web.dev'));

Go back to the app tab, send yourself another notification, and then click the notification. Your browser should open a new tab and load https://web.dev.

Next steps #

Look at ServiceWorkerRegistration.showNotification() to discover all of the different ways you can customize notifications.
Read Push notifications overview for a deeper conceptual understanding of how push notifications work.
Check out Codelab: Build a push notification server to learn how to build a server that manages subscriptions and sends web push protocol requests.
Try out Notification Generator to test out all the ways you can customize notifications.

Codelab: Build a push notification server

2020-11-11T00:00:00Z

This codelab shows you, step-by-step, how to build a push notification server. By the end of the codelab you'll have a server that:

Keeps track of push notification subscriptions (i.e. the server creates a new database record when a client opts in to push notifications, and it deletes an existing database record when a client opts out)
Sends a push notification to a single client
Sends a push notification to all subscribed clients

This codelab is focused on helping you learn by doing and doesn't talk about concepts much. Check out How do push notifications work? to learn about push notification concepts.

The client code of this codelab is already complete. You'll only be implementing the server in this codelab. To learn how to implement a push notification client, check out Codelab: Build a push notification client.

Check out push-notifications-server-codelab-complete (source) to see the complete code.

Browser compatibility #

This codelab is known to work with the following operating system and browser combinations:

Windows: Chrome, Edge
macOS: Chrome, Firefox
Android: Chrome, Firefox

This codelab is known to not work with the following operating systems (or operating system and browser combinations):

macOS: Brave, Edge, Safari
iOS

Application stack #

The server is built on top of Express.js.
The web-push Node.js library handles all of the push notification logic.
Subscription data is written to a JSON file using lowdb.

You don't have to use any of these technologies to implement push notifications. We chose these technologies because they provide a reliable codelab experience.

Setup #

Get an editable copy of the code #

The code editor that you see to the right of these instructions will be called the Glitch UI throughout this codelab.

Click Remix to Edit to make the project editable.

Set up authentication #

Before you can get push notifications working, you need to set up your server and client with authentication keys. See Sign your web push protocol requests to learn why.

Open the Glitch terminal by clicking Tools and then clicking Terminal.
In the terminal, run npx web-push generate-vapid-keys. Copy the private key and public key values.
Open .env and update VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY. Set VAPID_SUBJECT to mailto:test@test.test. All of these values should be wrapped in double quotes. After making your updates, your .env file should look similar to this:

VAPID_PUBLIC_KEY="BKiwTvD9HA…"
VAPID_PRIVATE_KEY="4mXG9jBUaU…"
VAPID_SUBJECT="mailto:test@test.test"

Close the Glitch terminal.

Open public/index.js.
Replace VAPID_PUBLIC_KEY_VALUE_HERE with the value of your public key.

Manage subscriptions #

Your client handles most of the subscription process. The main things your server needs to do are save new push notification subscriptions and delete old subscriptions. These subscriptions are what enable you to push messages to clients in the future. See Subscribe the client to push notifications for more context about the subscription process.

Save new subscription information #

To preview the site, press View App. Then press Fullscreen .

Click Register service worker in the app tab. In the status box you should see a message similar to this:

Service worker registered. Scope: https://desert-cactus-sunset.glitch.me/

In the app tab click Subscribe to push. Your browser or operating system will probably ask you if you want to let the website send you push notifications. Click Allow (or whatever equivalent phrase your browser/OS uses). In the status box you should see a message similar to this:

Service worker subscribed to push.  Endpoint: https://fcm.googleapis.com/fcm/send/…

Go back to your code by clicking View Source in the Glitch UI.
Open the Glitch Logs by clicking Tools and then clicking Logs. You should see /add-subscription followed by some data. /add-subscription is the URL that the client sends a POST request to when it wants to subscribe to push notifications. The data that follows is the client's subscription information that you need to save.
Open server.js.
Update the /add-subscription route handler logic with the following code:

app.post('/add-subscription', (request, response) => {
  console.log('/add-subscription');
  console.log(request.body);
  console.log(`Subscribing ${request.body.endpoint}`);
  db.get('subscriptions')
    .push(request.body)
    .write();
  response.sendStatus(200);
});

Delete old subscription information #

Go back to the app tab.
Click Unsubscribe from push.
Look at the Glitch Logs again. You should see /remove-subscription followed by the client's subscription information.
Update the /remove-subscription route handler logic with the following code:

app.post('/remove-subscription', (request, response) => {
  console.log('/remove-subscription');
  console.log(request.body);
  console.log(`Unsubscribing ${request.body.endpoint}`);
  db.get('subscriptions')
    .remove({endpoint: request.body.endpoint})
    .write();
  response.sendStatus(200);
});

Send notifications #

As explained in Send a push message, your server doesn't actually send the push messages directly to clients. Rather, it relies on a push service to do that. Your server basically just kicks off the process of pushing messages to clients by making web service requests (web push protocol requests) to a web service (the push service) owned by the browser vendor that your user uses.

Update the /notify-me route handler logic with the following code:

app.post('/notify-me', (request, response) => {
  console.log('/notify-me');
  console.log(request.body);
  console.log(`Notifying ${request.body.endpoint}`);
  const subscription = 
      db.get('subscriptions').find({endpoint: request.body.endpoint}).value();
  sendNotifications([subscription]);
  response.sendStatus(200);
});

Update the sendNotifications() function with the following code:

function sendNotifications(subscriptions) {
  // TODO
  // Create the notification content.
  const notification = JSON.stringify({
    title: "Hello, Notifications!",
    options: {
      body: `ID: ${Math.floor(Math.random() * 100)}`
    }
  });
  // Customize how the push service should attempt to deliver the push message.
  // And provide authentication information.
  const options = {
    TTL: 10000,
    vapidDetails: vapidDetails
  };
  // Send a push message to each client specified in the subscriptions array.
  subscriptions.forEach(subscription => {
    const endpoint = subscription.endpoint;
    const id = endpoint.substr((endpoint.length - 8), endpoint.length);
    webpush.sendNotification(subscription, notification, options)
      .then(result => {
        console.log(`Endpoint ID: ${id}`);
        console.log(`Result: ${result.statusCode}`);
      })
      .catch(error => {
        console.log(`Endpoint ID: ${id}`);
        console.log(`Error: ${error} `);
      });
  });
}

Update the /notify-all route handler logic with the following code:

app.post('/notify-all', (request, response) => {
  console.log('/notify-all');
  response.sendStatus(200);
  console.log('Notifying all subscribers');
  const subscriptions =
      db.get('subscriptions').cloneDeep().value();
  if (subscriptions.length > 0) {
    sendNotifications(subscriptions);
    response.sendStatus(200);
  } else {
    response.sendStatus(409);
  }
});

Go back to the app tab.
Click Unsubscribe from push and then click Subscribe to push again. This is only necessary because, as mentioned before, Glitch restarts the project every time you edit the code and the project is configured to delete the database on startup.
Click Notify me. You should receive a push notification. The title should be Hello, Notifications! and the body should be ID: <ID> where <ID> is a random number.
Open your app on other browsers or devices and try subscribing them to push notifications and then clicking the Notify all button. You should receive the same notification on all of your subscribed devices (i.e. the ID in the body of the push notification should be the same).

Next steps #

Read Push notifications overview for a deeper conceptual understanding of how push notifications work.
Check out Codelab: Build a push notification client to learn how to build a client that requests notification permission, subscribes the device to receive push notifications, and uses a service worker to receive push messages and display the messages as notifications.

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 #

How to create high-performance CSS animations

2020-10-06T00:00:00Z

This guide teaches you how to create high-performance CSS animations.

See Why are some animations slow? to learn the theory behind these recommendations.

Browser compatibility #

All of the CSS properties that this guide recommends have good cross-browser support.

Move an element #

To move an element, use the translate or rotation keyword values of the transform property.

For example to slide an item into view, use translate.

.animate {
  animation: slide-in 0.7s both;
}

@keyframes slide-in {
  0% {
    transform: translateY(-1000px);
  }
  100% {
    transform: translateY(0);
  }
}

Items can also be rotated, in the example below 360 degrees.

.animate {
  animation: rotate 0.7s ease-in-out both;
}

@keyframes rotate {
  0% {
    transform: rotate(0);
  }
  100% {
    transform: rotate(360deg);
  }
}

Resize an element #

To resize an element, use the scale keyword value of the transform property.

.animate {
  animation: scale 1.5s both;
}

@keyframes scale {
  50% {
    transform: scale(0.5);
  }
  100% {
    transform: scale(1);
  }
}

Change an element's visibility #

To show or hide an element, use opacity.

.animate {
  animation: opacity 2.5s both;
}

@keyframes opacity {
  0% {
    opacity: 1;
  }
  50% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

Avoid properties that trigger layout or paint #

Before using any CSS property for animation (other than transform and opacity), determine the property's impact on the rendering pipeline. Avoid any property that triggers layout or paint unless absolutely necessary.

Force layer creation #

As explained in Why are some animations slow?, by placing elements on a new layer they can be repainted without also requiring the rest of the layout to be repainted.

Browsers will often make good decisions about which items should be placed on a new layer, but you can manually force layer creation with the will-change property. As the name suggests, this property tells the browser that this element is going to be changed in some way.

In CSS this property can be applied to any selector:

body > .sidebar {
  will-change: transform;
}

However, the specification suggests this approach should only be taken for elements that are always about to change. If the above example was a sidebar the user could slide in and out, that might be the case. Some items on your page may not frequently change, and so it would be better to apply will-change using JavaScript at a point where it becomes likely the change will occur. You'll need to make sure to give the browser enough time to perform the optimizations needed and then remove the property once the changing has stopped.

If you need a way to force layer creation in one of the rare browsers that doesn't support will-change (most likely Internet Explorer at this point), you can set transform: translateZ(0).

Debug slow or janky animations #

Chrome DevTools and Firefox DevTools have lots of tools to help you figure out why your animations are slow or janky.

Check if an animation triggers layout #

An animation that moves an element using something other than transform, is likely to be slow. In the following example, I have achieved the same visual result animating top and left, and using transform.

Don't

.box {
  position: absolute;
  top: 10px;
  left: 10px;
  animation: move 3s ease infinite;
}

@keyframes move {
  50% {
     top: calc(90vh - 160px);
     left: calc(90vw - 200px);
  }
}

.box {
  position: absolute;
  top: 10px;
  left: 10px;
  animation: move 3s ease infinite;
}

@keyframes move {
  50% {
     transform: translate(calc(90vw - 200px), calc(90vh - 160px));
  }
}

You can test this in the following two Glitch examples, and explore performance using DevTools.

Before.
After.

Chrome DevTools #

Open the Performance panel.
Record runtime performance while your animation is happening.
Inspect the Summary tab.

If you see a nonzero value for Rendering in the Summary tab, it may mean that your animation is causing the browser to do layout work.

The animation-with-top-left example causes rendering work.

The animation-with-transform example does not cause rendering work.

Firefox DevTools #

In Firefox DevTools the Waterfall can help you to understand where the browser is spending time.

Open the Performance panel.
In the panel Start Recording Performance while your animation is happening.
Stop the recording and inspect the Waterfall tab.

If you see entries for Recalculate Style then the browser is having to begin at the start of the rendering waterfall.

Check if an animation is dropping frames #

Open the Rendering tab of Chrome DevTools.
Enable the FPS meter checkbox.
Watch the values as your animation runs.

At the top of the FPS meter UI you see the label Frames. Below that you see a value along the lines of 50% 1 (938 m) dropped of 1878. A high-performance animation will have a high percentage, e.g. 99%. A high percentage means that few frames are being dropped and the animation will look smooth.

The animation-with-top-left example causes 50% of frames to be dropped

The animation-with-transform example causes only 1% of frames to be dropped.

Check if an animation triggers paint #

When it comes to painting, some things are more expensive than others. For example, anything that involves a blur (like a shadow, for example) is going to take longer to paint than drawing a red box. In terms of CSS, however, this isn't always obvious: background: red; and box-shadow: 0, 4px, 4px, rgba(0,0,0,0.5); don't necessarily look like they have vastly different performance characteristics, but they do.

Browser DevTools can help you to identify which areas need to be repainted, and performance issues related to painting.

Chrome DevTools #

Open the Rendering tab of Chrome DevTools.
Select Paint Flashing.
Move the pointer around the screen.

In this example from Google Maps you can see the elements that will be repainted.

If you see the whole screen flashing, or areas that you don't think should change highlighted then you can do some investigation.

If you need to dig into whether a particular property is causing performance issues due to painting, the paint profiler in Chrome DevTools can help.

Firefox DevTools #

Open Settings and add a Toolbox button for Toggle paint flashing.
On the page you want to inspect, toggle the button on and move your mouse or scroll to see highlighted areas.

Conclusion #

Where possible restrict animations to opacity and transform in order to keep animations on the compositing stage of the rendering path. Use DevTools to check which stage of the path is being affected by your animations.

Use the paint profiler to see if any paint operations are particularly expensive. If you find anything, see if a different CSS property will give the same look and feel with better performance.

Use the will-change property sparingly, and only if you encounter a performance issue.

Add an Apple touch icon to your Progressive Web App

2019-08-26T00:00:00Z

Safari for iOS users can manually add Progressive Web Apps (PWAs) to their home screen. The icon that appears on the iOS home screen when a PWA is added is called the Apple touch icon. This codelab shows you how to add an Apple touch icon to a PWA. It assumes that you have access to an iOS device.

Measure #

Open the example app in a new tab:

Click Remix to Edit to make the project editable.
To preview the site, press View App. Then press Fullscreen .
Note the URL of your example app. It'll be something like https://example.glitch.me.

Run a Lighthouse PWA audit on your example app in Chrome DevTools:

Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.
Click the Lighthouse tab.
Make sure the Progressive Web App checkbox is selected in the Categories list.
Click the Generate report button.

In the PWA Optimized section, Lighthouse reports that the example app doesn't provide a valid Apple touch icon.

The Does not provide a valid apple-touch-icon audit

Add the example app to an iOS home screen #

To demonstrate how an Apple touch icon provides a more polished user experience, first try adding the example app to your iOS device's home screen when an Apple touch icon hasn't been specified.

Open Safari for iOS.
Open the URL of your example app. This is the URL like https://example.glitch.me that you noted earlier.
Tap Share > Add to Home Screen. You'll probably have to swipe left to see this option.
Tap Add.

Because the site hasn't specified an Apple touch icon, iOS just generates an icon for the site from the page's content.

An auto-generated home screen icon.

Add an Apple touch icon to the example app #

Uncomment the <link rel="apple-touch-icon"> tag at the bottom of the <head> of index.html.

    …
    <link rel="stylesheet" href="/index.css">
    <link rel="shortcut icon" href="https://cdn.glitch.com/49d34dc6-8fbd-46bb-8221-b99ffd36f1af%2Ftouchicon-180.png?v=1566411949736">
    <!-- <link rel="apple-touch-icon" href="https://cdn.glitch.com/49d34dc6-8fbd-46bb-8221-b99ffd36f1af%2Ftouchicon-180.png?v=1566411949736"> -->
    <link rel="apple-touch-icon" href="https://cdn.glitch.com/49d34dc6-8fbd-46bb-8221-b99ffd36f1af%2Ftouchicon-180.png?v=1566411949736">
  </head>
  …

Add the example app to an iOS home screen (again) #

Try adding the example app to an iOS home screen again. This time, a proper icon is generated for the site. If you audit the page again with Lighthouse you'll also see that the Does not provide a valid apple-touch-icon audit now passes.

The Apple touch icon.

Discover performance opportunities with Lighthouse

2018-11-05T00:00:00Z

Lighthouse is a tool that helps you measure and find ways to improve a page's performance. Here's the general workflow for how you use Lighthouse:

You tell Lighthouse what page to audit.
Lighthouse loads that page and records how long the page takes to hit various performance milestones. These milestones are called metrics.
Lighthouse gives you a report on how the page did. The report provides a score for each metric and a list of opportunities which, if you implement them, should make the page load faster.

Your mission is to improve your metrics scores over time, or at least make sure that they don't get worse. There's no way to work on metrics directly, though. Instead, you follow the opportunities that Lighthouse provides. Working on those opportunities tends to improve your metrics scores.

Run Lighthouse from your profile page #

Run Lighthouse from your web.dev profile page:

Provide any URL, and Lighthouse runs a series of audits generating a report of how well the page did.
Review the audits report to identify areas in which your page can be improved.
For each audit, you'll find guidance and immediate steps you can take to improve your scores.

Run Lighthouse from Chrome DevTools #

Chrome DevTools is the set of web developer tools that are built directly into the Google Chrome browser. You don't have to download anything to get DevTools. If you have Chrome, then you have DevTools.

In Chrome, go to the page that you want to audit.
Press `Control+Shift+J` (or `Command+Option+J` on Mac) to open DevTools.

Click the Audits tab. If you don't see this tab, click the » symbol and then select Audits from the list. Lighthouse is the engine that powers the Audits panel. That's why you see an image of a lighthouse.

Make sure the Mobile radio button is selected. When Lighthouse audits your page, it will simulate a mobile device's viewport and user agent string.
Make sure the Performance checkbox is enabled. You can enable or disable the rest of the checkboxes in the Audits section. If you enable them, then you'll see a bunch of opportunities on ways to improve those other aspects of your page.
Make sure the Simulated Fast 3G, 4x CPU Slowdown radio button is selected. Lighthouse doesn't actually throttle your network or CPU while it loads the page. Instead, it looks at how long the page took to load under normal conditions, and then it estimates how long it would have taken on a fast 3G network with a CPU that is 4 times less powerful than your machine's.
Make sure that the Clear Storage checkbox is enabled. This option forces Lighthouse to go to the network for every page resource, which is how first-time visitors experience the page.
Click Run Audits. After 5 to 10 seconds, Lighthouse shows you a report.

For example, if you run some audits with Simulated Fast 3G, 4x CPU Slowdown throttling enabled and then other times you run audits with throttling disabled, your metrics scores will be significantly lower when you have throttling enabled. You might spend a lot of time trying to figure out why your page is so much slower now, when in reality the only thing that changed was your configuration.

Understand your report #

The top-right of your report lists your overall performance score. 100 is a perfect score. Below the overall score are the metrics scores. Lighthouse v3 Scoring Guide explains how each metric score contributes to the overall score.

Hover over a metric to learn more about it. Click Learn more to read documentation about it.

Below your metrics scores you see screenshots of how the page looked while it loaded.

Below the screenshots you see opportunities for improving the page's performance.

Click an opportunity to learn more about it.

Next steps #

Try using Lighthouse to audit your page, either from your profile page or from Chrome DevTools. Implement one of the opportunities, and then audit your page again to see how the change affected your report. Your metrics scores should ideally be a little better, and Lighthouse should no longer be flagging that opportunity as something to work on.

Running Lighthouse yourself is great for spot-checking issues, but ultimately you'll want to setup continuous monitoring to make sure your site stays healthy. To track your Lighthouse progress over time add your site to the your profile.

Why HTTPS matters

2015-11-23T00:00:00Z

You should always protect all of your websites with HTTPS, even if they don't handle sensitive communications. Aside from providing critical security and data integrity for both your websites and your users' personal information, HTTPS is a requirement for many new browser features, particularly those required for progressive web apps.

Summary #

Intruders both malignant and benign exploit every unprotected resource between your websites and users.
Many intruders look at aggregate behaviors to identify your users.
HTTPS doesn't just block misuse of your website. It's also a requirement for many cutting-edge features and an enabling technology for app-like capabilities such as service workers.

HTTPS protects the integrity of your website #

HTTPS helps prevent intruders from tampering with the communications between your websites and your users' browsers. Intruders include intentionally malicious attackers, and legitimate but intrusive companies, such as ISPs or hotels that inject ads into pages.

Intruders exploit unprotected communications to trick your users into giving up sensitive information or installing malware, or to insert their own advertisements into your resources. For example, some third parties inject advertisements into websites that potentially break user experiences and create security vulnerabilities.

Intruders exploit every unprotected resource that travels between your websites and your users. Images, cookies, scripts, HTML… they're all exploitable. Intrusions can occur at any point in the network, including a user's machine, a Wi-Fi hotspot, or a compromised ISP, just to name a few.

HTTPS protects the privacy and security of your users #

HTTPS prevents intruders from being able to passively listen to communications between your websites and your users.

One common misconception about HTTPS is that the only websites that need HTTPS are those that handle sensitive communications. Every unprotected HTTP request can potentially reveal information about the behaviors and identities of your users. Although a single visit to one of your unprotected websites may seem benign, some intruders look at the aggregate browsing activities of your users to make inferences about their behaviors and intentions, and to de-anonymize their identities. For example, employees might inadvertently disclose sensitive health conditions to their employers just by reading unprotected medical articles.

HTTPS is the future of the web #

Powerful, new web platform features, such as taking pictures or recording audio with getUserMedia(), enabling offline app experiences with service workers, or building progressive web apps, require explicit permission from the user before executing. Many older APIs are also being updated to require permission to execute, such as the Geolocation API. HTTPS is a key component to the permission workflows for both these new features and updated APIs.

Read files in JavaScript

2010-06-18T00:00:00Z

Selecting and interacting with files on the user's local device is one of the most commonly used features of the web. It allows users to select files and upload them to a server, for example, uploading photos, or submitting tax documents, etc. But, it also allows sites to read and manipulate them without ever having to transfer the data across the network.

The modern File System Access API #

The File System Access API provides an easy way to both read from and write to files and directories on the user's local system. It's currently available in most Chromium-based browsers such as Chrome or Edge. To learn more about it, see the File System Access API article.

Since the File System Access API is not compatible with all browsers yet, check out browser-fs-access, a helper library that uses the new API wherever it is available, but falls back to legacy approaches when it is not.

Working with files, the classic way #

This guide shows you how to:

Select files
- Using the HTML input element
- Using a drag-and-drop zone
Read file metadata
Read a file's content

Select files #

HTML input element #

The easiest way for users to select files is using the <input type="file"> element, which is supported in every major browser. When clicked, it lets a user select a file, or multiple files if the multiple attribute is included, using their operating system's built-in file selection UI. When the user finishes selecting a file or files, the element's change event fires. You can access the list of files from event.target.files, which is a FileList object. Each item in the FileList is a File object.

<!-- The `multiple` attribute lets users select multiple files. -->
<input type="file" id="file-selector" multiple>
<script>
  const fileSelector = document.getElementById('file-selector');
  fileSelector.addEventListener('change', (event) => {
    const fileList = event.target.files;
    console.log(fileList);
  });
</script>

This example lets a user select multiple files using their operating system's built-in file selection UI and then logs each selected file to the console.

Limit the types of files users can select #

In some cases, you may want to limit the types of files users can select. For example, an image editing app should only accept images, not text files. To do that, add an accept attribute to the input element to specify which file types are accepted.

<input type="file" id="file-selector" accept=".jpg, .jpeg, .png">

Custom drag-and-drop #

In some browsers, the <input type="file"> element is also a drop target, allowing users to drag-and-drop files into your app. But, the drop target is small, and can be hard to use. Instead, once you've provided the core functionality using an <input type="file"> element, you can provide a large, custom drag-and-drop surface.

Choose your drop zone #

Your drop surface depends on the design of your application. You may only want part of the window to be a drop surface, or potentially the entire window.

Squoosh makes the entire window a drop zone.

Squoosh allows the user to drag and drop an image anywhere into the window, and clicking select an image invokes the <input type="file"> element. Whatever you choose as your drop zone, make sure it's clear to the user that they can drag and drop files onto that surface.

Define the drop zone #

To enable an element to be a drag-and-drop zone, you'll need to listen for two events, dragover and drop. The dragover event updates the browser UI to visually indicate that the drag-and-drop action is creating a copy of the file. The drop event is fired after the user drops the files onto the surface. Similar to the input element, you can access the list of files from event.dataTransfer.files, which is a FileList object. Each item in the FileList is a File object.

const dropArea = document.getElementById('drop-area');

dropArea.addEventListener('dragover', (event) => {
  event.stopPropagation();
  event.preventDefault();
  // Style the drag-and-drop as a "copy file" operation.
  event.dataTransfer.dropEffect = 'copy';
});

dropArea.addEventListener('drop', (event) => {
  event.stopPropagation();
  event.preventDefault();
  const fileList = event.dataTransfer.files;
  console.log(fileList);
});

event.stopPropagation() and event.preventDefault() stop the browser's default behavior and allow your code to run instead. Without them, the browser would otherwise navigate away from your page and open the files the user dropped into the browser window.

Check out Custom drag-and-drop for a live demonstration.

What about directories? #

Unfortunately, today there isn't a good way to access a directory.

The webkitdirectory attribute on the <input type="file"> element allows the user to choose a directory or directories. It's supported in most major browsers except for Firefox for Android.

If drag-and-drop is enabled, a user may try to drag a directory into the drop zone. When the drop event is fired, it will include a File object for the directory, but does not provide access any of the files within the directory.

Read file metadata #

The File object contains metadata about the file. Most browsers provide the file name, the size of the file, and the MIME type, though depending on the platform, different browsers may provide different, or additional information.

function getMetadataForFileList(fileList) {
  for (const file of fileList) {
    // Not supported in Safari for iOS.
    const name = file.name ? file.name : 'NOT SUPPORTED';
    // Not supported in Firefox for Android or Opera for Android.
    const type = file.type ? file.type : 'NOT SUPPORTED';
    // Unknown cross-browser support.
    const size = file.size ? file.size : 'NOT SUPPORTED';
    console.log({file, name, type, size});
  }
}

You can see this in action in the input-type-file demo.

Read a file's content #

To read a file, use FileReader, which enables you to read the content of a File object into memory. You can instruct FileReader to read a file as an array buffer, a data URL, or text.

function readImage(file) {
  // Check if the file is an image.
  if (file.type && !file.type.startsWith('image/')) {
    console.log('File is not an image.', file.type, file);
    return;
  }

  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    img.src = event.target.result;
  });
  reader.readAsDataURL(file);
}

The example above reads a File provided by the user, then converts it to a data URL, and uses that data URL to display the image in an img element. Check out the read-image-file demo to see how to verify that the user has selected an image file.

Monitor the progress of a file read #

When reading large files, it may be helpful to provide some UX to indicate how far the read has progressed. For that, use the progress event provided by FileReader. The progress event provides two properties, loaded (the amount read) and total (the amount to read).

function readFile(file) {
  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    const result = event.target.result;
    // Do something with result
  });

  reader.addEventListener('progress', (event) => {
    if (event.loaded && event.total) {
      const percent = (event.loaded / event.total) * 100;
      console.log(`Progress: ${Math.round(percent)}`);
    }
  });
  reader.readAsDataURL(file);
}

Hero image by Vincent Botta from Unsplash

Kayce Basques on web.dev

Agrofy: A 70% improvement in LCP correlated to a 76% reduction in load abandonment

Problem #

Solution #

Results #

Case study guidelines

web.dev's goal for case studies #

Find a compelling correlation #

Organize the beginning of your content as an inverted pyramid #

Title #

Subtitle #

Introduction #

General organization #

Hero images #

Cross-posting #

Examples #

Deliverables #

Codelab: Build a push notification client

Browser compatibility #

Setup #

Get an editable copy of the code #

Set up authentication #

Register a service worker #

Request push notification permission #

Subscribe to push notifications #

Unsubscribe from push notifications #

Receive a push message and display it as a notification #

Open a URL when a user clicks a notification #

Next steps #

Codelab: Build a push notification server

Browser compatibility #

Application stack #

Setup #

Get an editable copy of the code #

Set up authentication #

Manage subscriptions #

Save new subscription information #

Delete old subscription information #

Send notifications #

Next steps #

Push notifications overview

What are push notifications? #

Why use push notifications? #

How do push notifications work? #

Get permission to send push notifications #

Subscribe the client to push notifications #

Send a push message #

Encrypt the push message #

Sign your web push protocol requests #

Customize the delivery of the push message #

Receive and display the pushed messages as notifications #

Where to go next #

Code labs #

How to create high-performance CSS animations

Browser compatibility #

Move an element #

Resize an element #

Change an element's visibility #

Avoid properties that trigger layout or paint #

Force layer creation #

Debug slow or janky animations #

Check if an animation triggers layout #

Chrome DevTools #

Firefox DevTools #

Check if an animation is dropping frames #

Check if an animation triggers paint #

Chrome DevTools #

Firefox DevTools #

Conclusion #

Add an Apple touch icon to your Progressive Web App

Measure #

Add the example app to an iOS home screen #

Add an Apple touch icon to the example app #

Add the example app to an iOS home screen (again) #

Discover performance opportunities with Lighthouse

Run Lighthouse from your profile page #

Run Lighthouse from Chrome DevTools #

Understand your report #

Next steps #

Why HTTPS matters