Web permissions best practices

Marian Harbach

Thomas Steiner

Permission prompts are the web's main mechanism to protect users from powerful capabilities, that could be dangerous to their privacy and security. Browsers aim to confirm a user intends to allow a capability on a specific website. You can implement permissions for a number of APIs, including media capture (camera and microphone), geolocation, storage access, MIDI, and notifications.

Follow these practices when showing permission prompts to users, based on Chrome usage statistics and user research. When followed, your users should encounter fewer unnecessary prompts, which leads to fewer blocking decisions.

This document ends with some code patterns for permission-gated APIs and how to help users årecover from a blocked state.

Prompting best practices

Ask for permission after a user interaction, when users have the context to understand why you're asking and what benefit they get from allowing access.

When possible, provide alternative means to accomplish the same task. By carefully choosing the right moment to ask, you lower the chances that your users get into a blocked state that is hard to recover from.

Never ask on page load or without user interaction

Asking for permission on page load is equivalent to asking a customer for sensitive information as they walk into a physical store. Seeing a permission prompt, possibly among several other prompts for newsletter signup and cookie consent, is a jarring experience. Users won't understand why they are being asked and how they'll benefit.

Even if your web application can't work without access to a certain capability, give users a chance to understand why it's needed. For example, preface the permission prompt with why the prompt is needed and gives users a choice (for example, by providing alternative means to accomplish the same functionality). If you can't think of a better moment to ask for permission than on page load, there are a few examples later in this guide.

Asking for permission without prior user interaction is also ineffective. This is known as transient user activation. Chrome telemetry shows that 77% of permission prompts on desktop are shown without a signal of user intent, and consequently, only 12% of such prompts are allowed. After a user interaction, allow rates increase to 30%.

Only ask for permission after the user has interacted with the page.

Only ask when users can understand why

Permission decisions are often privacy decisions. Based on the contextual integrity framework, we know that privacy decisions are highly contextual. Understanding why access is necessary is critical. You should only request the capabilities you need to provide value, where users are likely to agree that they will find value. Additionally, ask for permission when it's apparent to your user why the capability is helpful. Make it easier for users to understand the usage context.

Our user research shows that users are substantially more likely to allow access when they understand why a site is asking for access and also perceive a benefit. We also find that users expect to explore unfamiliar sites first to better understand the value they can get in return for allowing access. They will often dismiss or ignore permission prompts in the meantime. With one-time permissions, they might allow for a single visit first. Support these behaviors in your application.

Provide alternatives

The outcome of some capabilities might not be helpful to users. For example, geolocation of a desktop device without a GPS sensor might return the wrong location because that person is connected to a VPN. Other users might not want to provide clipboard access because they prefer to stay in control and trigger these events with key combinations manually. In these situations, provide an alternative way to accomplish the same outcomes.

For example, if requesting geolocation permission, offer a text field where users can enter a zip code or address. Allow elements to be selected and copied to the clipboard with a keyboard shortcut or the context menu. For notifications, offer email instead of push notifications.

A useful pattern is to use the alternative UI also as the explanation for why access could be beneficial. Users who see an option to enter a location next to a button that triggers the geolocation API feel in control, because they understand they can type their address. Similarly, if there is a choice between receiving notifications through push or email, or joining a meeting without allowing camera and microphone access, users understand the tradeoffs.

Avoid blocked states

Once a user has permanently denied access to a permission-gated capability, browsers honor that decision. If it were possible to continue prompting for access, malicious sites would bombard users with prompts. Recovering from the blocked state of a capability intentionally takes effort. Avoid asking for permission in situations where users are unlikely to allow access.

A common way to do this is to use a so-called pre-prompt, where you explain to your users what is about to happen and why your application needs the capability you are going to request. Only when users react affirmatively to such a pre-prompt should you trigger the browser's permission prompt. There are situations where users may legitimately need to recover from that state. See the section Help users recover from a blocked state for more on this.

Pay attention to third-party content

Be aware of unexpected sources of permission prompts. Third-party scripts on your site might trigger unintended permission prompts. This can affect your user's experience, especially if prompts don't follow the best practices. To stay in control of the user experience, read the documentation for any third-party libraries and scripts that you add to your code.

When to ask for permission

Here are a few examples of moments that work well to ask for permission, following best practices:

• After a user clicks Use my location next to a form field, when manually entering an address.
• After a user subscribes to a video channel or posts, and clicks an affirmative button on a dialog describing that updates can be delivered as emails or notifications.
• After a user arrives at a page that prepares them to join a video call and answers affirmatively in a pre-prompt that they want to be seen and heard. Read more in the Google Meet case study.

Code patterns

Permission to use an API is granted through different means, depending on the API. Some older APIs use a model where the browser automatically asks for permission the first time you try to use the API. One example is the Geolocation API when calling navigator.geolocation.getCurrentPosition().

try {
  navigator.geolocation.getCurrentPosition((pos) => console.log(pos));
} catch (error) {
  console.error(error);
}

Other APIs use a model where you explicitly request permission first with a static method. A good example is Notification.requestPermission() for allowing notifications, or the less common DeviceOrientationEvent.requestPermission(), which is part of the Device Orientation Events API.

Some browsers automatically grant permission to certain APIs. For example, Chrome always allows access to a device orientation, whereas Safari shows a prompt.

const result = await DeviceOrientationEvent.requestPermission();
console.log(`The user's decision when prompted to use the Device Orientation
Events API was: ${result}.`);
if (result === 'granted') {
  /* Use the API. */
}

Check permissions state

To check if you can use a certain API, use the navigator.permissions.query() method from the Permissions API.

const result = await navigator.permissions.query({ name: 'geolocation' });
console.log(`The result of querying for the Geolocation API is:
${result.state}.`);
if (result.state === 'granted') {
  // Use the API.
}

Help users recover from a blocked state

To help users troubleshoot access problems, detect that they blocked access using the Permissions API and offer a guide on how to change their settings. When users interact with UI elements associated with a permissions-gated capability, use the check permission state and open a troubleshooting dialog.

The exact steps to change permission state vary by browser, so offer matching descriptions based on the user agent string for the most commonly used browsers.

In Chrome, users can change permissions from View site information > Site settings, found in the address bar. In some cases, they might have to reload the page before using a capability. In that case, a message bar appears across the top of the window that offers to reload the site.

Similar UIs for controlling permissions exist in other browsers, such as in Firefox.