Features gated by user activation
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 user interaction with the UI.
More precisely, an activation triggering input event is an event which:
- has the
isTrusted
attribute set totrue
, and - is an event of the following types:
keydown
(except for the Esc key nor a shortcut key reserved by the user agent)mousedown
pointerdown
(ifpointerType
is "mouse")pointerup
(ifpointerType
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.
Transient activation
Transient activation is a window state that indicates a user has recently pressed a button, moved a mouse, used a menu, 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 Window.open()
).
APIs that require transient activation (list is not exhaustive):
Clients.openWindow()
Clipboard.read()
Clipboard.readText()
Clipboard.write()
Clipboard.writeText()
ContactsManager.select()
Document.requestStorageAccess()
DocumentPictureInPicture.requestWindow()
Element.requestFullScreen()
Element.requestPointerLock()
EyeDropper.open()
HID.requestDevice()
HTMLInputElement.showPicker()
HTMLSelectElement.showPicker()
HTMLVideoElement.requestPictureInPicture()
IdleDetector.requestPermission()
Keyboard.lock()
MediaDevices.getDisplayMedia()
MediaDevices.getViewportMedia()
MediaDevices.selectAudioOutput()
MediaStreamTrack.sendCaptureAction()
Navigator.share()
PaymentRequest.show()
PresentationRequest.start()
RemotePlayback.prompt()
Serial.requestPort()
USB.requestDevice()
Keyboard.lock()
Window.getScreenDetails()
Window.open()
Window.queryLocalFonts()
Window.showOpenFilePicker()
Window.showSaveFilePicker()
Window.showDirectoryPicker()
WindowClient.focus()
XRSystem.requestSession()
Sticky activation
Sticky activation is a window state that indicates a user has pressed a button, moved a mouse, 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):
beforeunload
eventNavigator.vibrate()
VirtualKeyboard.show()
- Autoplay of Media and Web Audio APIs (in particular for
AudioContexts
).
UserActivation API
To programmatically determine if a window has either sticky or transient user activation, the UserActivation
API provides two properties which are available using navigator.userActivation
:
UserActivation.hasBeenActive
indicates whether the window has sticky user activation.UserActivation.isActive
indicates whether the window has transient user activation.