Detecting when a document is “fully active”

When reading the specs for various JavaScript APIs, you might come across the requirement that the document be “fully active” before you can use them. Here’s a definition of what that means from the specs: https://html.spec.whatwg.org/multipage/browsers.html#fully-active

What remains unclear is how to know if the document is fully active or not. As an example, the WakeLock API requires the document to be fully active. If the document is not fully active, then calling “WakeLock.request()” will reject the returned promise with a “NotAllowedError” error object. However, there are other reasons it might return a “NotAllowedError” and does not specify which reason in a given case.

So, how can I proactively determine if a document is fully active before attempting to use APIs that require it?

Answer

There is a section from the page: https://html.spec.whatwg.org/multipage/browsers.html#active-document

A Document d is said to be fully active when d’s browsing context is non-null, d’s browsing context’s active document is d, and either d’s browsing context is a top-level browsing context, or d’s browsing context’s container document is fully active.

Looking to your question:

So, how can I proactively determine if a document is fully active before attempting to use APIs that require it

let’s expand the rules:

  • d’s browsing context is non-null
  • d’s browsing context’s active document is d
  • either d’s browsing context is a top-level browsing context, or d’s browsing context’s container document is fully active

I think that can be translated to that javascript code, but I’m not 100% sure about that:

function isFullyActive(s /* self */) {
    return s.window !== null
    && s.document === s.window.document
    && (s.window.top === s.window || isFullyActive(s.window.parent));
}

// you can use in this way on a top level javascript:
isFullyActive(self)

I didn’t found any API/spec saying about an event or method to check if a document is fully active.

References: