webNavigation

Get notifications about the various stages of a navigation event.

To use this API you need to have the "webNavigation" permission.

Types

webNavigation.TransitionType: Cause of the navigation.
webNavigation.TransitionQualifier

Functions

webNavigation.getFrame(): 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.
webNavigation.getAllFrames(): Retrieves information about all frames of a given tab.

Events

webNavigation.onBeforeNavigate: Fired when a navigation is about to occur.
webNavigation.onCommitted: 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.
webNavigation.onDOMContentLoaded: Fired when the page's DOM is fully constructed, but the referenced resources may not finish loading.
webNavigation.onCompleted: Fired when a document, including the resources it refers to, is completely loaded and initialized.
webNavigation.onErrorOccurred: 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.
webNavigation.onCreatedNavigationTarget: Fired when a new window, or a new tab in an existing window, is created to host a navigation.
webNavigation.onReferenceFragmentUpdated: Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL.
webNavigation.onTabReplaced: Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.
webNavigation.onHistoryStateUpdated: Fired when the frame's history was updated to a new URL. All future events for that frame will use the updated URL.

	Edge	Firefox	Chrome	Opera
`TransitionQualifier`	?	45.0	Yes	33
`TransitionType`	?	45.0	Yes	33
`getAllFrames`	?	47.0	Yes	33
`getFrame`	?	47.0	Yes	33
`onBeforeNavigate`	?	45.0	Yes	33
`onCommitted`	?	45.0	Yes	33
`onCompleted`	?	45.0	Yes	33
`onCreatedNavigationTarget`	?	No	Yes	33
`onDOMContentLoaded`	?	45.0	Yes	33
`onErrorOccurred`	?	45.0	Yes	33
`onHistoryStateUpdated`	?	47.0	Yes	33
`onReferenceFragmentUpdated`	?	45.0	Yes	33
`onTabReplaced`	?	No	Yes	33

	Firefox
`TransitionQualifier`	48.0
`TransitionType`	48.0
`getAllFrames`	48.0
`getFrame`	48.0
`onBeforeNavigate`	48.0
`onCommitted`	48.0
`onCompleted`	48.0
`onCreatedNavigationTarget`	No
`onDOMContentLoaded`	48.0
`onErrorOccurred`	48.0
`onHistoryStateUpdated`	48.0
`onReferenceFragmentUpdated`	48.0
`onTabReplaced`	No

Chrome incompatibilities

Firefox does not support:
- onCreatedNavigationTarget
- onTabReplaced
- transition types and qualifiers
- Filtering
In Firefox onReferenceFragmentUpdated also triggers for pushState.

Acknowledgements

This API is based on Chromium's chrome.webNavigation API. This documentation is derived from web_navigation.json in the Chromium code.

// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.