Navigator objectThe 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 implements NavigatorID;
Navigator implements NavigatorLanguage;
Navigator implements NavigatorOnLine;
Navigator implements NavigatorContentUtils;
Navigator implements NavigatorCookies;
Navigator implements NavigatorPlugins;
Navigator implements NavigatorConcurrentHardware;
These interfaces are defined separately so that WorkerNavigator can re-use parts
of the Navigator interface.
[NoInterfaceObject, Exposed=(Window,Worker)]
interface 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.
navigator . appCodeNameReturns the string "Mozilla".
navigator . appNameReturns the string "Netscape".
navigator . appVersionReturns the version of the browser.
navigator . platformReturns the name of the platform.
navigator . productReturns the string "Gecko".
navigator . productSubReturns either the string "20030107", or the string "20100101".
navigator . userAgentReturns the complete `User-Agent` header.
navigator . vendorReturns either the empty string, the string "Apple Computer, Inc.",
or the string "Google Inc.".
navigator . vendorSubReturns the empty string.
appCodeNameMust return the string "Mozilla".
appNameMust return the string "Netscape".
appVersionMust 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".
platformMust 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".
productMust return the string "Gecko".
productSubMust return the appropriate string from the following list:
The string "20030107".
The string "20100101".
userAgentMust return the default `User-Agent`
value.
vendorMust return the appropriate string from the following list:
The string "Google Inc.".
The empty string.
The string "Apple Computer, Inc.".
vendorSubMust return the empty string.
If the navigator compatibility mode is Gecko, then the user agent must also support the following partial interface:
partial interface 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".
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 implementors are strongly urged to include as
little information in this API as possible.
[NoInterfaceObject, Exposed=(Window,Worker)]
interface NavigatorLanguage {
readonly attribute DOMString language;
readonly attribute FrozenArray<DOMString> languages;
};
navigator . languageReturns a language tag representing the user's preferred language.
navigator . languagesReturns 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.
languageMust return a valid BCP 47 language tag representing either a plausible language or the user's most preferred language. [BCP47]
languagesMust 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 return a new set of language tags, the user agent must
queue a task to fire an event named languagechange at the Window or
WorkerGlobalScope object and wait until that task begins to be executed before
actually returning a new value.
The task source for this task is the DOM manipulation task source.
To determine a plausible language, the user agent should bear in mind the following:
en-US" is
suggested; if all users of the service use that same value, that reduces the possibility of
distinguishing the users from each other.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.
registerProtocolHandler() methodSupport: registerprotocolhandlerChrome for Android NoneChrome 13+iOS Safari NoneUC Browser for Android NoneFirefox 3+Samsung Internet NoneIE NoneOpera Mini NoneSafari NoneEdge NoneAndroid Browser NoneOpera 11.6+
Source: caniuse.com
[Exposed=Window,
NoInterfaceObject]
interface NavigatorContentUtils {
void registerProtocolHandler(DOMString scheme, USVString url, DOMString title);
void unregisterProtocolHandler(DOMString scheme, USVString url);
};
The registerProtocolHandler() method
allows Web sites to register themselves as possible handlers for particular schemes. 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]
navigator . registerProtocolHandler(scheme, url, title)Registers a handler for the given scheme, at the given URL, with the given title.
The string "%s" in the 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 the URL.
User agents may, within the constraints described in this section, do whatever they like when the method is called. A UA 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. UAs could provide such a UI through modal UI or through a non-modal transient notification interface. UAs could also simply 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.
The arguments to the method have the following meanings and corresponding implementation requirements. The requirements that involve throwing exceptions must be processed in the order given below, stopping at the first exception thrown. (So the exceptions for the first argument take precedence over the exceptions for the second argument.)
A scheme, such as "mailto" or "web+auth". The
scheme must be compared in an ASCII case-insensitive manner by user agents for the
purposes of comparing with the scheme part of URLs that they consider against the list of
registered handlers.
The scheme value, if it contains a colon (as in "mailto:"),
will never match anything, since schemes don't contain colons.
If the registerProtocolHandler()
method is invoked with a scheme that is neither a safelisted scheme nor a scheme
whose value starts with the substring "web+" and otherwise contains only
ASCII lower alphas, and whose length is at least five
characters (including the "web+" prefix), the user agent must throw a
"SecurityError" DOMException.
The following schemes are the safelisted schemes:
bitcoingeoimircircsmagnetmailtommsnewsnntpopenpgp4fprsipsmssmstosshtelurnwebcalwtaixmppThis list can be changed. If there are schemes that ought to be added, please send feedback.
This list excludes any schemes that could reasonably be expected to be supported
inline, e.g. in an iframe, such as http or (more
theoretically) gopher. If those were supported, they could potentially be
used in man-in-the-middle attacks, by replacing pages that have frames with such content with
content under the control of the protocol handler. If the user agent has native support for the
schemes, this could further be used for cookie-theft attacks.
A string used to build the URL of the page that will handle the requests.
User agents must throw a "SyntaxError" DOMException if
the url argument passed to one of these methods does not contain the exact literal
string "%s".
User agents must throw a "SyntaxError" DOMException if
parsing the url argument relative to the
relevant settings object of this NavigatorContentUtils object is not
successful.
The resulting URL string would by definition not be a valid
URL string as it would include the string "%s" which is not a
valid component in a URL.
User agents must throw a "SecurityError" DOMException
if the resulting URL record has an origin
that differs from the origin specified by
the relevant settings object of this NavigatorContentUtils object.
This is forcibly the case if the %s placeholder is in the
scheme, host, or port parts of the URL.
The resulting URL string is the proto-URL. It identifies the handler for the purposes of the methods described below.
When the user agent uses this handler, it must replace the first occurrence of the exact
literal string "%s" in the url argument with an
escaped version of the absolute URL of the content in question (as defined below),
then parse the resulting URL, relative to the relevant
settings object of the NavigatorContentUtils object on which the registerProtocolHandler() method was
invoked, and then navigate an appropriate browsing
context to the resulting URL.
To get the escaped version of the absolute URL of the content in question, the user agent must replace every character in that absolute URL that is not a character in the URL default encode set with the result of UTF-8 percent encoding that character.
If the user had visited a site at https://example.com/ that made the
following call:
navigator.registerProtocolHandler('web+soup', 'soup?url=%s', 'SoupWeb™')
...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).
A descriptive title of the handler, which the UA might use to remind the user what the site in question is.
This section does not define how the pages registered by this method are used, beyond the requirements on how to process the url value (see above). To some extent, the processing model for navigating across documents defines some cases where these methods are relevant, but in general UAs may use this information wherever they would otherwise consider handing content to native plugins or helper applications.
In addition to the registration method, there is also a method for unregistering handlers.
navigator . unregisterProtocolHandler(scheme, url)Unregisters the handler given by the arguments.
The unregisterProtocolHandler()
method must unregister the handler described by the two arguments to the method, where the first
argument gives the scheme and the second gives the string used to build the URL of
the page that will handle the requests.
The first argument must be compared to the schemes for which custom protocol handlers are registered in an ASCII case-insensitive manner to find the relevant handlers.
The second argument must be preprocessed as described below, and if that is successful, must then be matched against the proto-URLs of the relevant handlers to find the described handler.
The second argument must be preprocessed as follows:
If the string does not contain the substring "%s", abort these
steps. There's no matching handler.
Parse the string relative to the relevant settings
object of this NavigatorContentUtils object. If this fails, then throw a
"SyntaxError" DOMException.
If the resulting URL record's origin
is not the same origin as the origin of the relevant settings
object of this NavigatorContentUtils object, throw a
"SecurityError" DOMException.
Return the resulting URL string as the result of preprocessing the argument.
These mechanisms 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.
Misleading titles. User agents should not rely wholly on the title
argument to the methods when presenting the registered handlers to the user, since sites could
easily lie. For example, a site hostile.example.net could claim that it was
registering the "Cuddly Bear Happy Scheme Handler". User agents should therefore use the handler's
origin in any UI along with any title.
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 Intranet URLs. The mechanism described in this section can result in secret Intranet URLs being leaked, in the following manner:
No actual confidential file data is leaked in this manner, but the URLs themselves could
contain confidential information. For example, the URL could be https://www.corp.example.com/upcoming-aquisitions/the-sample-company.egf, which
might tell the third party that Example Corporation is intending to merge with The Sample Company.
Implementors might wish to consider allowing administrators to disable this feature for 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.
[Exposed=Window,
NoInterfaceObject]
interface NavigatorCookies {
readonly attribute boolean cookieEnabled;
};
navigator . cookieEnabledReturns false if setting a cookie will be ignored, and true otherwise.
The cookieEnabled attribute must
return true if the user agent attempts to handle cookies according to the cookie specification,
and false if it ignores cookie change requests. [COOKIES]
[Exposed=Window,
NoInterfaceObject]
interface NavigatorPlugins {
[SameObject] readonly attribute PluginArray plugins;
[SameObject] readonly attribute MimeTypeArray mimeTypes;
boolean javaEnabled();
};
[Exposed=Window,
LegacyUnenumerableNamedProperties]
interface PluginArray {
void refresh(optional boolean reload = false);
readonly attribute unsigned long length;
getter Plugin? item(unsigned long index);
getter Plugin? namedItem(DOMString name);
};
[Exposed=Window,
LegacyUnenumerableNamedProperties]
interface MimeTypeArray {
readonly attribute unsigned long length;
getter MimeType? item(unsigned long index);
getter MimeType? namedItem(DOMString name);
};
[Exposed=Window,
LegacyUnenumerableNamedProperties]
interface Plugin {
readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString filename;
readonly attribute unsigned long length;
getter MimeType? item(unsigned long index);
getter MimeType? namedItem(DOMString name);
};
[Exposed=Window]
interface MimeType {
readonly attribute DOMString type;
readonly attribute DOMString description;
readonly attribute DOMString suffixes; // comma-separated
readonly attribute Plugin enabledPlugin;
};
navigator . plugins . refresh( [ refresh ] )Updates the lists of supported plugins and MIME types for this page, and reloads the page if the lists have changed.
navigator . plugins . lengthReturns the number of plugins, represented by Plugin objects, that the user agent reports.
navigator . plugins . item(index)navigator . plugins[index]Returns the specified Plugin object.
navigator . plugins . item(name)navigator . plugins[name]Returns the Plugin object for the plugin with the given name.
navigator . mimeTypes . lengthReturns the number of MIME types, represented by MimeType objects, supported by the plugins that the user agent reports.
navigator . mimeTypes . item(index)navigator . mimeTypes[index]Returns the specified MimeType object.
navigator . mimeTypes . item(name)navigator . mimeTypes[name]Returns the MimeType object for the given MIME type.
name
Returns the plugin's name.
description
Returns the plugin's description.
filename
Returns the plugin library's filename, if applicable on the current platform.
lengthReturns the number of MIME types, represented by MimeType objects, supported by the plugin.
item(index)Returns the specified MimeType object.
item(name)Returns the MimeType object for the given MIME type.
type
Returns the MIME type.
description
Returns the MIME type's description.
suffixes
Returns the MIME type's typical file extensions, in a comma-separated list.
enabledPlugin
Returns the Plugin object that implements this MIME type.
navigator . javaEnabled()Returns true if there's a plugin that supports the MIME type "application/x-java-vm".
The navigator.plugins attribute must
return a PluginArray object.
The navigator.mimeTypes attribute must
return a MimeTypeArray object.
A PluginArray object represents none, some, or all of the plugins supported by the user agent, each of which is represented by a Plugin object. Each of these Plugin
objects may be hidden plugins. A can't
be enumerated, but can still be inspected by using its name.
The fewer plugins are represented by the
PluginArray object, and of those, the more that are , the more the user's privacy will be protected. Each exposed plugin
increases the number of bits that can be derived for fingerprinting. Hiding a plugin helps, but
unless it is an extremely rare plugin, it is likely that a site attempting to derive the list of
plugins can still determine whether the plugin is supported or not by probing for it by name (the
names of popular plugins are widely known). Therefore not exposing a plugin at all is preferred.
Unfortunately, many legacy sites use this feature to determine, for example, which plugin to use
to play video. Not exposing any plugins at all might therefore not be entirely plausible.
The PluginArray objects created by a user agent must not be live. The
set of plugins represented by the objects must not change once an object is created, except when
it is updated by the refresh() method.
Each plugin represented by a PluginArray can support a number of
MIME types. For each such plugin, the user agent must
pick one or more of these MIME types to be those that are
explicitly supported.
The explicitly supported MIME types of
a plugin are those that are exposed through the Plugin and MimeTypeArray interfaces. As with plugins themselves, any variation between users regarding what is exposed
allows sites to fingerprint users. User agents are therefore encouraged to expose the same MIME types for all users of a plugin, regardless of the
actual types supported... at least, within the constraints imposed by compatibility with legacy
content.
The supported property indices of a PluginArray object are the
numbers from zero to the number of non- plugins represented by the object, if any.
The length attribute must return the
number of non- plugins
represented by the object.
The item() method of a
PluginArray object must return null if the argument is not one of the object's
supported property indices, and otherwise must return the result of running the
following steps, using the method's argument as index:
Let list be the Plugin objects
representing the non- plugins represented by the PluginArray object.
Return the indexth entry in list.
It is important for privacy that the order of plugins not leak additional information, e.g. the order in which plugins were installed.
The supported property names of a PluginArray object are the values
of the name attributes of all the Plugin objects represented by the PluginArray object.
The namedItem() method of a
PluginArray object must return null if the argument is not one of the object's
supported property names, and otherwise must return the Plugin object, of those represented by the PluginArray
object, that has a name equal to the method's argument.
The refresh() method of the
PluginArray object of a Navigator object, when invoked, must check to
see if any plugins have been installed or reconfigured since the user
agent created the PluginArray object. If so, and the method's argument is true, then
the user agent must act as if the location.reload()
method was called instead. Otherwise, the user agent must update the PluginArray
object and MimeTypeArray object created for attributes of that Navigator
object, and the Plugin and MimeType objects created
for those PluginArray and MimeTypeArray objects, using the same Plugin objects for cases where the name is the same, and the same MimeType objects for
cases where the type is the same, and creating new objects
for cases where there were no matching objects immediately prior to the refresh() call. Old Plugin
and MimeType objects must continue to return the same values that they had prior to
the update, though naturally now the data is stale and may appear inconsistent (for example, an
old MimeType entry might list as its enabledPlugin a Plugin
object that no longer lists that MimeType as a supported MimeType).
A MimeTypeArray object represents the MIME types
explicitly supported by plugins supported by the user
agent, each of which is represented by a MimeType object.
The MimeTypeArray objects created by a user agent must not be live.
The set of MIME types represented by the objects must not change once an object is created, except
when it is updated by the PluginArray object's refresh() method.
The supported property indices of a MimeTypeArray object are the
numbers from zero to the number of MIME types explicitly
supported by non- plugins represented by the corresponding PluginArray object, if
any.
The length attribute must return the
number of MIME types explicitly supported by non- plugins represented by the
corresponding PluginArray object, if any.
The item() method of a
MimeTypeArray object must return null if the argument is not one of the object's
supported property indices, and otherwise must return the result of running the
following steps, using the method's argument as index:
Let list be the MimeType objects representing the MIME types explicitly supported by non- plugins represented by the corresponding
PluginArray object, if any.
Return the indexth entry in list.
It is important for privacy that the order of MIME types not leak additional information, e.g. the order in which plugins were installed.
The supported property names of a MimeTypeArray object are the values
of the type attributes of all the MimeType
objects represented by the MimeTypeArray object.
The namedItem() method of a
MimeTypeArray object must return null if the argument is not one of the object's
supported property names, and otherwise must return the MimeType object
that has a type equal to the method's argument.
A Plugin object represents a plugin. It has
several attributes to provide details about the plugin, and can be enumerated to obtain the list
of MIME types that it explicitly
supports.
The Plugin objects created by a user agent must not be
live. The set of MIME types represented by the objects, and the values of the
objects' attributes, must not change once an object is created, except when updated by the
PluginArray object's refresh()
method.
The reported MIME types for a Plugin object are the
MIME types explicitly supported by the corresponding
plugin when this object was last created or updated by PluginArray.refresh(), whichever happened most
recently.
The supported property indices of a Plugin object
are the numbers from zero to the number of reported MIME types.
The length attribute must return the number
of reported MIME types.
The item() method of a Plugin object must return null if the argument is not one of the
object's supported property indices, and otherwise must return the result of running
the following steps, using the method's argument as index:
Let list be the MimeType objects representing the
reported MIME types.
Return the indexth entry in list.
It is important for privacy that the order of MIME types not leak additional information, e.g. the order in which plugins were installed.
The supported property names of a Plugin object
are the values of the type attributes of the
MimeType objects representing the reported MIME types.
The namedItem() method of a Plugin object must return null if the argument is not one of the
object's supported property names, and otherwise must return the
MimeType object that has a type equal to the
method's argument.
The name attribute must return the
plugin's name.
The description and filename attributes must return user-agent-defined
(or, in all likelihood, plugin-defined) strings. In each case, the same string must
be returned each time, except that the strings returned may change when the PluginArray.refresh() method updates the object.
If the values returned by the description or filename attributes vary between versions of a
plugin, they can be used both as a fingerprinting vector and, even more importantly,
as a trivial way to determine what security vulnerabilities a plugin (and thus a
browser) may have. It is thus highly recommended that the description attribute just return the same value as the
name attribute, and that the filename attribute return the empty string.
A MimeType object represents a MIME type that is, or was,
explicitly supported by a plugin.
The MimeType objects created by a user agent must not be live. The
values of the objects' attributes must not change once an object is created, except when updated
by the PluginArray object's refresh()
method.
The type attribute must return the
valid MIME type with no parameters describing the MIME type.
The description and suffixes attributes must return
user-agent-defined (or, in all likelihood, plugin-defined) strings. In each case, the
same string must be returned each time, except that the strings returned may change when the PluginArray.refresh() method updates the object.
If the values returned by the description or suffixes attributes vary between versions of a
plugin, they can be used both as a fingerprinting vector and, even more importantly,
as a trivial way to determine what security vulnerabilities a plugin (and thus a
browser) may have. It is thus highly recommended that the description attribute just return the same value as the
type attribute, and that the suffixes attribute return the empty string.
Commas in the suffixes attribute are
interpreted as separating subsequent filename extensions, as in "htm,html".
The enabledPlugin attribute must
return the Plugin object that represents the plugin
that explicitly supported the MIME type that this MimeType
object represents when this object was last created or updated by PluginArray.refresh(), whichever happened most
recently.
The navigator.javaEnabled() method
must return true if the user agent supports a plugin that supports the MIME
type "application/x-java-vm"; otherwise it must return false.