ContextQMD
Back to Content

User activation

files/en-us/web/security/defenses/user_activation/index.md

latest5.6 KB
Original Source

To ensure applications are unable to abuse APIs that can create a bad user experience when the behavior is not desired, some APIs can only be used when the user is in an "active interaction" state, meaning the user is currently interacting with the web page, or has interacted with the page at least once. Browsers limit access to sensitive APIs like popups, fullscreen, or vibration APIs to active user interactions to prevent malicious scripts from abusing these features. This page lists web platform features available only after user activation.

A user activation either implies that the user is currently interacting with the page, or has completed an interaction since page load. Typically, this is a click on a button or some other interaction with the UI.

More precisely, an activation triggering input event is an event which:

  • has the isTrusted attribute set to true, and
  • is one of the following types:

    • keydown (except for the <kbd>Esc</kbd> key, browser-reserved shortcuts, and certain keys that do not produce user activation, which vary by keyboard, such as <kbd>Caps Lock</kbd>, <kbd>Num Lock</kbd>, and <kbd>Print Screen</kbd>. The behavior may vary by browser.

    • mousedown

    • pointerdown (if pointerType is "mouse")

    • pointerup (if pointerType is not "mouse")

    • touchend

If an activation has been triggered, the user agent differentiates between two types of user activation window states: sticky and transient.

Comparison between transient and sticky activation

The difference between transient and sticky activation is that transient activation only lasts for a short while, and may in some cases be consumed (deactivated) when a protected feature is used, while sticky activation persists until the end of the session.

Gating features on transient activation ensures that they are only available if directly triggered by a user. Sticky activation, by contrast, is primarily used to restrict features that should not automatically trigger on page load, such as popups.

Transient activation

{{Glossary("Transient activation")}} is a window state that indicates a user has recently pressed a button or performed some other user interaction. Transient activation expires after a timeout (if not renewed by further interaction) and may also be consumed by some APIs (like {{domxref("Window.open()")}}).

APIs that require transient activation (list is not exhaustive):

  • {{domxref("Clients.openWindow()")}}
  • {{domxref("Clipboard.read()")}}
  • {{domxref("Clipboard.readText()")}}
  • {{domxref("Clipboard.write()")}}
  • {{domxref("Clipboard.writeText()")}}
  • {{domxref("ContactsManager.select()")}}
  • {{domxref("Document.requestStorageAccess()")}}
  • {{domxref("DocumentPictureInPicture.requestWindow()")}}
  • {{domxref("Element.requestFullScreen()")}}
  • {{domxref("Element.requestPointerLock()")}}
  • {{domxref("EyeDropper.open()")}}
  • {{domxref("HID.requestDevice()")}}
  • {{domxref("HTMLInputElement.showPicker()")}}
  • {{domxref("HTMLSelectElement.showPicker()")}}
  • {{domxref("HTMLVideoElement.requestPictureInPicture()")}}
  • {{domxref("IdleDetector/requestPermission_static", "IdleDetector.requestPermission()")}}
  • {{domxref("Keyboard.lock()")}}
  • {{domxref("MediaDevices.getDisplayMedia()")}}
  • MediaDevices.getViewportMedia()
  • {{domxref("MediaDevices.selectAudioOutput()")}}
  • MediaStreamTrack.sendCaptureAction()
  • {{domxref("Navigator.share()")}}
  • {{domxref("PaymentRequest.show()")}}
  • {{domxref("PresentationRequest.start()")}}
  • {{domxref("RemotePlayback.prompt()")}}
  • {{domxref("Serial.requestPort()")}}
  • {{domxref("USB.requestDevice()")}}
  • {{domxref("Window.getScreenDetails()")}}
  • {{domxref("Window.open()")}}
  • {{domxref("Window.queryLocalFonts()")}}
  • {{domxref("Window.showDirectoryPicker()")}}
  • {{domxref("Window.showOpenFilePicker()")}}
  • {{domxref("Window.showSaveFilePicker()")}}
  • {{domxref("WindowClient.focus()")}}
  • {{domxref("XRSystem.requestSession()")}}

Sticky activation

{{Glossary("Sticky activation")}} is a window state that indicates a user has at some time in the session pressed a button, used a menu, or performed some other user interaction. It is not reset after it has been set initially (unlike transient activation).

APIs that require sticky activation (not exhaustive):

  • {{domxref("Window/beforeunload_event", "beforeunload")}} event
  • {{domxref("Navigator.vibrate()")}}
  • {{domxref("VirtualKeyboard.show()")}}
  • Autoplay of Media and Web Audio APIs (in particular for AudioContexts).
  • {{domxref("Clipboard.clipboardchange_event", "clipboardchange")}} events (these can also be enabled by the user granting the clipboard-read permission).

UserActivation API

To programmatically determine if a window has either sticky or transient user activation, the {{domxref("UserActivation")}} API provides two properties which are available using {{domxref("navigator.userActivation")}}:

  • {{domxref("UserActivation.hasBeenActive")}} indicates whether the window has sticky user activation.
  • {{domxref("UserActivation.isActive")}} indicates whether the window has transient user activation.

See also