≡ webNavigation API
≡ Add-on developer resources
≡ Guides
webNavigation API
Hint
The webNavigation API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.
Use the browser.webNavigation API to receive notifications about the status of navigation requests in-flight.
Permissions
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
webNavigation
Access browser activity during navigation.
Note
The permission webNavigation is required to use messenger.webNavigation.*.
Functions
getAllFrames(details)
– [Added in TB 47]
Retrieves information about all frames of a given tab.
Note
The returned objects do not include the errorOccurred property. See bug 1248418.
Parameters
details
Return type (Promise)
_returns
A list of frames in the given tab, null if the specified tab ID is invalid.
Required permissions
webNavigation
getFrame(details)
– [Added in TB 47]
Retrieves information about the given frame. A frame refers to an <iframe> or a <frame> of a web page and is identified by a tab ID and a frame ID.
Parameters
details
Return type (Promise)
_returns
Information about the requested frame, null if the specified frame ID and/or tab ID are invalid.
frameId
The ID of the frame. 0 indicates that this is the main frame; a positive value indicates the ID of a subframe.
parentFrameId
ID of frame that wraps the frame. Set to -1 of no parent frame exists.
tabId
The ID of the tab in which the frame is.
url
The URL currently associated with this frame, if the frame identified by the frameId existed at one point in the given tab. The fact that an URL is associated with a given frameId does not imply that the corresponding frame still exists.
errorOccurred
True if the last navigation in this frame was interrupted by an error, i.e. the onErrorOccurred event fired.
Required permissions
webNavigation
Events
onBeforeNavigate
– [Added in TB 45]
Fired when a navigation is about to occur.
Note
Filtering is supported from version 50.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Parameters for onBeforeNavigate.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique for a given tab and process.
parentFrameId
ID of frame that wraps the frame. Set to -1 of no parent frame exists.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation is about to occur.
timeStamp
The time when the browser was about to start the navigation, in milliseconds since the epoch.
url
Required permissions
webNavigation
onCommitted
– [Added in TB 45]
Fired when a navigation is committed. The document (and the resources it refers to, such as images and subframes) might still be downloading, but at least part of the document has been received from the server and the browser has decided to switch to the new document.
Note
Filtering is supported from version 50.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Parameters for onCommitted.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation occurs.
timeStamp
The time when the navigation was committed, in milliseconds since the epoch.
transitionQualifiers
A list of transition qualifiers.
transitionType
Cause of the navigation.
url
Required permissions
webNavigation
onCompleted
– [Added in TB 45]
Fired when a document, including the resources it refers to, is completely loaded and initialized.
Note
Filtering is supported from version 50.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Parameters for onCompleted.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation occurs.
timeStamp
The time when the document finished loading, in milliseconds since the epoch.
url
Required permissions
webNavigation
onCreatedNavigationTarget
– [Added in TB 54]
Fired when a new window, or a new tab in an existing window, is created to host a navigation.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Note
If a blocked popup is unblocked by the user, the event is then sent.
Parameters for onCreatedNavigationTarget.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
sourceFrameId
The ID of the frame with sourceTabId in which the navigation is triggered. 0 indicates the main frame.
sourceProcessId
The ID of the process runs the renderer for the source tab.
sourceTabId
The ID of the tab in which the navigation is triggered.
tabId
The ID of the tab in which the url is opened
timeStamp
The time when the browser was about to create a new view, in milliseconds since the epoch.
url
The URL to be opened in the new window.
Required permissions
webNavigation
onDOMContentLoaded
– [Added in TB 45]
Fired when the page’s DOM is fully constructed, but the referenced resources may not finish loading.
Note
Filtering is supported from version 50.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Parameters for onDOMContentLoaded.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation occurs.
timeStamp
The time when the page’s DOM was fully constructed, in milliseconds since the epoch.
url
Required permissions
webNavigation
onErrorOccurred
– [Added in TB 45]
Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation.
Note
Filtering is supported from version 50.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Parameters for onErrorOccurred.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
error
The error description.
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation occurs.
timeStamp
The time when the error occurred, in milliseconds since the epoch.
url
Required permissions
webNavigation
onHistoryStateUpdated
– [Added in TB 47]
Fired when the frame’s history was updated to a new URL. All future events for that frame will use the updated URL.
Parameters for onHistoryStateUpdated.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation occurs.
timeStamp
The time when the navigation was committed, in milliseconds since the epoch.
transitionQualifiers
A list of transition qualifiers.
transitionType
Cause of the navigation.
url
Required permissions
webNavigation
onReferenceFragmentUpdated
– [Added in TB 45]
Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL.
Note
Filtering is supported from version 50.
Note
If the filter parameter is empty, Thunderbird raises an exception.
Parameters for onReferenceFragmentUpdated.addListener(listener, filters)
listener(details)
A function that will be called when this event occurs.
filters
Conditions that the URL being navigated to must satisfy. The ‘schemes’ and ‘ports’ fields of UrlFilter are ignored for this event.
Parameters passed to the listener function
details
frameId
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
processId
The ID of the process runs the renderer for this tab.
tabId
The ID of the tab in which the navigation occurs.
timeStamp
The time when the navigation was committed, in milliseconds since the epoch.
transitionQualifiers
A list of transition qualifiers.
transitionType
Cause of the navigation.
url
Required permissions
webNavigation
onTabReplaced
– [Added in TB 45]
Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.
Note
Although you can add listeners for this event, it will never fire because the underlying functionality is not supported.
Parameters for onTabReplaced.addListener(listener)
listener(details)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
Required permissions
webNavigation
Types
EventUrlFilters
TransitionQualifier
– [Added in TB 48]
Note
‘server_redirect’ is limited to top-level frames and ‘client_redirect’ is not supplied when redirections are created by JavaScript.
TransitionType
– [Added in TB 48]
Cause of the navigation. The same transition types as defined in the history API are used. These are the same transition types as defined in the history API except with “start_page” in place of “auto_toplevel” (for backwards compatibility).
string
Supported values:
auto_bookmark
auto_subframe
Note
Partially supported as the default transition type for subframes.
form_submit
generated
keyword
keyword_generated
link
Note
Partially supported as the default transition type for top-level frames.
manual_subframe
reload
start_page
typed
UrlFilter
– [Added in TB 50]
Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
object
hostContains
Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix ‘foo’, use hostContains: ‘.foo’. This matches ‘www.foobar.com’ and ‘foo.com’, because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix (‘foo.’) and to exactly match against components (‘.foo.’). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.
hostEquals
Matches if the host name of the URL is equal to a specified string.
hostPrefix
Matches if the host name of the URL starts with a specified string.
hostSuffix
Matches if the host name of the URL ends with a specified string.
originAndPathMatches
Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.
pathContains
Matches if the path segment of the URL contains a specified string.
pathEquals
Matches if the path segment of the URL is equal to a specified string.
pathPrefix
Matches if the path segment of the URL starts with a specified string.
pathSuffix
Matches if the path segment of the URL ends with a specified string.
ports
Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.
queryContains
Matches if the query segment of the URL contains a specified string.
queryEquals
Matches if the query segment of the URL is equal to a specified string.
queryPrefix
Matches if the query segment of the URL starts with a specified string.
querySuffix
Matches if the query segment of the URL ends with a specified string.
schemes
Matches if the scheme of the URL is equal to any of the schemes specified in the array.
urlContains
Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.
urlEquals
Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.
urlMatches
Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.
urlPrefix
Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.
urlSuffix
Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.