1. 8.9 System state and capabilities
      1. 8.9.1 The Navigator object
        1. 8.9.1.1 Client identification
        2. 8.9.1.2 Language preferences
        3. 8.9.1.3 Browser state
        4. 8.9.1.4 Custom scheme handlers: the registerProtocolHandler() method
          1. 8.9.1.4.1 Security and privacy
        5. 8.9.1.5 Cookies

8.9 System state and capabilities

8.9.1 The Navigator object

Navigator

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Window/navigator

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

The navigator attribute of the Window interface must return an instance of the Navigator interface, which represents the identity and state of the user agent (the client), and allows web pages to register themselves as potential protocol handlers:

[Exposed=Window]
interface Navigator {
  // objects implementing this interface also implement the interfaces given below
};
Navigator includes NavigatorID;
Navigator includes NavigatorLanguage;
Navigator includes NavigatorOnLine;
Navigator includes NavigatorContentUtils;
Navigator includes NavigatorCookies;
Navigator includes NavigatorPlugins;
Navigator includes NavigatorConcurrentHardware;

These interface mixins are defined separately so that WorkerNavigator can re-use parts of the Navigator interface.

8.9.1.1 Client identification

NavigatorID

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android12.1+
interface mixin NavigatorID {
  readonly attribute DOMString appCodeName; // constant "Mozilla"
  readonly attribute DOMString appName; // constant "Netscape"
  readonly attribute DOMString appVersion;
  readonly attribute DOMString platform;
  readonly attribute DOMString product; // constant "Gecko"
  [Exposed=Window] readonly attribute DOMString productSub;
  readonly attribute DOMString userAgent;
  [Exposed=Window] readonly attribute DOMString vendor;
  [Exposed=Window] readonly attribute DOMString vendorSub; // constant ""
};

In certain cases, despite the best efforts of the entire industry, web browsers have bugs and limitations that web authors are forced to work around.

This section defines a collection of attributes that can be used to determine, from script, the kind of user agent in use, in order to work around these issues.

The user agent has a navigator compatibility mode, which is either Chrome, Gecko, or WebKit.

The navigator compatibility mode constrains the NavigatorID interface to the combinations of attribute values and presence of taintEnabled() and oscpu that are known to be compatible with existing web content.

Client detection should always be limited to detecting known current versions; future versions and unknown versions should always be assumed to be fully compliant.

self . navigator . appCodeName

Returns the string "Mozilla".

self . navigator . appName

Returns the string "Netscape".

self . navigator . appVersion

Returns the version of the browser.

self . navigator . platform

Returns the name of the platform.

self . navigator . product

Returns the string "Gecko".

window . navigator . productSub

Returns either the string "20030107", or the string "20100101".

self . navigator . userAgent

Returns the complete `User-Agent` header.

window . navigator . vendor

Returns either the empty string, the string "Apple Computer, Inc.", or the string "Google Inc.".

window . navigator . vendorSub

Returns the empty string.

appCodeName

Must return the string "Mozilla".

appName

Must return the string "Netscape".

appVersion

Must return either the string "4.0" or a string representing the version of the browser in detail, e.g. "1.0 (VMS; en-US) Mellblomenator/9000".

platform

Must return either the empty string or a string representing the platform on which the browser is executing, e.g. "MacIntel", "Win32", "FreeBSD i386", "WebTV OS".

product

Must return the string "Gecko".

productSub

Must return the appropriate string from the following list:

If the navigator compatibility mode is Chrome or WebKit

The string "20030107".

If the navigator compatibility mode is Gecko

The string "20100101".

userAgent

NavigatorID/userAgent

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android12.1+

Must return the default `User-Agent` value.

vendor

Navigator/vendor

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera15+Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android14+

Must return the appropriate string from the following list:

If the navigator compatibility mode is Chrome

The string "Google Inc.".

If the navigator compatibility mode is Gecko

The empty string.

If the navigator compatibility mode is WebKit

The string "Apple Computer, Inc.".

vendorSub

Must return the empty string.

If the navigator compatibility mode is Gecko, then the user agent must also support the following partial interface:

partial interface mixin NavigatorID {
  [Exposed=Window] boolean taintEnabled(); // constant false
  [Exposed=Window] readonly attribute DOMString oscpu;
};

The taintEnabled() method must return false.

The oscpu attribute's getter must return either the empty string or a string representing the platform on which the browser is executing, e.g. "Windows NT 10.0; Win64; x64", "Linux x86_64".

(This is a tracking vector.) Any information in this API that varies from user to user can be used to profile the user. In fact, if enough such information is available, a user can actually be uniquely identified. For this reason, user agent implementers are strongly urged to include as little information in this API as possible.

8.9.1.2 Language preferences

NavigatorLanguage

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera4+Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+
interface mixin NavigatorLanguage {
  readonly attribute DOMString language;
  readonly attribute FrozenArray<DOMString> languages;
};
self . navigator . language

Returns a language tag representing the user's preferred language.

self . navigator . languages

Returns an array of language tags representing the user's preferred languages, with the most preferred language first.

The most preferred language is the one returned by navigator.language.

A languagechange event is fired at the Window or WorkerGlobalScope object when the user agent's understanding of what the user's preferred languages are changes.

language

NavigatorLanguage/language

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera4+Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

Must return a valid BCP 47 language tag representing either a plausible language or the user's most preferred language. [BCP47]

languages

NavigatorLanguage/languages

Support in all current engines.

Firefox32+Safari10.1+Chrome37+
Opera24+Edge79+
Edge (Legacy)16+Internet ExplorerNo
Firefox Android32+Safari iOS10.3+Chrome Android37+WebView Android37+Samsung Internet3.0+Opera Android24+

Must return a frozen array of valid BCP 47 language tags representing either one or more plausible languages, or the user's preferred languages, ordered by preference with the most preferred language first. The same object must be returned until the user agent needs to return different values, or values in a different order. [BCP47]

Whenever the user agent needs to make the navigator.languages attribute of a Window or WorkerGlobalScope object global return a new set of language tags, the user agent must queue a global task on the DOM manipulation task source given global to fire an event named languagechange at global, and wait until that task begins to be executed before actually returning a new value.

To determine a plausible language, the user agent should bear in mind the following:

(This is a tracking vector.) To avoid introducing any more fingerprinting vectors, user agents should use the same list for the APIs defined in this function as for the HTTP `Accept-Language` header.

NavigatorOnLine

Support in all current engines.

Firefox1.5+Safari4+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS3.2+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+
caniuse.com table
interface mixin NavigatorOnLine {
  readonly attribute boolean onLine;
};
self . navigator . onLine

Returns false if the user agent is definitely offline (disconnected from the network). Returns true if the user agent might be online.

The events online and offline are fired when the value of this attribute changes.

NavigatorOnLine/onLine

Support in all current engines.

Firefox1.5+Safari4+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS3.2+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android10.1+

The onLine attribute must return false if the user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail), and must return true otherwise.

When the value that would be returned by the navigator.onLine attribute of a Window or WorkerGlobalScope global changes from true to false, the user agent must queue a global task on the networking task source given global to fire an event named offline at global.

On the other hand, when the value that would be returned by the navigator.onLine attribute of a Window or WorkerGlobalScope global changes from false to true, the user agent must queue a global task on the networking task source given global to fire an event named online at the Window or WorkerGlobalScope object.

This attribute is inherently unreliable. A computer can be connected to a network without having Internet access.

In this example, an indicator is updated as the browser goes online and offline.

<!DOCTYPE HTML>
<html lang="en">
 <head>
  <title>Online status</title>
  <script>
   function updateIndicator() {
     document.getElementById('indicator').textContent = navigator.onLine ? 'online' : 'offline';
   }
  </script>
 </head>
 <body onload="updateIndicator()" ononline="updateIndicator()" onoffline="updateIndicator()">
  <p>The network is: <span id="indicator">(state unknown)</span>
 </body>
</html>
8.9.1.4 Custom scheme handlers: the registerProtocolHandler() method

Navigator/registerProtocolHandler

Firefox3+SafariNoChrome13+
Opera11.6+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox AndroidNoSafari iOSNoChrome AndroidNoWebView AndroidNoSamsung InternetNoOpera AndroidNo
caniuse.com table
interface mixin NavigatorContentUtils {
  [SecureContext] undefined registerProtocolHandler(DOMString scheme, USVString url);
  [SecureContext] undefined unregisterProtocolHandler(DOMString scheme, USVString url);
};
window . navigator . registerProtocolHandler(scheme, url)

Registers a handler for scheme at url. For example, an online telephone messaging service could register itself as a handler of the sms: scheme, so that if the user clicks on such a link, they are given the opportunity to use that web site. [SMS]

The string "%s" in url is used as a placeholder for where to put the URL of the content to be handled.

Throws a "SecurityError" DOMException if the user agent blocks the registration (this might happen if trying to register as a handler for "http", for instance).

Throws a "SyntaxError" DOMException if the "%s" string is missing in url.

window . navigator . unregisterProtocolHandler(scheme, url)

Unregisters the handler given by the arguments.

Throws a "SecurityError" DOMException if the user agent blocks the deregistration (this might happen if with invalid schemes, for instance).

Throws a "SyntaxError" DOMException if the "%s" string is missing in url.

The registerProtocolHandler(scheme, url) method steps are:

  1. Let (normalizedScheme, normalizedURLString) be the result of running normalize protocol handler parameters with scheme, url, and this's relevant settings object.

  2. In parallel: register a protocol handler for normalizedScheme and normalizedURLString. User agents may, within the constraints described, do whatever they like. A user agent could, for instance, prompt the user and offer the user the opportunity to add the site to a shortlist of handlers, or make the handlers their default, or cancel the request. User agents could also silently collect the information, providing it only when relevant to the user.

    User agents should keep track of which sites have registered handlers (even if the user has declined such registrations) so that the user is not repeatedly prompted with the same request.

    When the user agent uses this handler for a URL inputURL:

    1. Assert: inputURL's scheme is normalizedScheme.

    2. Let inputURLString be the serialization of inputURL.

    3. Let encodedURL be the result of running UTF-8 percent-encode on inputURLString using the component percent-encode set.

    4. Let handlerURLString be normalizedURLString.

    5. Replace the first instance of "%s" in handlerURLString with encodedURL.

    6. Let resultURL be the result of parsing handlerURLString.

    7. Navigate an appropriate browsing context to resultURL.

    If the user had visited a site at https://example.com/ that made the following call:

    navigator.registerProtocolHandler('web+soup', 'soup?url=%s')

    ...and then, much later, while visiting https://www.example.net/, clicked on a link such as:

    <a href="web+soup:chicken-kïwi">Download our Chicken Kïwi soup!</a>

    ...then the UA might navigate to the following URL:

    https://example.com/soup?url=web+soup:chicken-k%C3%AFwi

    This site could then do whatever it is that it does with soup (synthesize it and ship it to the user, or whatever).

    This does not define when the handler is used. To some extent, the processing model for navigating across documents defines some cases where it is relevant, but in general user agents may use this information wherever they would otherwise consider handing schemes to native plugins or helper applications.

The unregisterProtocolHandler(scheme, url) method steps are:

  1. Let (normalizedScheme, normalizedURLString) be the result of running normalize protocol handler parameters with scheme, url, and this's relevant settings object.

  2. In parallel: unregister the handler described by normalizedScheme and normalizedURLString.


To normalize protocol handler parameters, given a string scheme, a string url, and an environment settings object environment, run these steps:

  1. Set scheme to scheme, converted to ASCII lowercase.

  2. If scheme is neither a safelisted scheme nor a string starting with "web+" followed by one or more ASCII lower alphas, then throw a "SecurityError" DOMException.

    This means that including a colon in scheme (as in "mailto:") will throw.

    The following schemes are the safelisted schemes:

    This list can be changed. If there are schemes that ought to be added, please send feedback.

  3. If url does not contain "%s", then throw a "SyntaxError" DOMException.

  4. Parse url relative to environment.

  5. If that fails, then throw a "SyntaxError" DOMException.

    This is forcibly the case if the %s placeholder is in the host or port of the URL.

  6. If the resulting URL record's scheme is not an HTTP(S) scheme or the resulting URL record's origin is not same origin with environment's origin, then throw a "SecurityError" DOMException.

  7. Assert: the result of Is url potentially trustworthy? given the resulting URL record is "Potentially Trustworthy".

    Because normalize protocol handler parameters is run within a secure context, this is implied by the same origin condition.

  8. Return (scheme, resulting URL string).

    The resulting URL string will by definition not be a valid URL string as it includes the string "%s" which is not a valid component in a URL.

8.9.1.4.1 Security and privacy

Custom scheme handlers can introduce a number of concerns, in particular privacy concerns.

Hijacking all web usage. User agents should not allow schemes that are key to its normal operation, such as an HTTP(S) scheme, to be rerouted through third-party sites. This would allow a user's activities to be trivially tracked, and would allow user information, even in secure connections, to be collected.

Hijacking defaults. User agents are strongly urged to not automatically change any defaults, as this could lead the user to send data to remote hosts that the user is not expecting. New handlers registering themselves should never automatically cause those sites to be used.

Registration spamming. User agents should consider the possibility that a site will attempt to register a large number of handlers, possibly from multiple domains (e.g., by redirecting through a series of pages each on a different domain, and each registering a handler for web+spam: — analogous practices abusing other web browser features have been used by pornography web sites for many years). User agents should gracefully handle such hostile attempts, protecting the user.

Hostile handler metadata. User agents should protect against typical attacks against strings embedded in their interface, for example ensuring that markup or escape characters in such strings are not executed, that null bytes are properly handled, that over-long strings do not cause crashes or buffer overruns, and so forth.

Leaking private data. Web page authors may reference a custom scheme handler using URL data considered private. They might do so with the expectation that the user's choice of handler points to a page inside the organization, ensuring that sensitive data will not be exposed to third parties. However, a user may have registered a handler pointing to an external site, resulting in a data leak to that third party. Implementors might wish to consider allowing administrators to disable custom handlers on certain subdomains, content types, or schemes.

Leaking credentials. User agents must never send username or password information in the URLs that are escaped and included sent to the handler sites. User agents may even avoid attempting to pass to web-based handlers the URLs of resources that are known to require authentication to access, as such sites would be unable to access the resources in question without prompting the user for credentials themselves (a practice that would require the user to know whether to trust the third-party handler, a decision many users are unable to make or even understand).

Interface interference. User agents should be prepared to handle intentionally long arguments to the methods. For example, if the user interface exposed consists of an "accept" button and a "deny" button, with the "accept" binding containing the name of the handler, it's important that a long name not cause the "deny" button to be pushed off the screen.

8.9.1.5 Cookies
interface mixin NavigatorCookies {
  readonly attribute boolean cookieEnabled;
};
window . navigator . cookieEnabled

Returns false if setting a cookie will be ignored, and true otherwise.

Navigator/cookieEnabled

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android12.1+

The cookieEnabled attribute must return true if the user agent attempts to handle cookies according to HTTP State Management Mechanism, and false if it ignores cookie change requests. [COOKIES]