Document UserActivation API (#21285)

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")}}

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")}}

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}}

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)

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)

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)

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)

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")}}

files/jsondata/GroupData.json

@@ -615,6 +615,7 @@
         "PopStateEvent",
         "PromiseRejectionEvent",
         "RadioNodeList",
+        "UserActivation",
         "ValidityState",
         "Window"
       ],