diff --git a/files/en-us/glossary/sticky_activation/index.md b/files/en-us/glossary/sticky_activation/index.md index bdf13f1cf9f3bd2..bc9534f5ef63352 100644 --- a/files/en-us/glossary/sticky_activation/index.md +++ b/files/en-us/glossary/sticky_activation/index.md @@ -13,7 +13,10 @@ A page is considered "user activated" if a user is currently interacting with th See [Features gated by user activation](/en-US/docs/Web/Security/User_activation) for examples of APIs that require _sticky activation_. +See the {{domxref("UserActivation.hasBeenActive")}} property to programmatically access the current window's sticky activation state. + ## See also - [HTML Living Standard > Sticky activation](https://html.spec.whatwg.org/multipage/interaction.html#sticky-activation) - {{Glossary("Transient activation")}} +- {{domxref("UserActivation.hasBeenActive")}} diff --git a/files/en-us/glossary/transient_activation/index.md b/files/en-us/glossary/transient_activation/index.md index 907984e3a7811b1..bcd58cb6a261b7d 100644 --- a/files/en-us/glossary/transient_activation/index.md +++ b/files/en-us/glossary/transient_activation/index.md @@ -13,9 +13,12 @@ For example, scripts cannot arbitrarily launch a popup that requires _transient See [Features gated by user activation](/en-US/docs/Web/Security/User_activation) for examples of APIs that require _transient activation_. +See the {{domxref("UserActivation.isActive")}} property to programmatically access the current window's transient activation state. + > **Note:** Transient activation expires after a timeout (if not renewed by further interaction), and may also be "consumed" by some APIs. See {{Glossary("Sticky activation")}} for a user activation that doesn't reset after it has been set initially. ## See also - [HTML Living Standard > Transient activation](https://html.spec.whatwg.org/multipage/interaction.html#transient-activation) - {{Glossary("Sticky activation")}} +- {{domxref("UserActivation.isActive")}} diff --git a/files/en-us/web/api/navigator/index.md b/files/en-us/web/api/navigator/index.md index cd4c89c6d237be6..1caeb759d5a154a 100644 --- a/files/en-us/web/api/navigator/index.md +++ b/files/en-us/web/api/navigator/index.md @@ -71,6 +71,8 @@ _Doesn't inherit any properties._ - : Returns a {{domxref("ServiceWorkerContainer")}} object, which provides access to registration, removal, upgrade, and communication with the {{domxref("ServiceWorker")}} objects for the [associated document](https://html.spec.whatwg.org/multipage/browsers.html#concept-document-window). - {{domxref("Navigator.storage")}} {{ReadOnlyInline}} - : Returns the singleton {{domxref('StorageManager')}} object used for managing persistence permissions and estimating available storage on a site-by-site/app-by-app basis. +- {{domxref("Navigator.userActivation")}} {{ReadOnlyInline}} + - : Returns a {{domxref("UserActivation")}} object containing information about the current window's user activation state. - {{domxref("Navigator.userAgent")}} {{ReadOnlyInline}} - : Returns the user agent string for the current browser. - {{domxref("Navigator.userAgentData")}} {{ReadOnlyInline}} {{Experimental_Inline}} diff --git a/files/en-us/web/api/navigator/useractivation/index.md b/files/en-us/web/api/navigator/useractivation/index.md new file mode 100644 index 000000000000000..bb2e6d8ad272309 --- /dev/null +++ b/files/en-us/web/api/navigator/useractivation/index.md @@ -0,0 +1,55 @@ +--- +title: Navigator.userActivation +slug: Web/API/Navigator/userActivation +page-type: web-api-instance-property +tags: + - API + - Property + - Reference +browser-compat: api.Navigator.userActivation +--- + +{{APIRef("HTML DOM")}} {{SeeCompatTable}} + +The read-only **`userActivation`** property of the {{domxref("Navigator")}} interface returns a {{domxref("UserActivation")}} object which contains information about the current window's user activation state. + +## Value + +A {{domxref("UserActivation")}} object. + +## Examples + +### Checking if a user gesture was recently performed + +Use {{domxref("UserActivation.isActive")}} to check wether the user is currently interacting with the page ({{Glossary("Transient activation")}}). + +```js +if (navigator.userActivation.isActive) { + // proceed to request playing media, for example +} +``` + +### Checking if a user gesture was ever performed + +Use {{domxref("UserActivation.hasBeenActive")}} to check wether the user has ever interacted with the page ({{Glossary("Sticky activation")}}). + +```js +if (navigator.userActivation.hasBeenActive) { + // proceed with auto-playing an animation, for example +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("UserActivation")}} +- {{domxref("UserActivation.hasBeenActive")}} +- {{domxref("UserActivation.isActive")}} +- [Features gated by user activation](/en-US/docs/Web/Security/User_activation) diff --git a/files/en-us/web/api/useractivation/hasbeenactive/index.md b/files/en-us/web/api/useractivation/hasbeenactive/index.md new file mode 100644 index 000000000000000..15d3a13759dd73f --- /dev/null +++ b/files/en-us/web/api/useractivation/hasbeenactive/index.md @@ -0,0 +1,44 @@ +--- +title: UserActivation.hasBeenActive +slug: Web/API/UserActivation/hasBeenActive +page-type: web-api-instance-property +tags: + - API + - Property + - Reference +browser-compat: api.UserActivation.hasBeenActive +--- + +{{APIRef("HTML DOM")}} {{SeeCompatTable}} + +The read-only **`hasBeenActive`** property of the {{domxref("UserActivation")}} interface indicates whether the current window has sticky user activation (see {{Glossary("sticky activation")}}). + +## Value + +A boolean. + +## Examples + +### Checking if a user gesture was ever performed + +Use the `hasBeenActive` property to check wether the user has ever interacted with the page. + +```js +if (navigator.userActivation.hasBeenActive) { + // proceed with auto-playing an animation, for example +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("UserActivation")}} +- {{domxref("UserActivation.isActive")}} +- [Features gated by user activation](/en-US/docs/Web/Security/User_activation) diff --git a/files/en-us/web/api/useractivation/index.md b/files/en-us/web/api/useractivation/index.md new file mode 100644 index 000000000000000..5b7d9358469d18b --- /dev/null +++ b/files/en-us/web/api/useractivation/index.md @@ -0,0 +1,67 @@ +--- +title: UserActivation +slug: Web/API/UserActivation +page-type: web-api-interface +tags: + - API + - Interface + - Reference +browser-compat: api.UserActivation +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +The **`UserActivation`** interface allows querying information about a window's user activation state. + +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. + +There are two kinds of window user activation states: + +- {{Glossary("Transient activation")}} (user is currently interacting with the page) and +- {{Glossary("Sticky activation")}} (user has interacted at least once since page load). + +See [Features gated by user activation](/en-US/docs/Web/Security/User_activation) for more information and a list of APIs that require either sticky or transient user activation. + +This API is only available in the window context and not exposed to workers. + +## Properties + +- {{domxref("UserActivation.hasBeenActive")}} {{ReadOnlyInline}} {{experimental_inline}} + - : Indicates whether the current window has sticky user activation. +- {{domxref("UserActivation.isActive")}} {{ReadOnlyInline}} {{experimental_inline}} + - : Indicates whether the current window has transient user activation. + +## Examples + +### Checking if a user gesture was recently performed + +Use {{domxref("UserActivation.isActive")}} to check wether the user is currently interacting with the page ({{Glossary("Transient activation")}}). + +```js +if (navigator.userActivation.isActive) { + // proceed to request playing media, for example +} +``` + +### Checking if a user gesture was ever performed + +Use {{domxref("UserActivation.hasBeenActive")}} to check wether the user has ever interacted with the page ({{Glossary("Sticky activation")}}). + +```js +if (navigator.userActivation.hasBeenActive) { + // proceed with auto-playing an animation, for example +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("navigator.userActivation")}} +- [Features gated by user activation](/en-US/docs/Web/Security/User_activation) diff --git a/files/en-us/web/api/useractivation/isactive/index.md b/files/en-us/web/api/useractivation/isactive/index.md new file mode 100644 index 000000000000000..cfe55e5e9f50625 --- /dev/null +++ b/files/en-us/web/api/useractivation/isactive/index.md @@ -0,0 +1,44 @@ +--- +title: UserActivation.isActive +slug: Web/API/UserActivation/isActive +page-type: web-api-instance-property +tags: + - API + - Property + - Reference +browser-compat: api.UserActivation.isActive +--- + +{{APIRef("HTML DOM")}} {{SeeCompatTable}} + +The read-only **`isActive`** property of the {{domxref("UserActivation")}} interface indicates whether the current window has transient user activation (see {{Glossary("transient activation")}}). + +## Value + +A boolean. + +## Examples + +### Checking if a user gesture was recently performed + +Use the `isActive` property to check wether the user is currently interacting with the page. + +```js +if (navigator.userActivation.isActive) { + // proceed to request playing media, for example +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("UserActivation")}} +- {{domxref("UserActivation.hasBeenActive")}} +- [Features gated by user activation](/en-US/docs/Web/Security/User_activation) diff --git a/files/en-us/web/security/user_activation/index.md b/files/en-us/web/security/user_activation/index.md index d3cf29484ee90bd..ae095dfc96afade 100644 --- a/files/en-us/web/security/user_activation/index.md +++ b/files/en-us/web/security/user_activation/index.md @@ -65,10 +65,18 @@ Examples APIs that require sticky activation: - `navigator.getAutoplayPolicy()` - `navigator.virtualKeyboard.show()` +## 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 - {{Glossary("Transient activation")}} - {{Glossary("Sticky activation")}} +- {{domxref("UserActivation")}} API - [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) {{QuickLinksWithSubpages("/en-US/docs/Web/Security")}} diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 1dd13bbc6ef219c..ba8ff91a59ee2da 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -615,6 +615,7 @@ "PopStateEvent", "PromiseRejectionEvent", "RadioNodeList", + "UserActivation", "ValidityState", "Window" ],