chrome.webNavigation
Description
Use thechrome.webNavigation API to receive notifications about the status of navigation requests in-flight.
Permissions
webNavigationAllchrome.webNavigation methods and events require you to declare the"webNavigation" permissionin theextension manifest. For example:
{"name":"My extension",..."permissions":["webNavigation"],...}Concepts and usage
Event order
For a navigation that is successfully completed, events are fired in the following order:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompletedAny error that occurs during the process results in anonErrorOccurred event. For a specificnavigation, there are no further events fired afteronErrorOccurred.
If a navigating frame contains subframes, itsonCommitted is fired before any of its children'sonBeforeNavigate; whileonCompleted is fired after all of its children'sonCompleted.
If the reference fragment of a frame is changed, aonReferenceFragmentUpdated event is fired. Thisevent can fire any time afteronDOMContentLoaded, even afteronCompleted.
If the history API is used to modify the state of a frame (e.g. usinghistory.pushState(), aonHistoryStateUpdated event is fired. This event can fire any time afteronDOMContentLoaded.
If a navigation restored a page from theBack Forward Cache, theonDOMContentLoaded eventwon't fire. The event is not fired because the content has already completed load when the pagewas first visited.
If a navigation was triggered usingChrome Instant orInstant Pages, a completely loadedpage is swapped into the current tab. In that case, anonTabReplaced event is fired.
Relation to webRequest events
There is no defined ordering between events of thewebRequest API and the events of thewebNavigation API. It is possible that webRequest events are still received for frames that alreadystarted a new navigation, or that a navigation only proceeds after the network resources are alreadyfully loaded.
In general, the webNavigation events are closely related to the navigation state that is displayedin the UI, while the webRequest events correspond to the state of the network stack which isgenerally opaque to the user.
Tab IDs
Not all navigating tabs correspond to actual tabs in Chrome's UI, for example, a tab that is beingpre-rendered. Such tabs are not accessible using thetabs API nor can you request informationabout them by callingwebNavigation.getFrame() orwebNavigation.getAllFrames(). Once such a tabis swapped in, anonTabReplaced event is fired and they become accessible through these APIs.
Timestamps
It's important to note that some technical oddities in the OS's handling of distinct Chromeprocesses can cause the clock to be skewed between the browser itself and extension processes. Thatmeans that thetimeStamp property of theWebNavigation eventtimeStamp property is only guaranteedto beinternally consistent. Comparing one event to another event will give you the correct offsetbetween them, but comparing them to the current time inside the extension (using(new Date()).getTime(),for instance) might give unexpected results.
Frame IDs
Frames within a tab can be identified by a frame ID. The frame ID of the main frame is always 0, theID of child frames is a positive number. Once a document is constructed in a frame, its frame IDremains constant during the lifetime of the document. As of Chrome 49, this ID is also constant forthe lifetime of the frame (across multiple navigations).
Due to the multi-process nature of Chrome, a tab might use different processes to render the sourceand destination of a web page. Therefore, if a navigation takes place in a new process, you mightreceive events both from the new and the old page until the new navigation is committed (i.e. theonCommitted event is sent for the new main frame). In other words, it is possible to have morethan one pending sequence of webNavigation events with the sameframeId. The sequences can bedistinguished by theprocessId key.
Also note that during a provisional load the process might be switched several times. This happenswhen the load is redirected to a different site. In this case, you will receive repeatedonBeforeNavigate andonErrorOccurred events, until you receive the finalonCommitted event.
Another concept that is problematic with extensions is the lifecycle of theframe. A frame hosts a document (which is associated with a committed URL).The document can change (say by navigating) but theframeId won't, and so itis difficult to associate that something happened in a specific document withjustframeIds. We are introducing a concept of adocumentIdwhich is a unique identifier per document. If a frame is navigated and opens anew document the identifier will change. This field is useful for determiningwhen pages change their lifecycle state (between prerender/active/cached)because it remains the same.
Transition types and qualifiers
ThewebNavigationonCommitted event has atransitionType and atransitionQualifiersproperty. Thetransition type is the same as used in thehistory API describing how thebrowser navigated to this particular URL. In addition, severaltransition qualifiers can bereturned that further define the navigation.
The following transition qualifiers exist:
| Transition qualifier | Description |
|---|---|
| "client_redirect" | One or more redirects caused by JavaScript or meta refresh tags on the page happened during the navigation. |
| "server_redirect" | One or more redirects caused by HTTP headers sent from the server happened during the navigation. |
| "forward_back" | The user used the Forward or Back button to initiate the navigation. |
| "from_address_bar" | The user initiated the navigation from the address bar (aka Omnibox). |
Examples
To try this API, install thewebNavigation API example from thechrome-extension-samplesrepository.
Types
TransitionQualifier
Enum
"client_redirect" "server_redirect" "forward_back" "from_address_bar"
TransitionType
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 thehistory API except with"start_page" in place of"auto_toplevel" (for backwards compatibility).
Enum
"link" "typed" "auto_bookmark" "auto_subframe" "manual_subframe" "generated" "start_page" "form_submit" "reload" "keyword" "keyword_generated"
Methods
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
Retrieves information about all frames of a given tab.
Parameters
- details
object
Information about the tab to retrieve all frames from.
- tabId
number
The ID of the tab.
- callback
function optional
The
callbackparameter looks like:(details?: object[]) => void
- details
object[] optional
A list of frames in the given tab, null if the specified tab ID is invalid.
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- errorOccurred
boolean
True if the last navigation in this frame was interrupted by an error, i.e. the onErrorOccurred event fired.
- frameId
number
The ID of the frame. 0 indicates that this is the main frame; a positive value indicates the ID of a subframe.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
The ID of the parent frame, or
-1if this is the main frame. - processId
number
The ID of the process that runs the renderer for this frame.
- url
string
The URL currently associated with this frame.
Returns
Promise<object[] | undefined>
Chrome 93+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
)
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
object
Information about the frame to retrieve information about.
- documentId
string optional
Chrome 106+The UUID of the document. If the frameId and/or tabId are provided they will be validated to match the document found by provided document ID.
- frameId
number optional
The ID of the frame in the given tab.
- processId
number optional
Deprecated since Chrome 49Frames are now uniquely identified by their tab ID and frame ID; the process ID is no longer needed and therefore ignored.
The ID of the process that runs the renderer for this tab.
- tabId
number optional
The ID of the tab in which the frame is.
- callback
function optional
The
callbackparameter looks like:(details?: object) => void
- details
object optional
Information about the requested frame, null if the specified frame ID and/or tab ID are invalid.
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- errorOccurred
boolean
True if the last navigation in this frame was interrupted by an error, i.e. the onErrorOccurred event fired.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
The ID of the parent frame, or
-1if this is the main frame. - url
string
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.
Returns
Promise<object | undefined>
Chrome 93+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
Fired when a navigation is about to occur.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentLifecycleChrome 106+
The lifecycle the document is in.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
The ID of the parent frame, or
-1if this is the main frame. - processId
number
Deprecated since Chrome 50The processId is no longer set for this event, since the process which will render the resulting document is not known until onCommit.
The value of -1.
- tabId
number
The ID of the tab in which the navigation is about to occur.
- timeStamp
number
The time when the browser was about to start the navigation, in milliseconds since the epoch.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
Chrome 74+The ID of the parent frame, or
-1if this is the main frame. - processId
number
The ID of the process that runs the renderer for this frame.
- tabId
number
The ID of the tab in which the navigation occurs.
- timeStamp
number
The time when the navigation was committed, in milliseconds since the epoch.
- transitionQualifiers
A list of transition qualifiers.
- transitionType
Cause of the navigation.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
Fired when a document, including the resources it refers to, is completely loaded and initialized.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
Chrome 74+The ID of the parent frame, or
-1if this is the main frame. - processId
number
The ID of the process that runs the renderer for this frame.
- tabId
number
The ID of the tab in which the navigation occurs.
- timeStamp
number
The time when the document finished loading, in milliseconds since the epoch.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
Fired when a new window, or a new tab in an existing window, is created to host a navigation.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- sourceFrameId
number
The ID of the frame with sourceTabId in which the navigation is triggered. 0 indicates the main frame.
- sourceProcessId
number
The ID of the process that runs the renderer for the source frame.
- sourceTabId
number
The ID of the tab in which the navigation is triggered.
- tabId
number
The ID of the tab in which the url is opened
- timeStamp
number
The time when the browser was about to create a new view, in milliseconds since the epoch.
- url
string
The URL to be opened in the new window.
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
Fired when the page's DOM is fully constructed, but the referenced resources may not finish loading.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
Chrome 74+The ID of the parent frame, or
-1if this is the main frame. - processId
number
The ID of the process that runs the renderer for this frame.
- tabId
number
The ID of the tab in which the navigation occurs.
- timeStamp
number
The time when the page's DOM was fully constructed, in milliseconds since the epoch.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
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.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- error
string
The error description.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
Chrome 74+The ID of the parent frame, or
-1if this is the main frame. - processId
number
Deprecated since Chrome 50The processId is no longer set for this event.
The value of -1.
- tabId
number
The ID of the tab in which the navigation occurs.
- timeStamp
number
The time when the error occurred, in milliseconds since the epoch.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
Fired when the frame's history was updated to a new URL. All future events for that frame will use the updated URL.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
Chrome 74+The ID of the parent frame, or
-1if this is the main frame. - processId
number
The ID of the process that runs the renderer for this frame.
- tabId
number
The ID of the tab in which the navigation occurs.
- timeStamp
number
The time when the navigation was committed, in milliseconds since the epoch.
- transitionQualifiers
A list of transition qualifiers.
- transitionType
Cause of the navigation.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- documentId
string
Chrome 106+A UUID of the document loaded.
- documentLifecycleChrome 106+
The lifecycle the document is in.
- frameId
number
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.
- frameTypeChrome 106+
The type of frame the navigation occurred in.
- parentDocumentId
string optional
Chrome 106+A UUID of the parent document owning this frame. This is not set if there is no parent.
- parentFrameId
number
Chrome 74+The ID of the parent frame, or
-1if this is the main frame. - processId
number
The ID of the process that runs the renderer for this frame.
- tabId
number
The ID of the tab in which the navigation occurs.
- timeStamp
number
The time when the navigation was committed, in milliseconds since the epoch.
- transitionQualifiers
A list of transition qualifiers.
- transitionType
Cause of the navigation.
- url
string
- filters
object optional
- url
Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.
Parameters
- callback
function
The
callbackparameter looks like:(details: object) => void
- details
object
- replacedTabId
number
The ID of the tab that was replaced.
- tabId
number
The ID of the tab that replaced the old tab.
- timeStamp
number
The time when the replacement happened, in milliseconds since the epoch.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-10-15 UTC.